Reviewer Credits API V3 Developer Documentation

Welcome to the Reviewer Credits API V3 documentation. This API enables your application to manage reviewer credits operations for academic journals. It supports multiple endpoints to handle everything from submission proposals and peer review registrations to editorial decisions and reviewer candidate selection.

Note: Most endpoints require the calling user to have a “Journal” role. Authentication is handled via JWT, and the API uses custom filters to modify token behavior. Additionally, all endpoints implement rate limiting (throttling) to prevent abuse.

Note2: Please request a test account by contacting the Reviewer Credits team to test your developments.

Table of Contents

  1. Authentication & Authorization
  2. Rate Limiting
  3. API Endpoints
    3.1. Step #1: Propose a New Submission
    3.2. Step #2: Retrieve Reviewer Candidates
    3.3. Step #3: Select a Reviewer Candidate
    3.4. Step #4: Register Reviewer Acceptance/Decline Decision
    3.5a. Step #5a: Register a Completed Peer Review
    3.5b. Step #5b: Bulk Register Completed Peer Reviews
    3.6. Step #6: Register a Published Submission
    3.7. Register an Editorial Decision
  4. Common Response Formats
  5. Examples
  6. Additional Notes

Introduction

The Reviewer Credits API V3 is designed using industry-standard practices and methodologies, ensuring robust, secure, and scalable integration with academic journal systems. This RESTful API leverages modern authentication techniques such as JWT (JSON Web Tokens) for secure user verification and employs widely recognized rate-limiting strategies (token bucket mechanism) to maintain optimal performance. In addition, our API documentation follows the OpenAPI (Swagger) standard, making it easier for developers to understand, test, and integrate with our services. The endpoints are designed to support common operations in academic publishing—such as managing peer reviews, editorial decisions, submission proposals, and reviewer candidate selection—while adhering to best practices in error handling, response formatting, and data validation.

The Swaggerhub API version 3 Documentation here: https://app.swaggerhub.com/apis/ReviewerCredits/ReviewerCredits/3.0

Download the Postman Collection v2.1 here: https://www.reviewercredits.com/wp-content/uploads/2025/02/RC-API-V3-PROD.postman_collection.zip

Authentication & Authorization

  • JWT Authentication:
    The API uses JWT for authentication. Custom filters modify the token’s expiration and remove unnecessary user data before dispatch.
    • Token Expiration: The token expiration is set to time plus 100 hours. Client should request new token once it is expired.
    • Payload Filtering: The fields user_email, user_nicename, and user_display_name are removed from the JWT payload for security.
  • User Role Check:
    The API endpoints enforce that the current user has a “Journal” role. If the user is not logged in or does not have the proper role, a 401 or 403 error is returned.

Rate Limiting

All API endpoints implement throttling using a token bucket mechanism. If too many requests are made in a short time, the API will throw an exception with HTTP status 429 Too Many Requests. The client should check for this status and retry after the indicated delay.

API Endpoints

The step numbers are suggestions only. Endpoints work regardless of the order.

Step #1: Propose a New Submission

Endpoint: POST /submission/proposal
Description: Proposes a new submission for the reviewer finder.
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
journalTitle string Yes Title of the Journal.
journalContactEmail string Yes Contact email address for the Journal.
originSubmissionId string Yes Field for origin submission ID.
submissionTitle string Yes Title of the submission.
abstract string Yes Abstract text of the manuscript.
platform string Yes Platform identifier for logging.
version string Yes Version identifier for logging.
journalEIssn string No E-ISSN of the Journal.
journalPIssn string No Print ISSN of the Journal.
authorsData string No JSON-encoded object with authors data.
submissionSourceFileURL string No URL to the manuscript source file.
reviewerRegisterLink string No Link for reviewers to register.
reviewerInstructions string No Additional instructions for reviewers.

Successful Response Example:

{
“code”: “rc_200”,
“message”: “Submission proposal successfuly saved. Please save your rcSubmissionId in your DB.”,
“data”: {
“rcSubmissionId”: “proposal_456”
}
}

Step #2: Retrieve Reviewer Candidates

Endpoint: GET /submission/reviewerCandidates
Description: Retrieves reviewer candidates for a given submission.
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
rcSubmissionId string Yes Reviewer Credits Submission ID.
platform string Yes Platform identifier.
version string Yes Version identifier.

Successful Response Example:

