Workflow: Peer Review

This workflow sets out a process in which a typical peer review system may integrate with the ORCID API. It gives a walkthrough of the process of receiving validated ORCID iDs from reviewers, retrieving data from ORCID records, adding peer review groups and review activity to ORCID records, and updating review activities which you have previously added to ORCID records. It is based on version 2.0 of the ORCID message schema. Not every peer review system will fulfil every element of this process—many systems may only collect reviewers’ iDs and display them within your system or in metadata.

Introduction

Peer review is central to the evaluation of research – not just for journal article publication, but also for conference programming, for awarding grants, and for making hiring, promotion, and tenure decisions. Embedding ORCID iDs into your workflows can help streamline your processes, improve the management of people databases, and improve discoverability. And importantly, you can play your part in building a trusted research information infrastructure by asserting the connection between individuals and their peer review activity.

Common integration points for publishing systems:

  1. Before you start: system setup
  2. Collect reviewers’ iDs and biographical information
  3. Display reviewers’ iDs
  4. Connect review activity data to reviewers’ ORCID records
  5. Synchronize your system's data with reviewers' records
  6. Take your system one step further

Before you start: System setup

Please be sure to check that your system meets the requirements below. Additional setup requirements for more advanced integrations can be found in the relevant section(s).

  • Your system must be able to accept and store ORCID iDs together with the researcher’s information.
  • Your system must be able to capture a six-digit authorization code and exchange it for an access token immediately.
  • Your system must also be able to accept and store persistent access tokens together with the researcher’s information. We strongly recommend that you store all of the token response, including refresh tokens, scopes, and token expiry, as these can be useful if access tokens are lost, or if you upgrade your system to support new scopes.
  • Customized interaction messages: We recommend creating at least three messages:
    • Start message: Where researchers initiate the connection process
    • Connection-success message: This message should display on the page the researcher is redirected to after successfully authorizing the connection with your system. It should display their ORCID iD and can also display a thank you or acknowledgement message.
    • Connection-failure message: This message should display on the page the researcher is redirected to after denying authorization to your system. It should give the reasons you requested permission from the researcher and again offer the opportunity to grant permission.
  • Log interactions: Your system should record both calls made to the ORCID API and responses received; this is necessary so our team can help if a problem develops later.

Collect reviewers’ iDs and biographical information

Publishers, funders, research organizations, and other parties organizing reviews can integrate ORCID into peer review workflows to collect authenticated ORCID iDs and to gain permission to update reviewers’ ORCID records, either immediately or in the future. It is critical that you collect ORCID iDs and obtain permission to update reviewers’ ORCID records by requiring users to sign into ORCID from within your system and then retrieving their data from the ORCID Registry using the ORCID API. It is also essential to provide information within your system about why you are collecting ORCID iDs and why this is beneficial to your authors and reviewers.

Examples of peer review organizations who are Collecting iDs include Faculty of 1000 and the American Geophysical Union.

The steps to complete the Collect process are:

Provide a hyperlinked ORCID-branded button for collecting authenticated ORCID iDs: This can be at sign-in, within the author’s personal profile, on the submission form itself, when co-authors confirm their role in a submission, or even in a customized email to a potential author or reviewer. Using the ORCID button consistently helps ensure that researchers associate it with being asked to securely provide their iD, which in turn builds trust in ORCID as a reliable identifier.


Example button graphics and code

Customize the user experience! You can specify a display language, pre-fill the researcher’s name, and include a state parameter which will be returned with the user to your system.

Configure the button’s link to request permissions to the reviewer’s ORCID record: You'll be getting the ORCID iD by obtaining an access token through three-legged OAuth authorization, and this starts with a link customized with your API credentials and scopes that represent the access permissions you're requesting. If you are only planning to collect and display ORCID iDs within your system and review metadata, then you need only /read-limited access to an ORCID record. (If you are using the public API, replace this with /authenticate.)

If you are planning to connect review activity data to ORCID records, then you should request both /read-limited and /activities/update access.

