You must be logged into an account to view the generated documentation for each endpoint.

Adding reviews to Publons

The review endpoint allows partners to recognise their reviewers by giving them the option to add their reviews to Publons.

Each successful request sends a co-branded email to the reviewer with information about Publons and a link to receive recognition for the review by adding it to their Publons profile. This endpoint can be configured on a per journal basis to support a variety of peer review work flows ranging from unsigned and hidden to signed and publicly displayed.

Table of Contents

Overview

The Publons API is RESTful and based on requests and responses.

Request

A Review object is used as the root element for all requests. Each request adds a single review record; to add multiple review records multiple requests are required.

Each request must contain an API key in the header. Details are provided here.

Response

A successful request will return a '201 Success' response along with the action taken by Publons and the token the reviewer can use to claim the review. A unsuccessful request will return a '400 Bad Request' response containing a dictionary of errors.

ResponseStatus CodeDescription
Created201 Indicates that the Review object was processed successfully.
Bad Request400 Indicates that the Review object contained errors. The response contains a dictionary of errors.

Example Success Response

This response indicates the review was automatically claimed by the reviewer.

{
  "token": "Y376tgAnMwmAzl5Ii9gT0YHDBj",
  "action": "REVIEWER_CLAIMED"
}

Possible actions

ActionDescription
REVIEWER_UNSUBSCRIBED The reviewer has unsubscribed from Publons.
REVIEWER_EMAILED The reviewer was sent an email with details on how to claim the review.
REVIEWER_CLAIMED The review has been added to the reviewer's profile automatically due to their account preferences.
PARTNER_TO_EMAIL The reviewer should be contacted to claim the review, but the integrating party has disabled this feature. In this case they must contact the reviewer with the token themselves.
DUPLICATE_REVIEW The review was a duplicate, no action was taken.

Example Bad Request Response

{
    "key": ["This field is required."],
    "reviewer": {
        "name": ["This field is required."]
        "email": ["This field is required."]
    },
    "publication": {
        "title": ["This field is required."]
    }
}

Objects

Requests are constructed from JSON objects, starting with a Review object.

Review object

The Review object forms the root of a request. The minimal Review object requires a key to identify the journal and its settings, the reviewer's publishing name and contact email address and the title of the reviewed manuscript.

The object supports many additional fields which can be populated in order to build rich reviewer profiles and ensure reviews are associated with the correct researchers and publications.

NameTypeOptionalDescription
keyStringRequiredA key issued by us to identify the journal and its settings including the branding used when contacting the reviewer and the permission to use for the review.
publicationPublication objectRequiredManuscript that was reviewed.
reviewerAcademic objectRequiredThe reviewer who performed this review.
complete_dateDate objectRequired When the review was submitted. The difference between complete_date and request_date is the time it took the reviewer to perform the review.
request_dateDate objectOptionalWhen the reviewer was first contacted about reviewing.
editorAcademic objectOptionalThe editor responsible for this review.
doiStringOptionalThe Digital Object Identifier for this review.
contentStringOptionalText, Markdown or HTML content of the review.
typeStringOptional The type of review performed. This must either be "pre" for pre-publication reviews or "post" for post-publication reviews (default: "pre").
versionStringOptional Multiple rounds of review are often necessary. The `version` marks the round of review (default: "0").
decisionStringOptional The publication decision resulting from review. This must either be "accept", "reject" or "revisions" (default: "accept").
urlStringOptional If the review is hosted online already Publons will link back to the source of the review.

Examples

For detailed examples see the examples section.

Minimal Review object

The simplest possible request contains the key, reviewer, review date and the publication.

{
    "key": "0123456789abcdef",
    "reviewer":{
        "name": "Reviewer A. B. Name",
        "email": "a@b.com"
    },
    "complete_date": {
            "year": 2014,
            "month": 3
    },
    "publication": {
        "title": "Publication title"
    }
}
Review object with review content
{
    "key": "0123456789abcdef",
    "reviewer":{
        "name": "Reviewer A. B. Name",
        "email": "a@b.com"
    },
    "complete_date": {
            "year": 2014,
            "month": 3
    },
    "publication": {
        "title": "Publication title",
    },
    "content": "Text, Markdown or HTML content of the review."
}

Publication object

Publication objects contains information about the manuscript that was reviewed. The only required field is the title. Additional details assist in associating reviews to existing publications and giving authors richer profiles.

