You must be signed 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 and send an email to the reviewer with a link to securely sign up and associate the review with their profile. 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.

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.
editorAcademic objectOptionalThe editor responsible for this review.
request_dateDate objectOptionalWhen the reviewer was first contacted about reviewing.
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.
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 and the publication.

{
    "key": "0123456789abcdef",
    "reviewer":{
        "name": "Reviewer A. B. Name",
        "email": "a@b.com"
    },
    "publication": {
        "title": "Publication title"
    }
}
Review object with review content
{
    "key": "0123456789abcdef",
    "reviewer":{
        "name": "Reviewer A. B. Name",
        "email": "a@b.com"
    },
    "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.
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.
identifierStringOptional Any internal identifier generated by the publisher. This will remain private; it is used internally to associate multiple reviews with the same article.
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",
    },
    "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",
    },
    "publication": {
        "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": "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"
}

Failed request

Request

{}

Response

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