The below example requests permission to read data visible to trusted parties as well as to write activities to ORCID records on the ORCID sandbox. Replace with your client information and paste directly into your web browser to generate an access token for testing (be sure to remove the brackets!).

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited%20/activities/update%20&redirect_uri=[Your landing page]

Obtain access token to get researcher’s ORCID iD: The reviewer signs into their ORCID account and simultaneously authorizes the connection. They are sent back to your landing page—the redirect URI specified in the OAuth link. Appended to the end of that link will be a six-digit authorization code:

https://[Your landing page]?code=gtYn37

At this point, your system’s user interface should display a helpful message to the researcher, e.g. “Thanks for connecting your ORCID iD!” or simply display their iD in full—see Display below.

In the system backend, immediately exchange the authorization code. The authorization code expires upon use.

  URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=[Six-digit code]
    redirect_uri=[Your landing page]

  Example call: 3-legged OAuth 

ORCID will then return the researcher’s validated ORCID iD and an access token:

{"access_token":"c47026d9-90bf-4480-a259-a953bc103495","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138517,
"scope":"/read-limited /activities/update","orcid":"0000-0001-2345-6789","name":"Sofia Garcia"}

If the user denies your system access: ORCID returns the researcher to the specified landing page and attaches an error message:

https://[your landing page]?error=access_denied&error_description=User%20denied%20access 

Your system should read this and automatically direct the researcher to the connection-denied landing page. We strongly recommend that you use this opportunity to explain more fully to the researcher why you are collecting ORCID iDs and requesting permission to access their record, and to prompt them again to sign in and authorize the connection to your system.

Store the token exchange result (ORCID iD, access token, refresh token, scope, scope expiry) in your system in a safe and secure manner. The ORCID iD and access token at a minimum \will be required to perform any action to the user's ORCID record: read, write, update. If you are only requesting /authenticate access, access tokens can be stored to indicate that the iD has been authenticated, and can be used to read public data on ORCID records.

Use the author’s iD and access token to read their ORCID record and populate their profile in your system: Save researchers time by allowing them to quickly and easily transfer data from their ORCID records to your system:

  Method: GET
  Accept: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access token: [Stored access token]
  URL:  https://api.sandbox.orcid.org/v2.0/[ORCID iD]/record
  Example call: GitHub 

Once you have obtained the record data, you can use it to update your system. Our recommended process is by searching the external identifiers for the relevant item, e.g. works, and then querying the identifier source to obtain robust metadata for each item. Alternatively, you can use the put code to read all of the data that was added to the ORCID record for that specific item. See Read data on an ORCID record for more information on reading the ORCID record, and Read ORCID XML 2.0 for more information on interpreting the ORCID message schema.


Display reviewers' iDs

Researchers want to know that using their iD in your system has had some effect. The best way to signal that the collected iD is actually put to use is to display it where their review activity is tracked or attached to their personal profile. This also helps familiarize all researchers with the ORCID iD icon so they recognize it and know to use their own iD in future. An example of a peer review organization displaying reviewers' iDs is Publons.

Including ORCID iDs in metadata and published reviews requires that you have collected validated ORCID iDs from reviewers as described above in Collect. The steps to complete the Display process are:

Display within your system: Once a researcher has connected their ORCID iD to your system, clearly display their iD within their profile and/or on their review so that they know that they have successfully connected and asserted their identity. Format the iD as a hyperlinked URI and include the green iD icon, per our iD Display Guidelines.

ORCID iD iconorcid.org/0000-0001-2345-6789

Display in published reviews: If you publicly circulate and acknowledge reviewers, display the reviewers' ORCID iDs in the published review, formatted as a hyperlinked URI, per our iD Display Guidelines.

Embed ORCID iDs in metadata: If you pass peer review activity to third-party systems, include the reviewer's ORCID iD to recognize their contributions.


Connect peer review activity to ORCID records

