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.
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.
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-publicYou 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 signs in, 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. ORCID grants long-lived permissions (not expiring for approximately 20 years) and do not expire unless your system revokes the token or the user revokes access from their account settings.
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"}
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 |
|
|
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 |
Sandbox: https://api.sandbox.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 100) |
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.