Basic tutorial: Read data on an ORCID record

You can help make life easier for your users by retrieving data from their ORCID records to populate your forms, systems, and more. Using the ORCID API, you can read biographical and research activities information on ORCID records. Responses can be returned in XML or JSON format.

This tutorial will walk you through reading public and limited-access information on an ORCID record using the public and member API. It is based on version 2.1 of the ORCID message schema.

Note: the public API may be throttled at the IP or transaction level in order to discourage inadvertent overloading or deliberate abuse of the system.


Contents


Get an access token to read an ORCID record

Public or member API: /read-public token

Anyone with public or member API credentials can receive a /read-public access token. To obtain a token, make a call to the ORCID API using two-legged OAuth authorization (i.e. a call directly to the API). The call is the same for public and member API credentials.

An example call to obtain an access token to read public data on the sandbox -- replace the information in bold 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:

{"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}

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. 

Note: /read-public permissions are automatically included in the token returned with the /authenticate scope. If you have obtained a researcher’s authenticated ORCID iD using /authenticate on the public API, then you can also use same returned access token to read their public record.


Member API: /read-limited token

ORCID members with member API credentials can request permission from users to read limited-access data on their ORCID records through 3-legged OAuth authorization (i.e. user grants permission, is returned to your system with an authorization code, and you exchange that code for an access token). This permission is valid only for that individual’s ORCID record; if you want to read limited-access data on another ORCID record, you must request permission from that record holder.

When long-lived permissions are enabled and granted, the authorization does not expire so you will be able to access read-limited information on that record using the same access token until the user revokes access. (API credentials issued since October 2014 have long-lived tokens enabled by default. If you’re uncertain whether your credentials have long-lived tokens, contact us.)

Build the authorization link

Built your authorization link by specifying your API credentials’ client ID and associated landing page (redirect URI). Set the scope to be /read-limited -- a full list of scopes, descriptions, and request methods are available at our GitHub repository.

The below example requests permission to read limited-access data 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=/read-limited&redirect_uri=[Your landing page]

Exchange the authorization code for an ORCID iD and access token

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":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

The access tokens returned can be short lived (expiring one hour after issue) or long lived (expiring 20 years after issue). Either token can be used multiple times before it expires.


Use an access token to read an ORCID record

Once you have an ORCID iD and access token, you can use the access token to read data on the ORCID record.

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 chart of the summary sections is set out below. The grey boxes are the main summary views.

Endpoint

Description

/record

Summary view of the full ORCID record

/person

Biographical section of the ORCID record, including through /researcher-urls below

/address

The researcher’s countries or regions

/email

The email address(es) associated with the record

/external-identifiers

Linked external identifiers in other systems

/keywords

Keywords related to the researcher and their work

/other-names

Other names by which the researcher is known

/personal-details

Personal details: the researcher’s name, credit (published) name, and biography

/researcher-urls

Links to the researcher’s personal or profile pages

/activities

Summary of the activities section of the ORCID record, including through /works below.

/educations

Education affiliations

/employments

Employment affiliations

/fundings

Summary of funding activities

/peer-reviews

Summary of peer review activities

/works

Summary of research works

Now that you know your endpoint, you can build your base URL:

Credentials type:

Public API

Member API

Resource URL:

Sandbox: https://pub.sandbox.orcid.org
Production: https://pub.orcid.org

Sandbox: https://api.sandbox.orcid.org
Production: https://api.orcid.org

API version:

v2.1

ORCID iD:

[Target ORCID iD]

Endpoint:

[Target endpoint]

Now that you’ve built your base URL, you can call the API using your access token. This example call retrieves a summary of the full ORCID record in XML format using the member API on the sandbox server.

  Method: GET
  Accept: application/vnd.orcid+xml 
  Authorization type: Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.1/[ORCID iD]/record
  Example calls: GitHub

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 complete with their respective put code:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record path="/0000-0001-2345-6789" xmlns:internal="http://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>

For assistance reading the 2.1 ORCID record XML, see Reading ORCID record XML (2.1).

This put code can be used to make an additional call to the API to retrieve the full data from that item. The following items can be queried using an individual section (biography) or put code:

Endpoint

Description

/address/[put code]

An individual country or region

/biography

The biography field: a free text area that only the researcher can edit

/education/[put code]

An individual education affiliation item

/email/[put code]

An individual email address associated with the record

/employment/[put code]

An individual employment affiliation item

/external-identifier/[put code]

An individual linked external identifier in another system

/funding/[put code]

An individual funding activity

/keywords/[put code]

An individual keyword related to the researcher and their work

/other-names/[put code]

An individual additional name by which the researcher is known

/peer-review/[put code]

An individual peer review activity

/researcher-urls/[put code]

An individual external link to the researcher’s personal or profile page

/work/[put code]

An individual research work

/works/[put code1],[put code2],[put code3]

Bulk individual research works (up to 50)

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: Bearer
  Access token: [Stored access token]
  URI: https://api.sandbox.orcid.org/v2.1/[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"  [...] >
    [...] 
    </work:work>

Works also supports reading the full metadata of up to 50 individual work items at once. This example call retrieves in full work items 230776, 230777, and 230777 in XML format using the member API on the sandbox server. 

  Method: GET
  Accept: application/vnd.orcid+xml 
  Authorization type: Bearer
  Access token: [Stored access token]
  URI: https://api.sandbox.orcid.org/v2.1/[ORCID iD]/works/230776,230777,230777
  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 each work item:

  <?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
    <bulk:bulk [...]>
       <work:work put-code="230776" visibility="public">
       [...]</work:work>
       <work:work put-code="230777" visibility="public">
       [...]</work:work>
       <work:work put-code="230777" visibility="public">
       [...]</work:work>
    </bulk:bulk [...]>;

If you experience any trouble or do not receive a 200 OK message, check our troubleshooting page for assistance.