Making the connection between iDs and review activity builds trust in digital research information. It enables you to make assertions about the connections between your reviewers and their activity, which benefits you, your users, and the community. When a review is submitted, you can use ORCID to assert the contribution by adding an entry to the Peer Review section of your user’s ORCID record with as much or little detail as appropriate. 

It is possible to acknowledge the full range of peer review contributions, from double blind to open. We follow the CASRAI Peer Review Services data profile developed by the Peer Review Services Working Group.  A citation combines three elements: information about the reviewer, about the organization sponsoring the review, and about the review itself. Each of these components involves a persistent identifier: ORCID iD, group identifier, and review identifier.

Examples of organizations who connect peer review activity to researchers' records include American Geophysical Union and Faculty of 1000. An example of an organization adopting a unique identifier is Publons

Adding information to ORCID records requires that you have collected both ORCID iDs and update permissions as described in Collect above.

System setup:

  • Your system must assign a unique, resolvable review identifier for each peer review activity, used to prevent duplication. This identifier will be displayed in the peer review activity. 
  • Your system must assign a unique group id for each group added to the ORCID Registry. (See "Define the peer review group" below.)
  • Your system must be able to save a put code, a unique identifier for items within the ORCID Registry, for each group and peer review activity added to the ORCID Registry. Every item that is added to the activities section of the ORCID record is returned a put code. If you ever need to read, edit, or delete the review or group you added, you will use the put code.
  • Your system must be able to send data in XML or JSON formatted in the ORCID message schema.

The steps to complete the Connect progress for by adding works to researchers’ ORCID records are listed below. 

Define the peer review group

Before you can add a review activity to an ORCID record, you need to define how it will be displayed and grouped on the record. In the example image above, F1000Research is the peer review group. A basic guide for peer review groups can be found in our GitHub repository

Obtain a token to search and add peer review groups: Use your member API credentials to obtain an access token through two-legged OAuth authentication

  https://sandbox.orcid.org/oauth/token 
  HEADER: accept:application/json
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=client_credentials
    scope=/group-id-record/update
  Example call: GitHub

You will then be returned an access token similar to the following:

{"access_token":"71604efe-6b17-417b-8a9a-ab3e92427674","token_type":"bearer",
"refresh_token":"a267a688-e057-46bb-a78a-b29efe35d91e","expires_in":631138518,
"scope":"/group-id-record/update","orcid":null}

The token returned is long-lived (not expiring for approximately 20 years) and can be used multiple times. 

Search existing peer review groups: As a best practice, your system should use existing group IDs so peer review activity can be grouped on the user's ORCID record as expected. Before creating a new peer review group, search for it on the ORCID Registry by name. The below example searches the Sandbox Registry for the peer review group with the name "F1000Research":

  Method: GET
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/group-id-record?name=F1000Research
  Example call: GitHub

If the peer review group with the same name exists, you will receive an HTTP 200 response. The below example has the group ID with the name "F1000Research" and the group ID "issn:2046-1402": 

HTTP/1.1 200 OK [...] 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<group-id:group-id-record put-code="1006" xmlns:group-id="https://www.orcid.org/ns/group-id" xmlns:common="http://www.orcid.org/ns/common">
    <common:last-modified-date>2015-09-23T16:01:11.244Z</common:last-modified-date>
    <common:created-date>2015-09-18T14:26:34.923Z</common:created-date>
    <group-id:name>F1000Research</group-id:name>
    <group-id:group-id>issn:2046-1402</group-id:group-id>
    <group-id:description>F1000Res Dev. http://dev1r1.f1000ri.com</group-id:description>
    <group-id:type>journal</group-id:type>
    <common:source>
        <common:source-client-id>
            <common:uri>https://sandbox.orcid.org/client/0000-0002-8384-9805</common:uri>
            <common:path>0000-0002-8384-9805</common:path>
            <common:host>sandbox.orcid.org</common:host>
        </common:source-client-id>
        <common:source-name>F1000 Test</common:source-name>
    </common:source>
