Basic Tutorial: Add and Update Data on an ORCID Record (3.0+)

You can help make life easier for your users by connecting validated information to their ORCID records. You will also be helping to build trust in scholarly communications and, by keeping that data up to date, you can reduce the reporting burden for your users and improve data quality. 

This tutorial will walk you through adding information to an ORCID record, formatting data per the ORCID message schema, and updating or deleting data that you have previously added to an ORCID record. It is based on version 3.0 of the ORCID message schema.

You will require Member API credentials for the sandbox testing server, as well as a testing record on the ORCID sandbox, in order to test adding and updating items to the ORCID record. Check our Getting started guide to learn how to get credentials and a testing ORCID record. The text in bold in each example should be replaced with your own credentials, ORCID iD, and system responses. The access tokens from this process allow you to add a single item (or multiple works) at once, as well as edit or delete a single item at once. Multiple scopes can be requested at one time.

Contents


Get permission to update records

The process to get permission to add or update data on a user’s ORCID record follows the OAuth Dance as described in Tokens through 3-legged OAuth Authorization. The user starts in your local system, which refers them to a customized authorization URL. The URL includes your client information, as well as the scopes specifying the specific areas of their record that you wish to access. After signing in, the user authorizes the connection with your system and is returned to your landing page (redirect URI) along with an authorization code that you’ll use to get their ORCID iD along with an access token valid for the requested scopes.

Build the authorization link

Choose which of the supported update scopes work for your system (a full list of scopes, descriptions, and request methods are available in our GitHub repository):


Scope

Description

/person/update

Update biographical data—the left column of the ORCID record user interface.

  • Other names by which the researcher is known
  • Identifiers representing the researcher in your system
  • Keywords related to the researcher and their work
  • The researcher’s country or region
  • Links to the researcher’s personal or profile pages

/activities/update

Update research activity data—the right column of the ORCID record user interface.

  • Education affiliations
  • Employment affiliations
  • Funding activities
  • Research works (output)
  • Peer review activities
  • Research resource
  • Researcher URLS
  • Service
  • Qualifications
  • Membership
  • Distinctions
  • Invited positions
 

The example below requests permission to add and update research activities on the ORCID sandbox testing server. Replace the bracketed data 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=/activities/update&redirect_uri=[Your landing page]

Exchange the authorization code for an ORCID iD and access token

Using your testing record, sign in and authorize the connection. You will be redirected to your specified Redirect URI specified with a six-digit authorization code appended to the end:

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

Immediately exchange the authorization code for the ORCID iD and access token. The authorization code expires upon use.

 URL=https://sandbox.orcid.org/oauth/token

  HEADER: Accept: application/json

  METHOD: POST

  DATA: 

    client_id=Your client ID

    client_secret=Your client secret

    grant_type=authorization_code

    code=Six-digit code

    redirect_uri=Your landing page

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

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",

"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,

"scope":"/activities/update","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

The access token returned will be long-lived, expiring approximately 20 years after issue unless revoked by your system or by the user.

Format the data

Before you can add an item to the ORCID record you will need to create it. Format your data in the ORCID message schema in XML or JSON. Sample XML files for creating new items on the ORCID record and reading existing items on the ORCID record are available in our GitHub repository.

We also recommend that you validate your data against our XSD. The XSD for all sections of the ORCID record are available in our GitHub repository.

Add an item to an ORCID record

Now that you’ve formatted the data and collected the ORCID iD and access token, make an HTTP POST request to the record, specifying the relevant endpoint.



Endpoint

Required scope

Description

/external-identifiers

/person/update

Identifiers representing the researcher in your system

/keywords

Keywords related to the researcher and their work

/other-names

Other names by which the researcher is known

/address

The researcher’s country or region

/researcher-urls

Links to the researcher’s personal or profile pages

/education

/activities/update

Education affiliations

/employment

Employment affiliations

/funding

Funding activities

/peer-review

Peer review activities

/work

Research works (single)

/works

Research works (multiple)

/research-resource

Research resources

/service

Services

/qualification

Qualification

/membership

Membership

/distinction

Distinction

/invited-position

 

Invited Position

 

The call below adds a new employment affiliation to a record on the sandbox testing 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 single employment item to add

  URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment

  Example call: GitHub

The API will return a 201 Created message to indicate that the item posted correctly, along with the item’s put code. (In the case of posting bulk works, the API will return a 200 OK message.) Check our troubleshooting page if a different message is returned. You will need to save the put code to make any updates or remove the item.

Update an item on the ORCID record 

It’s good practice to keep information that you’ve added to ORCID records up to date. Update an item that you have added previously by making an HTTP PUT request along with the ORCID iD, stored access token, and stored put code—be sure to include the put code for the item in your formatted XML or JSON.  Only one item can be updated at a time, and you can only update items added by your client.

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

 <?xml version="1.0" encoding="UTF-8"?> 

    <employment:employment put-code="739288" [...]>

    [...]    

  </employment:employment>

Call the API:

 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 affiliation to update

  URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288

  Example calls: GitHub

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

Delete an item on an ORCID record 

If you have added data that later needs to be deleted, for example, if it has been associated with the wrong ORCID iD, then you can make an HTTP DELETE request along with the ORCID iD, stored access token, and stored put code. Only one item can be deleted at a time, and you can only delete items added by your client.

 Method: DELETE

  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/v3.0/[ORCID iD]/employment/739288

  Example call: GitHub

ORCID inbox notifications

Users receive a notification in their ORCID inbox whenever there is a change in data on an ORCID record. The notification includes basic information about the change: the name of the client performing the update, date of change, the section of the ORCID record that was updated, and the item that was changed. See our user Knowledge Base for more about notifications.  There will be one notification in the ORCID Inbox for each API call. An API call adding or updating a single activity will result in one notification in the Inbox. A call to the end point for bulk adding works will also result in one notification in the Inbox, listing the first 20 items that were added.

ORCID records on the sandbox also have functioning inboxes. We recommend regularly looking through the inboxes of your testing ORCID records when planning how your systems will schedule data updates.