API Tutorial: Read Data on a Record

We recommend that developers test the Public API in the sandbox testing server before using the production version. Below are the steps on how to register for public API credentials in both the Sandbox and Production environments.

• Sign into your ORCID record:
  Production server: https://orcid.org/signin
  Sandbox testing server: https://sandbox.orcid.org/signin
• Click on your name in the top right hand corner
• Click Developer Tools from the menu option
  Note: In order to access Developer Tools, you must verify your email address. If you have not already verified your email address, you will be prompted to do before you can register for public API credentials
• Read and agree to the ‘ORCID Public APIs Terms of Service
• Click the “Register for ORCID Public API Credentials” button.

Completing the Application Details Form

• Once you have registered for your Public API Credentials you will be directed back to Developer Tools (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• You need to complete the application details form presented to register a new application.
  • Name: The name of your application. This will be displayed to users when they grant your application permission to get their ORCID iD, and it will be displayed in their Trusted organization list. We recommend using the name of your organization or service (e.g. a journal name).
  • Application URL: The website the user can visit to learn more about your application. This will also be displayed in their Trusted organization list.
  • Application Description: Information about the application that you are developing and how you will use the user’s ORCID iD. This will be displayed to users on the OAuth screen.

Adding Redirect URIs

Once the user has authorized your application, they will be returned to a URI that you specify. You must provide these URIs in advance or your integration users will experience an error.

• Enter your redirect URI in the box provided
• If you need to enter more than 1 redirect URI, click ‘Add another redirect URI’

Please note:

• Only HTTPS URIs are accepted in production
• Domains registered MUST exactly match the domains used, including subdomains
• Register all redirect URIs fully where possible. This is the most secure option and what we recommend. For more information about redirect URIs, please see our redirect URI FAQ

Saving your application

Once you have completed the application form and added your redirect URIs you can save your application.

• Click ‘Save my application and generate my client ID and secret’

You will be directed back to the developer tools page which will now include your Public API client credentials

Updating your credentials

Making a change to your application information is very simple.

• Edit the relevant information and then click ‘Save application’

Use your credentials

Now that you have your credentials, it’s time to start using the ORCID Public API!

Please note that we can transfer your credentials to the member API if you become an ORCID member in the future.

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.

Anyone with public or member API credentials can receive a /read-public access token. To obtain a token, you make a call to the ORCID API token endpoint.

This process is often referred to as the client-credentials OAuth flow, or 2-step OAuth.

An example call to obtain an access token to read public data on the sandbox — replace the placeholders with your credentials (be sure to remove the brackets.

URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  METHOD: POST
  DATA: 
    client_id=[Your public API client ID]
    client_secret=[Your public API secret]
    grant_type=client_credentials
    scope=/read-public

You will then be returned an access token similar to the following. The token returned is long-lived (not expiring for approximately 20 years) and can be used multiple times to retrieve public data from ORCID records. 

{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}

Note: All tokens with the /authenticate scope now also have /read-public scope included. If you use only the /authenticate scope, you can use the stored access tokens to read public data without needing to again obtain an access token. 

Integrators using the member API can use the /read-public scope to read ORCID record summaries.

To obtain /read-limited access, you must ask the researcher for permission. You do this using OAuth. Specifically, “3 legged OAuth“.

For more information please see our API Tutorial: Read data on an ORCID record

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.

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.

This example call retrieves a summary of the full ORCID record in XML format using the member API on the sandbox server. You need an access token to make an API requests to the Public or Member API.

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

The API will return a 200 OK message, indicating that the request was received successfully, and the full summary of the ORCID record, including summaries of individual items.

<?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>

Each item (work, funding, employment etc) has a put code. This can be used to obtain full details of the item if needed.

The ORCID record is divided into individual sections to make reading the record faster and more consistent. You can first call a section to receive its summary, and then call using an individual item’s put code to receive robust information on that item.

A table of the summary sections that you can use the API to read are set out below.

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.

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.

The ORCID registry supports “content negotiation”. This means machines and other systems can ask ORCID registry for person metadata in different formats.

One of these formats is JSON-LD, which uses the schema.org vocabulary, specifically the Person type, which we connect with works, organisations and other identifiers. We also support XML, JSON, RDF XML and turtle, and have implemented Cross-origin resource sharing (CORS) to make it our data easy to access.

• See this blog post for an overview of ORCID and schema.org
• See our technical documentation on content negotiatio

Searching for a user using cURL like so:

curl -iL https://orcid.org/0000-0000-0000-0000

Will return a 200 even if the user does not exist. To avoid this, use content negotiation in your call like so:

curl -iL -H 'Accept: application/xml' https://orcid.org/0000-0000-0000-0000