Writing peer review items

The task of writing peer review is very similar to writing works and funding, i.e.,

  • a batch file containing information to be written to ORCID records, together with the email or ORCID iD of the researcher/contributors to be affected, is uploaded to the Hub.
  • the Hub then either sends the people identified email invitations and/or uses the access tokens it already has to write the information to their ORCID records.

As with all complex objects passed through the Hub, peer review requires a structured file format such as the json or YAML formats to convey.

The main difference between peer review and other complex ORCID objects is that to assert peer review requires the pre-registration of a peer review group for the peer review to belong to. As a best practice, you should use existing group IDs (so peer review activity can be grouped on the user’s ORCID record as expected) before creating a new one. To search for the existence of a peer review group requires the use of the ORCID API. Until we’ve built the search feature of the Hub, let us know the group’s name and we’ll () run the search for you.

If you do need to create a new peer review group this can be accomplished from the ‘/Settings/GroupId Record’ page available to Organisation Administrators. Select ‘Create’, and you’ll be able to specify:

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)

Once saved, from the ‘/Settings/GroupId Record’ page, select the group you’ve just created and the click ‘With selected’ > ‘Insert or Update record’. As soon as the record shows a put code, the group’s “Group Id” can be referred to in a peer-review file.

NB: you only need to do this once for each peer review group.

The Hub accepts batches of peer review items where each item contains an initial invitees block (detailing the names, email, and optionally ORCID iD and put-code for each individual to be affected) and following that invitee block, the data to be written to each invitee’s ORCID record. The peer review data must comply with the structure of the ORCID V2.0/V2.1 peer review schema, but omit put-code. If the task describes an update to existing information in a users ORCID record the put-code will not apply to all invitees; instead specify each put-code in the data of the relevant invitee:

[{"invitees":[{invitee1}, {invitee2}, ...], peer review},{"invitees":[{invitee4}, {invitee5}, ...], peer review2}, ...]

Example files can be found here: Example peer review task in json and Example peer review task in yaml, while any uploaded peer review file will be validated against the peer_review_schema.yaml.

For more information and guidance on the structure expected of peer review task files see here: Peer review schema for ORCID API 2.0/2.1 For an overview of peer review in ORCID see here: Workflow: Peer Review

Example peer review task in json

Show/Hide Code
	"invitees": [
			{"identifier":"00001", "email": "[email protected]", "first-name": "Alice", "last-name": "Contributor 1", "ORCID-iD": "0000-0002-9207-4933", "put-code": null, "visibility": null},
			{"identifier":"00002", "email": "[email protected]", "first-name": "Bob", "last-name": "Contributor 2", "ORCID-iD": null, "put-code": null, "visibility": null}],
	"reviewer-role": "REVIEWER",
	"review-identifiers": {
		"external-id": [{
			"external-id-type": "source-work-id",
			"external-id-value": "1212221",
			"external-id-url": {
				"value": "https://localsystem.org/1234"
			"external-id-relationship": "SELF"
	"review-url": {
		"value": "https://alt-url.com"
	"review-type": "REVIEW",
	"review-completion-date": {
		"year": {
			"value": "2012"
		"month": {
			"value": "08"
		"day": {
			"value": "01"
	"review-group-id": "issn:12131",
	"subject-external-identifier": {
		"external-id-type": "doi",
		"external-id-value": "10.1087/20120404",
		"external-id-url": {
			"value": "https://doi.org/10.1087/20120404"
		"external-id-relationship": "SELF"
	"subject-container-name": {
		"value": "Journal title"
	"subject-type": "JOURNAL_ARTICLE",
	"subject-name": {
		"title": {
			"value": "Name of the paper reviewed"
		"subtitle": {
			"value": "Subtitle of the paper reviewed"
		"translated-title": {
			"language-code": "en",
			"value": "Translated title"
	"subject-url": {
		"value": "https://subject-alt-url.com"
	"convening-organization": {
		"name": "The University of Auckland",
		"address": {
			"city": "Auckland",
			"region": "Auckland",
			"country": "NZ"
		"disambiguated-organization": {
			"disambiguated-organization-identifier": "385488",
			"disambiguation-source": "RINGGOLD"

You can download example_peer_reviews.json here.

Example peer review task in yaml

Show/Hide Code
- invitees:
  - identifier: '00001'
    email: [email protected]
    first-name: Alice
    last-name: Contributor 1
    ORCID-iD: 0000-0002-9207-4933
    put-code: null
    visibility: null
  - identifier: '00002'
    email: [email protected]
    first-name: Bob
    last-name: Contributor 2
    ORCID-iD: null
    put-code: null
    visibility: null
  reviewer-role: REVIEWER
    - external-id-type: source-work-id
      external-id-value: '1212221'
        value: https://localsystem.org/1234
      external-id-relationship: SELF
    value: https://alt-url.com
  review-type: REVIEW
      value: '2012'
      value: '08'
      value: '01'
  review-group-id: ringgold:9999999999
    value: Journal title
    external-id-type: doi
    external-id-value: 10.1087/20120404
      value: https://doi.org/10.1087/20120404
    external-id-relationship: SELF
  subject-type: JOURNAL_ARTICLE
      value: Name of the paper reviewed
      value: Subtitle of the paper reviewed
      language-code: en
      value: Translated title
    value: https://subject-alt-url.com
    name: The University of Auckland
      city: Auckland
      country: NZ
      disambiguated-organization-identifier: '385488'
      disambiguation-source: RINGGOLD

You can download example_peer_reviews.yaml here.


Any peer review task file that is uploaded is first validates against the current peer_review_schema.yaml:

Show/Hide Code

You can download peer_review_schema.yaml here.