</group-id:group-id-record>

Store the group id in your system to use for the and proceed to Add the peer review.

If the group ID record is not found in the Registry, add it as follows. 

Format the new group ID record in ORCID message schema: The group ID record must be created in XML or JSON in the ORCID message schema. The XSD and sample XML for for group IDs can be found in our GitHub repository

The group ID must include the following fields (each field is limited to 1000 characters):

  • Name: The name of the group. This can be the name of a journal (Journal of Criminal Justice), a publisher (Society of Criminal Justice), or non-specific description (Legal Journal) as required.
  • Group ID: The group's identifier, formatted as type:identifier, e.g. issn:12345678. This can be as specific (e.g. the journal's ISSN) or vague as required. Valid types include: issn, ringgold, orcid-generated, fundref, publons (contact ORCID if you require a different group ID type)
  • Description: A brief textual description of the group. This can be as specific or vague as required. 
  • Type: One of the specified types: publisher; institution; journal; conference; newspaper; newsletter; magazine; peer-review service (contact ORCID if you require a different peer review type)

Add the group ID record to the ORCID Registry: Use your access token to add your new group ID: 

  Method: POST
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  Data: [link to file or text of a group ID to add]
  URL: https://api.sandbox.orcid.org/v2.0/group-id-record
  Example call: GitHub

Save the returned put code in your system in association with the group ID -- you'll need it later if you need to amend the group IDrecord. Check our troubleshooting page if a different message is returned.

  HTTP/1.1 201 Created [...] 
  Location: https://api.sandbox.orcid.org/v2.0/group-id-record/4321

Add the peer review

Now that you have defined a peer review group, you can use the group ID to create a new peer review activity. 

Format the peer review in ORCID message schema: The review activity must be created in XML or JSON in the ORCID message schema.  Sample XML can be found in our GitHub repository.

At the minimum, the review activity must include the following elements:

  • Role: The individual’s role in the review process, e.g. chair, editor, member, organizer, reviewer.
  • Group identifier: The group ID that is used for aggregation purposes. 
    • Convening organization: This describes the organization which organized the review - a journal publisher, conference organizer, funding agency, faculty, etc.
    • Organization identifier: The persistent identifier for the organization. Whenever possible, this should be a Ringgold identifier or FundRef identifier.
  • Review data: This data refers to the review activity and not what was reviewed.
    • Type: The type of review activity, e.g. review, evaluation.
    • Date: The date the review was completed. This can be broad (2008) or specific (2010-12-10). 
    • Review identifier: A unique, resolvable identifier provided by the source of the review itself. We generally recommend that this not contain identifiable data that can be traced back to the subject of the review. 

We also suggest that you include other data as appropriate, such as:

  • Review URL: A link to a representation of the review or review record online. 
  • Information about the review subject: The thing that the reviewer reviewed.
    • Container name: The name of the main  
    • Subject type: The type of item that was reviewed, e.g. journal article, conference paper. 
    • Subject name: The name of the reviewed item. 
    • Subject external identifier: The unique identifier of the subject of the review, e.g. an article DOI. 
    • Container name: The name of the object of which the review subject is part, e.g. the conference for which the paper was reviewed. 

Add the review activity to the reviewer’s ORCID record: Use the ORCID iD and access token you have stored for the reviewer. The example below adds a review activity to a record on the sandbox server.

  Method: POST
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  Data: [link to file or text of a single review activity to add]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/peer-review
  Example call: GitHub

Save the returned put code in your system in association with the review activity. You'll need this put code to update the review.

  HTTP/1.1 201 Created [...] 
  Location: https://api.sandbox.orcid.org/v2.0/0000-0001-2345-6789/peer-review/739286

Synchronize your systems’ data with reviewers’ ORCID records

Updating reviewers’ profiles within your system to reflect changes in their affiliations or in recognition of other work helps reduce their reporting burden and improves data quality.

