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
  • Request
  • Response
• Constructing a review
  • Review objects
  • Publication objects
  • Academic objects
  • Date objects
• Examples
  • Minimal
  • Detailed
  • Failed request

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.

Example Success Response

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

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

Possible actions

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.

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.

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.

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".

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"
}