API

Invitations

An invitation asks one reviewer from a search to review one article. Scholvet delivers it, collects the answer and tells you.

Lifecycle

An invitation starts as pending and moves to exactly one final state.

status	Meaning
`pending`	Waiting for the reviewer. Ends at respondBy.
`accepted`	The reviewer accepted. Their identity is now included and dueAt is set.
`declined`	The reviewer declined. declineReason tells you why.
`expired`	No answer before respondBy.
`cancelled`	You withdrew the invitation.
`completed`	You confirmed the completed review.

Create an invitation

POST /v1/invitations

Invites a reviewer from one of your searches. Returns 201 Created with the invitation.

Request body

Field	Type	Description
`searchId` required	`uuid`	The search the reviewer code came from. It must not have expired.
`reviewerCode` required	`string`	A reviewerCode from that search.
`externalRef`	`string`	Your own identifier for the invitation, up to 80 characters. Returned in every response and webhook.
`articleTitle` required	`string`	Title shown to the reviewer, up to 600 characters.
`articleAbstract`	`string`	Abstract shown to the reviewer, up to 4,000 characters.
`message`	`string`	A personal note from the editor, up to 2,000 characters.
`respondByDays`	`integer`	Days the reviewer has to answer, 1 to 30. Default 7.
`reviewDays`	`integer`	Days for the review after acceptance, 1 to 90. Default 21.

Request

curl -X POST https://api.scholvet.com/v1/invitations \
  -H "X-Api-Key: $SCHOLVET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": "0b4f6c1e-5c1a-4a7e-9d0f-7f1c2a9e3b55",
    "reviewerCode": "SV-7KQ2MX4P",
    "externalRef": "your-invitation-881",
    "articleTitle": "Deep learning for tumour detection in brain MRI",
    "articleAbstract": "We evaluate convolutional neural networks...",
    "message": "We would value your opinion on this manuscript.",
    "respondByDays": 7,
    "reviewDays": 21
  }'

Response · 201 Created

{
  "invitationId": "6d8da67a-2bc0-4c8e-b8c9-e9831c02f746",
  "externalRef": "your-invitation-881",
  "articleRef": "JMIR-2026-0104",
  "reviewerCode": "SV-7KQ2MX4P",
  "status": "pending",
  "createdAt": "2026-10-28T09:20:11Z",
  "respondBy": "2026-11-04T09:20:11Z",
  "respondedAt": null,
  "dueAt": null,
  "completedAt": null,
  "declineReason": null,
  "reviewer": null
}

Besides validation errors, creating an invitation can fail with:

404 search_not_found — The search does not exist or belongs to another journal.
409 search_expired — The search is older than 30 days. Search again.
422 reviewer_not_in_search — The reviewer code is not a result of that search.
409 reviewer_unavailable — The reviewer was already invited for this article, or is no longer available (capacity, leave or a new conflict of interest).
402 overage_cap_reached — The overage cap of your institution is reached; no new invitations this period.

The invitation object

Every invitation endpoint and webhook returns this object.

Field	Type	Description
`invitationId` required	`uuid`	Identifier of the invitation.
`externalRef`	`string \| null`	Your externalRef, if you sent one.
`articleRef` required	`string`	The articleRef of the search.
`reviewerCode` required	`string`	The reviewer's code for your journal.
`status` required	`string`	pending, accepted, declined, expired, cancelled or completed.
`createdAt` required	`date-time`	When you sent the invitation.
`respondBy` required	`date-time`	Deadline for the answer.
`respondedAt`	`date-time \| null`	When the reviewer answered.
`dueAt`	`date-time \| null`	Deadline for the review: answer time plus reviewDays.
`completedAt`	`date-time \| null`	When the review was completed, as you confirmed it.
`declineReason`	`string \| null`	Reason for a decline.
`reviewer`	`object \| null`	fullName, email, orcid, academicTitle and institution. Present only when the status is accepted or completed.

Example · accepted

{
  "invitationId": "6d8da67a-2bc0-4c8e-b8c9-e9831c02f746",
  "externalRef": "your-invitation-881",
  "articleRef": "JMIR-2026-0104",
  "reviewerCode": "SV-7KQ2MX4P",
  "status": "accepted",
  "createdAt": "2026-10-28T09:20:11Z",
  "respondBy": "2026-11-04T09:20:11Z",
  "respondedAt": "2026-10-29T07:02:45Z",
  "dueAt": "2026-11-19T07:02:45Z",
  "completedAt": null,
  "declineReason": null,
  "reviewer": {
    "fullName": "Ayşe Demir",
    "email": "[email protected]",
    "orcid": "0000-0001-5109-3700",
    "academicTitle": "Prof. Dr.",
    "institution": "Ankara University"
  }
}

Values of declineReason:

busy — I am too busy right now
out_of_scope — Outside my expertise
conflict_of_interest — Conflict of interest
other — Other

List invitations of an article

GET /v1/invitations?articleRef={articleRef}

Returns your invitations for one articleRef, newest first (up to 100). Useful to rebuild state if a webhook was missed.

Request

curl "https://api.scholvet.com/v1/invitations?articleRef=JMIR-2026-0104" \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Get an invitation

GET /v1/invitations/{invitationId}

Returns one invitation. 404 invitation_not_found if it does not exist or belongs to another journal.

Request

curl https://api.scholvet.com/v1/invitations/6d8da67a-2bc0-4c8e-b8c9-e9831c02f746 \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Cancel an invitation

POST /v1/invitations/{invitationId}/cancel

Withdraws a pending or accepted invitation and tells the reviewer. Other states answer 409 invalid_status.

Request

curl -X POST https://api.scholvet.com/v1/invitations/6d8da67a-2bc0-4c8e-b8c9-e9831c02f746/cancel \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Confirm a completed review

POST /v1/invitations/{invitationId}/completion

Marks an accepted invitation as completed. Other states answer 409 invalid_status.

Request body

Field	Type	Description
`accepted` required	`boolean`	true if the review was acceptable; false if it was not usable.
`qualityRating`	`integer`	Editor's rating of the review, 1 to 5.
`completedAt`	`date-time`	When the review was submitted. Defaults to now; a value in the future or before acceptance is ignored.

Request

curl -X POST https://api.scholvet.com/v1/invitations/6d8da67a-2bc0-4c8e-b8c9-e9831c02f746/completion \
  -H "X-Api-Key: $SCHOLVET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accepted": true, "qualityRating": 4, "completedAt": "2026-11-15T16:40:00Z" }'

Reviewers earn recognition points only through this call, never on their own word. Points depend on punctuality and your rating, are held for 30 days and are not awarded for reviews for the reviewer's own institution or beyond six per journal in a year.

Next: Registering reviewers →