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. For publishers, funders, peer review recognition organizations, and others, 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.
This guide is designed for members who are integrating ORCID peer review functionality into their systems and processes. It gives an overview of how peer review integrations may qualify for each element of the Collect & Connect program, introduces the new aspects of version 2.0 of the ORCID API – the version which supports peer review, gives example of peer review XML and API calls, and offers suggestions for planning your communications campaign to announce your peer review integration with the ORCID Registry.
- Collecting ORCID iDs & Connecting peer review activity to ORCID records
- ORCID peer review API
- Letting everyone know: communications planning
Organizations facilitating and tracking peer review activity - including publishers and third-party peer review recognition groups - can collect authenticated ORCID iDs for peer reviewers at the point in which an individual submits their review of a work or claims previous peer review activity.
To qualify for the ORCID Collect badge, you need to:
- Collect and store authenticated ORCID iDs for peer reviewers that work with you, either on a voluntary or mandatory basis, to ensure that iDs are entered without typos, and the user you are interacting with owns the iD and approves its use. You may also collect and store the permission access tokens to read, add to and/or update individuals’ ORCID records
- Provide an ORCID-branded button for collecting authenticated ORCID iDs to create a consistent user experience and help associate the iD icon with a trusted process for reviewers
- Explain the benefits of using an ORCID iD to enable foster understanding of why you are collecting this information
- Explain the benefits of including ORCID iDs at your site to demonstrate the broader benefits of ORCID in your organization or sector
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.
To qualify for the ORCID Display badge, in addition to the items under Collect, your system must:
- Store and publicly display iDs on your website(s) and within metadata anywhere that the reviewer’s name would appear – e.g. recognition lists, review displays, communications to those for whom the review was performed (if applicable) – to signal to your users and the community that your system is plumbed to support their use of ORCID
- Display the ORCID iD linked with the iD icon, following ORCID guidelines to create a consistent user experience and help associate the iD icon with a trusted process making assertions about an individual’s contributions
- Use the ORCID member logo on any web pages that describe your system's connection to ORCID to demonstrate your support for ORCID (contact the ORCID CES team to obtain the ORCID member logo)
- Explain why you collect iDs and how this benefits your users to enable them to understand why you are collecting this information
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.
Recognize upcoming and past peer review activity on the ORCID Record
To qualify for the ORCID Connect badge, in addition to the items under Collect and Display, your system must:
- Ingest public/shared information from ORCID records to auto-populate forms to save users time, eliminate errors caused by manual entry
- AND/OR -
- Request permissions to update the reviwer's ORCID record to assert the connection between your users and their contributions. Your integrating system may store long-lived permissions, so that individuals only need to give you permission once to benefit from their record being updated by your organization
- IN BOTH CASES -
- Explain the benefit of your system's connection with ORCID and how they benefit the researcher
- Adopt internally a unique reference identifier to represent the recognized peer review activity (n.b. this identifier does not need to have meaning outside of your own systems)
Learn how to connect peer review activity to ORCID records in the Peer Review API section below. Examples of organizations who are Connecting peer review activity to researchers' records include the American Geophysical Union and Faculty of 1000. An example of an organization adopting a unique identifier is Publons.
Synchronizing information between your system and reviewers’ ORCID records helps reduce the reporting burden for them – and you – and improves data quality for everyone. It helps achieve the goal of “Enter once, reuse often”.
To qualify for the ORCID Synchronize badge, in addition to the items under Collect, Display, and Connect, your system must:
- Create bidirectional information flow (synchronization) between your system and ORCID
- AND/OR -
- Create a search & link wizard available on your site and/or in the ORCID Registry to enable reviewers to add their pass review activities to their ORCID record (contact the ORCID CES team for more information)
- AND/OR -
- Automatically update ORCID records with information from your system after obtaining the reviewer’s permission
- AND -
- Explain the benefits of synchronization to your users
Learn more about synchronizing ORCID records with your system at ORCID API: Enabling automatic updates.
This section provides basic information on how to develop and test the peer review functionality in the ORCID Registry. If you have not used the ORCID API before, we suggest you start by reviewing our general API documentation.
Below is an image of how peer review looks in a researcher’s ORCID record:
- Ensure that group(s) that you will be adding peer review activity to already exist on the site; add them if they do not already exist.
- Initiate permission with the user to get permission to add/update items on their ORCID record; store their ORCID iD and the access token for future use.
- Use the peer review API to add new peer review activities to add to the user’s ORCID record.
- Store the resulting put code along with each peer review activity in your local database in case you need to later update the the activity.
Example files and tutorials for adding peer review groups and activities can be found at the ORCID GitHub.
Peer review is only available in 2.0 release candidate versions of the ORCID API Schema – the current stable release candidate is v3.
2.0 includes major updates from earlier versions of the ORCID API, including:
- A single scope to grant access to all activities on a record. (Previously different scopes were needed to access the affiliations, funding, and works sections of a record.)
- POST commands must be used for creating new items and PUT commands can only be used to update existing items. (Previously PUT commands could also be used to add new items.)
- Single item interactions using put codes. Each call to the API will only affect one item on an ORCID record and that item is referenced by it’s put code. (Earlier versions allowed multiple items to be read, edited, or updated with a single command.) Be sure to save the put code for each new item!
- Division of the ORCID XSD into multiple parts.
There are two components to the API for peer review:
- The general peer review schema, for describing peer review activity, and
- The groups schema, for specifying the organization, conference, journal or other classification that you would like to list the peer review activity under.
The designation of groups allows you to pre-define how peer review activity will be displayed in researchers’ ORCID records.
See the Groups API guide at the ORCID GitHub for more information. At present, only approved ORCID members can add groups as the peer-review functionality is still in development. Contact the ORCID CES team to have your credentials enabled to add groups.
Peer review schema
The ORCID peer review schema for the latest stable 2.0 release candidate (rc3) is at ORCID GitHub. Be aware that the schema could change with later release candidate versions – watch rc3 for the version actively in development.
You may also find an additional guide at the ORCID GitHub (rc3).
Below is a sample XML document using this schema:
<?xml version="1.0" encoding="UTF-8"?> <peer-review:peer-review visibility="private" xmlns:common="http://www.orcid.org/ns/common" xmlns:peer-review="http://www.orcid.org/ns/peer-review" xmlns:work="http://www.orcid.org/ns/work" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.orcid.org/ns/peer-review ../peer-review-2.0_rc1.xsd "> <peer-review:reviewer-role>reviewer</peer-review:reviewer-role> <peer-review:review-identifiers> <work:work-external-identifier> <common:external-identifier-url>http://www.wellcome.ac.uk/Funding/Biomedical-science/Application-information/Committees/WTP059408.htm</common:external-identifier-url> <common:relationship>self</common:relationship> <work:external-identifier-type>source-work-id</work:external-identifier-type> <work:external-identifier-id>WTP059408</work:external-identifier-id> </work:work-external-identifier> </peer-review:review-identifiers> <peer-review:review-url>http://www.wellcome.ac.uk/Funding/Biomedical-science/Application-information/Committees/WTP059408.htm</peer-review:review-url> <peer-review:review-type>review</peer-review:review-type> <peer-review:review-completion-date> <common:year>2014</common:year> </peer-review:review-completion-date> <peer-review:review-group-id>ringgold:5072</peer-review:review-group-id> <peer-review:convening-organization> <common:name>Wellcome Trust</common:name> <common:address> <common:city>London</common:city> <common:region>London</common:region> <common:country>GB</common:country> </common:address> <common:disambiguated-organization> <common:disambiguated-organization-identifier>5072</common:disambiguated-organization-identifier> <common:disambiguation-source>ringgold</common:disambiguation-source> </common:disambiguated-organization> </peer-review:convening-organization> </peer-review:peer-review>
|Read a summary of peer review activities||/read-limited||GET||https://api.sandbox.orcid.org/v2.0_rc3/[ORCID]/activities|
|Read a single peer review activity||/read-limited||GET||https://api.sandbox.orcid.org/v2.0_rc3/[ORCID]/peer-review/[PUT-CODE]|
|Add a peer review activity||/activities/update||POST||https://api.sandbox.orcid.org/v2.0_rc3/[ORCID]/peer-review|
|Update an existing peer review activity||/activities/update||PUT||https://api.sandbox.orcid.org/v2.0_rc3/[ORCID]/peer-review/[PUT-CODE]|
Example URL to grant access
https://sandbox.orcid.org/oauth/authorize?\ client_id=APP-NPXKK6HFN6TJ4YYI&\ response_type=code&\ scope=/read-limited /activities/update&\ redirect_uri=https://developers.google.com/oauthplayground
Example CURL call to exchange an authorization code for an access token (this call remains the same from earlier versions)
curl -i -L -H "Accept: application/json" \ --data "client_id=APP-NPXKK6HFN6TJ4YYI&\ client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97&\ grant_type=authorization_code&code=G900Cz&\ redirect_uri=https://developers.google.com/oauthplayground" \ "https://sandbox.orcid.org/oauth/token"
Example CURL call to read a summary of activities on a record
curl -L -i -H "Content-Type: application/orcid+xml" \ -H "Authorization: Bearer 1cd499e3-3f93-4437-8a0d-d183b02e994c" \ "https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-9227-8514/activities"
Example CURL call to read a peer review item
curl -L -i -H "Content-Type: application/orcid+xml" \ -H "Authorization: Bearer 1cd499e3-3f93-4437-8a0d-d183b02e994c" \ "https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-9227-8514/peer-review/1006"
Example CURL call to add a new peer review activity
curl -H "Content-Type: application/vnd.orcid+xml" \ -H "Authorization: Bearer 1cd499e3-3f93-4437-8a0d-d183b02e994c" \ -d "@peer.xml" \ -X POST "https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-9227-8514/peer-review"
Example CURL call to update a peer review activity
curl -H "Content-Type: application/vnd.orcid+xml" \ -H "Authorization: Bearer 1cd499e3-3f93-4437-8a0d-d183b02e994c" \ -d "@/XML/peer.xml" \ -X PUT "https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-9227-8514/peer-review/1006"
Letting the world know: communications planning
Please help us help both you and those who will be adopting peer review functionality after you by:
- Keeping us updated on your progress: what’s going well, what you’re struggling with, your launch date and rollout plans
- Working with us once you’re ready to launch to get the good news about your implementation out to your own stakeholders, to the ORCID community, and beyond
- Being willing to share your experiences of setting up peer review functionality with others, for example, through contributing updates to the ORCID blog or by helping us build use cases which others can benefit from