API Tutorial: Add and Update data on an ORCID record

You can request sandbox Member API credentials to build and test your application. These credentials allow you to make calls to the sandbox premium member API to read, write to, and update ORCID records. Access to the sandbox testing environment is freely available to anyone, even if you’re not an ORCID member organization.

Note: If you are using an ORCID certified service provider systemthat already supports ORCID, you do not need to register for sandbox API credentials unless you wish to try out the ORCID integration functionality within the Sandbox envrionment. 

The sandbox lets you create test user accounts and develop your integration without having to worry about affecting data on the live (production) ORCID Registry. The sandbox behaves the same way as the production ORCID Registry with a few exceptions.

Creating a test account

In order to test the ORCID API and API calls, such as a reading and adding information to an ORCID record, you will also need to create a test ORCID record in the sandbox. This can be done through the user interface, much like on the production ORCID Registry. Go to https://sandbox.orcid.org/register and register for an account.

Mailinator email addresses

The sandbox server only sends emails to Mailinator (@mailinator.com) email addresses in order to not spam mail servers unintentionally. You will not receive a verification email or password reset notification unless you use a @mailinator.com address, and verification is required in order to make any manual edits to sandbox records. Find out more about their free to use public inboxes here. If you do not wish to use a Mailinator address, then please make note of your username and password (as you will be using them to grant authorization to your application when testing), and contact us to request assistance with verification.

Mailinator is an email service that has a public free service and a private paid service. For testing you can use the completely free public service. Find out more about their tiers here.

Mailinator is a third party service that is not managed or maintained by ORCID. We recommend that you review how this service works and its limitations before using these addresses.

There are two different update scopes – one for biographical details, the other for activities.

ORCID integrations use “3 legged OAuth” to authenticate users and request permission to interact with their records. Any integration can ask for read permissions using the Public API. ORCID members can use the Member API to ask for update permissions. It works like this:

• You create a special link
• When clicked, the user is sent to ORCID
  • ORCID asks the user to sign in
  • ORCID asks the user to grant permission to your application
  • ORCID sends the user back to your system with an authorization code
• Your system exchanges that code for an access token

The customized authorization URL includes your client information, as well as the ‘scopes’ that specify 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 along with an authorization code. This code is then used to get their ORCID iD along with an access token valid for the requested scopes.

Build the authorization link and get and authorization code

You build your authorization link by specifying your API credentials’ client ID and associated landing page (redirect URI). You choose which permissions to ask for by setting the scope parameter.

The below example requests permission to read limited-access data on the ORCID sandbox testing server. In the real world you display this link on your website, or include it in an email when asking the user to authenticate and authorize. However, for testing purposes you can simply paste it into your web browser. Replace the bracketed data with your client information and be sure to remove the square brackets!

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

One the user has clicked the link, signed in at ORCID and granted permissions they are redirected back to your site, like this:

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

Exchange the authorization code for an ORCID iD and access token

You should immediately exchange the authorization code for the ORCID iD and access token. The authorization code expires upon use. The request looks like this and cannot be made in a web browser, it must be made by your server.

 URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  HEADER: Content-Type: application/x-www-form-urlencoded
  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 in JSON format:

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

Access tokens are long lived by default and expire 20 years after issue. The token can be used multiple times before it expires.

Use the access token

3-legged access tokens are linked to specific ORCID record. To use them, you include them in API requests you make to read or update that record.

When requesting permission to interact with an ORCID user’s record, you specify one or more ‘scopes’. Each scope allows you to do certain things, such as read the record, or update a particular section.

3-legged (authorization code) scopes

3 legged refers to the three actors involved in obtaining permission from a user; ORCID, your system and the user themselves.

/authenticate

This scope is used to collect the ORCID iD and read public information on the record only. All other 3-legged scopes include the authenticate permission, so this scope can be omitted if asking for any other access. This scope is available on the Member or Public API.

/read-limited (Member API only)

This scope is used to get access to read public and limited visibility items on an ORCID record. This scope is only available on the Member API.

/activities/update (Member API only)

This scope is used to write, update and delete items in the affiliation, funding, works, professional activities, research resources and peer-review sections of an ORCID record. This scope is only available on the Member API.

/person/update (Member API only)

This scope is used to write, update and delete items in the other-names, keywords, countries, researcher-urls, websites, and personal external identifiers sections of the record. This scope is only available on the Member API.

openid

This scope is used by OpenID integrators when an id_token is required. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user. This scope is available on the public and member API.

Please note that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification. Please see our OpenID documentation for more information.

Multiple scopes

Multiple scopes can be requested in a single interaction by listing the scopes in the authenticate URL with an encoded space between each, such as scope=/read-limited%20/activities/update%20/person/update

Complete access

If you want full access to read and edit a record include three scopes in your authenticate URL: /read-limited, /activities/update and /person/update. In the URL they would appear as scope=/read-limited%20/activities/update%20/person/update

2-legged (client credential) scopes

For some activities you do not have to ask the user for permission. Two legged OAuth scopes are requested directly from the ORCID API and do not require the researcher to grant permission. Tokens with these scopes are valid for 20 years and can be reused

/read-public

This scope is used to read public information on a single ORCID iD,search for ORCID records or to read summary information (member API only). This scope is available on the Member or Public API.

/webhook

This scope allows a client application to register a webhook on an ORCID record, in order to receive notifications when a record is updated. This scope is available to premium ORCID members only.