{
“code”: “rc_200”,
“message”: “OK”,
“data”: {
“candidateCount”: 2,
“candidates”: [
{
“id”: “23303”,
“name”: “John Smith”,
“email”: “[email protected]”,
“score”: “6.2158”,
“hIndex”: “40”,
“orcid”: “0000-0002-5095-2345”,
“affiliation”: “Quantify Research (Sweden), Stockholm, Sweden”,
“articlesCount”: “124”,
“citationsCount”: “9229”,
“isselected”: null
},
{
“id”: “2304”,
“name”: “Marco Polo”,
“email”: “[email protected]”,
“score”: “4.48318”,
“hIndex”: “42”,
“orcid”: “0000-0003-4274-5454”,
“affiliation”: “Maastricht University, Maastricht, Netherlands”,
“articlesCount”: “349”,
“citationsCount”: “6550”,
“isselected”: null
}
]
}
}

Note: The candidates property is an array of objects. There may be up to 100 number of candidate objects in the array. 

Note2: Email property is filled only for Premium Journals. Please check the journal subscription plans for more details or contact us.

Step #3: Select a Reviewer Candidate

Endpoint: POST /submission/selectCandidate
Description: Selects a reviewer candidate based on their candidate ID.
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
candidateId integer Yes Numeric ID of the candidate.
platform string Yes Platform identifier.
version string Yes Version identifier.

Successful Response Example:

{

  “code”: “rc_200”,

  “message”: “Candidate selection processed successfully.”,

  “data”: {

    “candidateId”: 10

  }

}

Step #4: Register Reviewer Acceptance/Decline Decision

Endpoint: POST /submission/reviewAcceptanceDecision
Description: Registers the reviewer’s acceptance or decline decision.
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
candidateId integer Yes Numeric ID of the candidate.
action string Yes Action taken by the reviewer. Valid values: accepted, declined.
platform string Yes Platform identifier.
version string Yes Version identifier.

Successful Response Example:

{

  “code”: “rc_200”,

  “message”: “Candidate selection processed successfully.”,

  “data”: {

    “candidateId”: 10

  }

}

Step #5a: Register a Completed Peer Review

Endpoint: POST /review/register
Description: Registers a completed peer review.
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
dateCompleted string Yes Date the review was completed (YYYY/MM/DD).
submissionId string Yes Unique submission ID.
reviewerIdentifier string Yes Unique reviewer identifier (email address/ORCID).
reviewerIdentifierType string Yes Type of the reviewer identifier (email or orcid).
dateDue string No Due date of the review (YYYY/MM/DD).
editorName string No Handling editor name.
acceptanceDate string No Acceptance date of the review (YYYY/MM/DD).
recommendation string No Recommendation provided by the reviewer. Acceptable values: accept, decline, major, minor.
wordCount integer No Word count of the review (if tracked).
reviewReport string No Reviewer comments/report text.
email string No Reviewer’s email address (if different from reviewerIdentifier).
firstName string No Reviewer’s first name.
lastName string No Reviewer’s last name.
rejectedByEditor boolean No Whether the review was later rejected by the editor.

Successful Response Example:

{

  “code”: “rc_200”,

  “message”: “Review registered successfully.”,

  “data”: {

    “reviewId”: 123

  }

}

Step #5b: Bulk Register Completed Peer Reviews (Bulk)

Endpoint: POST /review/register/bulk
Description: Registers multiple completed peer reviews in a single request. The bulk request is validated and then processed asynchronously using a background job. This is intended for high-volume integrations (e.g., nightly exports of completed reviews).
Required Role: Journal

Processing model:

  • The endpoint validates all reviews in the request.
  • Reviews that pass validation are queued for asynchronous processing.
  • Reviews that fail validation are skipped.
  • If all reviews fail validation, the request is rejected with a 400 error and structured validation details.
  • A notification email is sent when the bulk processing is completed.

 

Request Body Parameters:

Top-Level Request Body

Parameter Type Required Description
reviews array Yes Array of peer review objects to register in bulk. Minimum 1, maximum 1000 items per request.
platform string No Platform identifier for logging (e.g., ojs, editorial-manager).
version string No Integration/version identifier for logging (e.g., 1.0.0, plugin-2.1).


Note:

  • The API-level argument validation enforces non-empty array and maximum 1000 reviews per request.
  • If more than 1000 objects are provided in reviews, the request is rejected with HTTP 400.

Review Object Fields (Each Item in reviews)

Each entry in the reviews array has the same structure as the single-review endpoint (POST /review/register), plus support for an optional rating field.