Synchronize data between your system and ORCID by automatically updating ORCID records and regularly querying the researcher’s ORCID records for any new changes. This requires persistent (long-term) update tokens. (Premium members can register webhooks to receive pings from ORCID when monitored records are updated.)

Be sure to check the last modified date to find the latest information.

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record  [...]>
  <history:history>
    <common:last-modified-date>2016-11-29T11:29:23.584Z
    </common:last-modified-date>
  </history:history>
  [...]
  Example XML: GitHub

Updating peer review data on an ORCID record

Peer review data added by your system may need to be amended or deleted from researchers’ records or the ORCID Registry. Review activity should be updated as a best practice, rather than deleted and reposted, but there are some cases where deletion is preferable:

Update

Delete

Correcting data, e.g. typos, formatting errors

Activity incorrectly attributed to researcher

Changing the name of a group identifier

Peer review activity incorrectly added as work

Send a call to the API to update using the ORCID iD, access token, the updated peer review activity, and the activity’s put code. Only one activity can be updated at a time.

Format the updated review activity in the ORCID message schema with the changed information, and include the stored put code.

<?xml version="1.0" encoding="UTF-8"?>
<peer-review:peer-review put-code="12345" [...] >
   [...]
</peer-review:peer-review>
  Example XML: GitHub

Add the updated review activity to the ORCID record: The final endpoint must be the corresponding put code of the activity to be updated.

  Method: PUT
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type:  Bearer
  Access token: [Stored access token]
  Data: [Link to file or text of review activity to update]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/peer-review/[put-code]
  Example call: GitHub 

The API will return a 200 OK message to indicate that the activity updated correctly. Check our troubleshooting page if a different message is sent.

Deleting a peer review activity from an ORCID record

Use the ORCID iD, access token, and the work’s put code to delete the review activity. Only one can be deleted at a time.

  Method: DELETE
  Authorization type:  Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/peer-review/[put-code]
  Example call: GitHub 

The API will return a 204 NO CONTENT message to indicate that the item updated correctly. Check our troubleshooting page if a different message is sent.

Updating group identifiers in the ORCID Registry

Send a call to the API to update using the stored access token, the updated group ID, and the ID's put code. Only one group ID record can be updated at a time.

Format the updated group ID record in the ORCID message schema with the changed information, and include the stored put code.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<group-id:group-id-record put-code="<b>2699</b>">
   [...]
</group-id:group-id-record>

  Example XML: GitHub

Add the updated group ID record to the ORCID Registry: The final endpoint must be the corresponding put code of the group ID record to be updated.

  Method: PUT
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access token: [Stored access token]
  Data: [Link to file or text of group ID record to update]
  URL: https://api.sandbox.orcid.org/v2.0/group-id-record/[put-code]
  Example call: GitHub 

The API will return a 200 OK message to indicate that the ID updated correctly. Check our troubleshooting page if a different message is sent.

Deleting a group ID from an ORCID record

The ORCID API will only allow the deletion of a group ID which has no peer review activity associated with it. This is to ensure that there are no floating identifiers associated with peer review activity.

Use the stored access token and the group ID record’s put code to delete the group ID. Only one can be deleted at a time.

  Method: DELETE
  Authorization type: Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/group-id-record/[put-code]
  Example call: GitHub 

The API will return a 204 NO CONTENT message to indicate that the item updated correctly. Check our troubleshooting page if a different message is sent.


Take your system one step further

Besides collecting researchers’ iDs and connecting them with their publications, your system can also:

  1. Create a search & link wizard: Peer review organizations who also curate review databases can create Search & Link wizards to benefit the entire community. These are links from the ORCID Registry user interface which first request researchers’ update permission and then redirect to your system. They require considerable testing between the provider and ORCID. Get in contact with the ORCID Community Team if you are interested in creating a Search & Link wizard.
  2. Add a link to the reviewer's profile within your system: Add a link to your reviewers personal profile under the Websites section of their researcher’s ORCID record. See more on adding personal information such as websites at the Research information and profile systems workflow.