Items (works, employment, funding, peer review etc) can be added to an ORCID record using the ORCID member API. To do this, you must first obtain permission from the researcher using OAuth and format the item metadata using the ORCID message schema.

Once you have formatted the data and collected the ORCID iD and access token, you make an API request using HTTP POST, specifying the relevant endpoint.

Method: POST 
Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [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

The call below adds a new employment affiliation to a record on the sandbox testing server:

<?xml version="1.0" encoding="UTF-8"?>      
<employment:employment [...]>     
[...]            
</employment:employment>

Example call: Github

The API will return a 201 message to indicate that the item posted correctly, along with the item put code. Your client will be listed as the source of the item.

Check our troubleshooting page if a different message is returned. You will need to save the  store the put code and access token to make any updates or remove the item.

An ORCID record may contain information about a researcher’s work, affiliations, funding, peer review, and more.

Items on ORCID records can be broken down into assertions that connect the ORCID iD-holder with an activity or affiliation. These assertions can be added to an ORCID record by the researcher who owns the record, or by systems the researcher has granted permission to do so.  We call the entity that added an assertion to an ORCID record the source.

Examples

Following our principles of transparency and openness, we believe it is important to be able to see the source of the assertion — who is adding that information to the record.  Here is how we do that:

1. When a researcher (or their delegated trusted individual) adds an assertion to their record, ORCID automatically records that person as the source
2. When a system approved by the researcher adds an assertion to a record, ORCID automatically records the system owner (an ORCID member) as the source.

We display the source name in the user interface and make it available (with its unique identifier) in the API:

However, research information workflows can be more complicated than this, and the real source of an assertion can be unintentionally obscured by one system adding an item on behalf of a person or another system. To ensure transparency, we need to distinguish between who made the connection between the person and the item, and who added the item to the record.  As above, whoever adds the item to the ORCID record is the source; whoever creates the connection between the ORCID iD and the item is the assertion origin.

For example:

1. A researcher imports data into their ORCID record from a system, such as a Search and Link wizard. The researcher is making the assertion connecting their iD with the item, so they are the assertion origin; while the system is the entity adding the assertion to the ORCID record — the source
2. A researcher interacts with System A (the assertion origi), which uses services provided by System B to update ORCID records, making System B the source

We encourage our community to engage in taking steps to preserve and share information on assertion origin, so that everyone can benefit from seeing the source.

For more information, please see:

• Assertion Assurance Pathways: What Are They and Why Do They Matter?
• Plans for Enabling Multiple Assertions in the ORCID Registry

ORCID members can update information they’ve previously added to an ORCID record. Only one item can be updated at a time, and it can only be updated using the client credentials that created it in the first place.

To facilitate updating, make sure you store the put code and access token when creating items.

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+jsonnAuthorization type and Access token: Bearer [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.

All items (apart from the biography text) on an ORCID record have a put code:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>   
<record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>      
<funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">   [...] 
</record:record>

This put code can be used to make a call to the API to retrieve the full data for an item. The following items can be queried using a put code:

Using the section endpoint and put code, you can call the API using your same access token to get that specific item in full. This example call retrieves the full funding item 4413 in XML format using the member API on the sandbox server.

Method: GET Accept: application/vnd.orcid+xml Authorization type and Access token: Bearer [stored access token]URI: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/funding/4413

Example call: GitHub

The API will return a 200 OK message to indicate that the message was received successfully and return the full XML of the funding item:

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
    <funding:funding put-code="4413" path="/0000-0002-9227-8514/funding/4413" visibility="public"  [...] >
    [...] 
    </funding:funding>

You can check the source of an item when reading it if you want to know who added it.

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 specifying the relevant endpoint, 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. You can delete items even when the user has revoked permission.

This example call deletes the employment item with the put code “739288” from a record”

Method: DELETE 
Content-type:  application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288

Example call: GitHub

Please see our list of supported identifiers for the V3.0 API. We occasionally add new types at the request of ORCID members who would like to use them when adding items to the registry.

ORCID supports the use of  ROR identifiers, GRID identifiers and Crossref Funder Registry identifiers to disambiguate organizations in ORCID records. 

For more information, see Working with Organization Identifiers

Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info

Works in ORCID are grouped together based on both their identifiers and those identifiers‚ relationship to the work. There are four types of relationships:

• Self: the identifier refers solely to that work and can be grouped with other works that have the same identifier
• Part of: the work is part of this identifier and cannot be grouped with other works
• Version of: these identifiers apply to alternate versions of the work and can be grouped with self and version of identifiers
• Funded by: these identifiers apply to the funding for the work. These identifiers are not used for grouping works.

Our API provides support for this in the XSD. Each item has a display index attribute which indicates its rank within its group. The highest display index is the preferred item selected by the researcher. Items added via the API which have not been ranked by the researcher have a display index of 1 and are used as the default preferred source within the group until changed by the researcher. The display index also determines the work order when reading the ORCID record with the API.

For more information regarding grouping on ORCID records, please see our support article.

Visibility indicates the privacy setting of the item, based on the user’s set visibility preference. If a visibility tag is included when information is posted via the API, it will be ignored. Rather, the information will be posted per the user’s default visibility preference as set in their account preferences.

Public items can be read by anyone via the API and are shown on the researcher’s public record, Trusted party items are only returned via the API to clients who have read-limited access; they are not on the researcher’s public record. Private items are visible only to the researcher and the source of the item – the only private items returned via the API are those which were added to the record via your integration More about visibility settings in the ORCID Registry.

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 the item in 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.