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.5. Step #5: Register a Completed Peer Review
    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 #5: 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 #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.