Parameter Type Required Description
dateCompleted string Yes Date the review was completed, format YYYY/MM/DD.
submissionId string Yes Unique submission ID in the journal’s system. Maximum length: 128 characters.
reviewerIdentifier string Yes Unique reviewer identifier (e.g., email address or ORCID).
reviewerIdentifierType string Yes Type of the reviewer identifier. Valid values: email, orcid (case-sensitive, stored in lowercase).
dateDue string No Due date of the review (YYYY/MM/DD).
editorName string No Handling editor’s name. Maximum length: 256 characters.
acceptanceDate string No Date the review invitation was accepted (YYYY/MM/DD).
recommendation string No Recommendation provided by the reviewer. Valid values: ACCEPT, DECLINE, MAJOR, MINOR (must match exactly as shown).
wordCount integer No Word count of the review, if tracked. Must be a non-negative integer.
reviewReport string No Reviewer comments/report text. Maximum length: 2048 characters.
email string No Reviewer’s email address (if different from reviewerIdentifier). Maximum length: 256 characters.
firstName string No Reviewer’s first name.
lastName string No Reviewer’s last name.
rejectedByEditor boolean No Whether the review was later rejected by the editor.
rating integer No Rating given to the review (if used by the journal). Must be an integer between 1 and 5 (inclusive).

Date validation:
dateCompleted, dateDue, and acceptanceDate are validated against the YYYY/MM/DD format. Invalid dates will cause the corresponding review to fail validation.

 

Success response if at least 1 review is valid:

{
“code”: “rc_200”,
“message”: “Bulk review registration started”,
“data”: {
“message”: “8 valid reviews are being processed. 2 reviews were skipped due to validation errors. You will be notified via email once the processing is complete.”,
“total_reviews”: 10,
“valid_reviews”: 8,
“skipped_reviews”: 2,
“status”: “processing”
}
}

If no reviews were skipped (all valid):

 
{
“code”: “rc_200”,
“message”: “Bulk review registration started”,
“data”: {
“message”: “Your bulk review registration request has been received and is being processed. You will be notified via email once the processing is complete.”,
“total_reviews”: 5,
“valid_reviews”: 5,
“status”: “processing”
}
}

Step #6: Register a Published Submission

Endpoint: POST /submission/published
Description: Registers a published submission.
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
decisionDate string Yes The date of the decision (YYYY/MM/DD).
manuscriptId string Yes Unique submission ID.
paperTitle string Yes Title of the submission.
published boolean No Whether the submission was published.
rejected boolean No Whether the submission was rejected.
workType string No Type of the submission (MANUSCRIPT, MONOGRAPH, or CONFERENCE_CONTRIBUTION).
peerReviewPrivacyType string No Peer review privacy type (OPEN, SINGLE, or DOUBLE).

Successful Response Example:

{

  “code”: “rc_200”,

  “message”: “Published submission successfully saved.”,

  “data”: {

    “publishedSubmissionId”: “abc123”

  }

}

Register an Editorial Decision

Endpoint: POST /submission/registerEditorDecision
Description: Registers an editorial decision (e.g., send to a new review round, accept/decline submission).
Required Role: Journal

Request Body Parameters:

Parameter Type Required Description
journalTitle string Yes Title of the journal.
submissionId string Yes Submission ID in the journal’s system.
editorialDecision string Yes Decision type. Acceptable values: accept, decline, major, minor.
editorEmail string No Email of the editor.
editorialDecisionDate string No Date of the editorial decision (YYYY/MM/DD).
round integer No Round number for the decision.
stage string No Stage of the editorial process.
editorFullName string No Full name of the editor.
editorOrcid string No ORCID of the editor, if available.
editorCountry string No Editor’s country.

Successful Response Example:

{
“code”: “rc_200”,
“message”: “Editorial decision successfully saved.”,
“data”: {}
}

Common Response Formats

Success Response

A successful API call returns a JSON object with:

  • code: A string code (e.g., rc_200).
  • message: A short message (e.g., OK).
  • data: An object containing the relevant data (e.g., review ID, candidate list, etc.).

Error Response

When an error occurs, the API returns a JSON object containing:

  • code: A string error code (e.g., rc_400, rc_404, or rc_429).
  • message: A description of the error.
  • data: An object containing details such as HTTP status and any error messages.

Example error response:

{
“code”: “rc_400”,
“message”: “Invalid date format. Should be (YYYY/MM/DD).”,
“data”: {
“status”: 400,
“errors”: null
}
}

Additional Notes

  • Rate Limiting:
    Clients should be prepared to handle HTTP 429 responses and retry after the indicated time.
  • Data Validation:
    The API performs validation on several parameters (e.g., date formats, allowed enumeration values). Make sure your request payload adheres to the expected format.
  • Logging:
    API calls are logged for debugging and analytics purposes. Check with your system administrator if you need details on these logs.
  • Extensibility:
    The API is built to be extended. Future changes (such as adding new roles or additional endpoints) will follow similar patterns as documented here.