Basic tutorial: Add and update data on an ORCID record

You can help make life easier for your users by connecting validated information to their ORCID records—and 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 2.1 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

  1. Get permission to update records
  2. Format the data
  3. Add an item to the ORCID record
  4. Update an item on the ORCID record
  5. Delete an item on the ORCID record
  6. ORCID inbox notifications

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

The below example 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 the 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)

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/v2.1/[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/v2.1/[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 the ORCID record

If you have added data that 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/v2.1/[ORCID iD]/employment/739288
  Example call: GitHub

ORCID inbox notifications

How do users find out information has been added, updated, or deleted on their record? They receive a notification in their ORCID inbox. Whenever there is a change in data on an ORCID record, the user receives a notification with basic information about the change, including the name of the client performing the update, date of change, and section of the ORCID record that was updated. See our user Knowledge Base for more about notifications.  

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. 

Questions? Comments?

Let us know – we're always happy to help.