NameTypeOptionalDescription
titleStringRequired The manuscript title.
identifierStringOptional Any internal identifier generated by the publisher. This will remain private; it is used internally to associate multiple reviews with the same article. Should contain revision number if available.
doiStringOptional The publication DOI.
abstractStringOptional The text, HTML or markdown formatted abstract.
submit_dateDate objectOptional The date the publication was submitted.
accept_dateDate objectOptional The date the publication was accepted. If left empty the publication will be marked as not yet accepted.
publish_dateDate ObjectOptional The date the publication was published. If left empty the publication will be marked as not yet published.
authors[Academic Object]Optional A list of the authors of this publication.

Examples

Publication title only
{
    "title": "Publication title"
}
Detailed publication and author information
{
    "title": "Publication title",
    "doi": "10.1000/100000",
    "identifier": "N.0001",
    "submit_date": {
        "year": 2014,
        "month": 3
    },
    "accept_date": {
        "year": 2014,
        "month": 4,
        "day": 25
    },
    "authors": [
        {
            "name": "Reviewer A. B. Name",
            "orcid": "0000-0000-0000-0000",
            "email": "reviewer@university.com",
            "identifier": "P.0000001",
            "affiliations": [
                "Researcher - University"
            ]
        },
        {
            "name": "Reviewer C. D. Name",
            "orcid": "0000-0000-0000-0000"
        }
    ]
}

Academic Object

Academic objects are used for reviewers, editors and authors. For a reviewer the name and email address are required. For editors and authors only the name is required. Additional details assist in ensuring new content is associated with the correct academics and building more detailed profiles.

NameTypeOptionalDescription
nameStringRequired Full publishing name of academic.
emailStringOptional (Required for reviewer) Contact email address of academic.
orcidStringOptional ORCID of the academic.
identifierStringOptional An internal identifier generated by the publisher. This will remain private; it can be used internally to associate multiple publications and reviews to the same academic.
affiliations[String]Optional A list of affiliations for this academic including, potentially, their university or institution.

Examples

Authors and Editors
{
    "name": "Reviewer A. B. Name"
}
Reviewers
{
    "name": "Reviewer A. B. Name",
    "email": "a@b.com"
}
Detailed
{
    "name": "Reviewer A. B. Name",
    "email": "a@b.com",
    "orcid": "0000-0000-0000-0000",
    "identifier": "P.0000001",
    "affiliations": [
        "Researcher - University"
    ]
}

Date Object

Date Objects are flexible and can be specified using their "year", "year and month" or "year, month and day".

NameTypeOptionalDescription
yearIntRequired Year formatted as YYYY.
monthIntOptional Month of year formatted as MM.
dayIntOptional Day of month formatted as DD.

Year only
{"year": 2014}
Full date

{
  "year": 2014,
  "month": 5,
  "day": 3
}

Full examples

Minimal

The minimum review record requires four fields: the integration key, reviewer's name, reviewer's contact email and the title of the publication they reviewed.

Request

{
    "key": "0123456789abcdef",
    "reviewer":{
        "name": "Richard P. Feynman",
        "email": "richard.feynman@institution.com",
    },
    "complete_date": {
            "year": 2014,
            "month": 3
    },
    "publication": {
        "title": "The future of academic research",
    }
}

Detailed

This Review Record contains additional details about the reviewer, the review, the reviewed publication and its authors. Adding these helps Publons create richer profiles for reviewers.

Request

{
    "key": "0123456789abcdef",
    "reviewer":{
        "name": "Reviewer A. B. Name",
        "email": "andrew@publons.com",
        "orcid": "0000-0000-0000-0000",
        "identifier": "P.0000001",
    },
    "complete_date": {
            "year": 2014,
            "month": 3,
            "day": 25
    },
    "publication": {
        "title": "Publication title",
        "doi": "10.1000/100000",
        "identifier": "N.0001",
        "submit_date": {
            "year": 2014,
            "month": 3,
            "day": 25
        },
        "accept_date": {
            "year": 2014,
            "month": 4,
            "day": 25
        },
        "authors": [
            {
                "name": "Author A. B. Name",
                "email": "author@universiry.com",
                "orcid": "0000-0000-0000-0000",
                "identifier": "P.0000001",
                "affiliations": [
                    "Researcher - University",
                ]
            },
            {
                "name": "Author C. D. Name",
                "orcid": "0000-0000-0000-0000"
            }
        ],
        "abstract": "Text, Markdown or HTML abstract.",
    },
    "complete_date": {
        "year": 2014,
        "month": 4,
        "day": 15
    },
    "content": "Text, Markdown or HTML content of the review.",
    "doi": "10.1000/100000",
    "identifier": "N.0001"
}