Tutorial: Retrieve data from an ORCID record (1.2)

This guide is an archived document related to the 1.2 version of the ORCID Message Schema, which is no longer supported by ORCID. The current supported version is 2.0 documentation. Go to the document for the 2.0 Message Schema.

Introduction

This tutorial will go over the steps to retrieve read-limited data from an ORCID record to add to your local system using cURL. The retrieval can be biographical data, activities data, or an entire ORCID record. The text in bold in each example should be replaced with your own credentials, the relevant ORCID iD, and system responses.

Note: This guide is based on version 1.2 of the ORCID Schema. Refer to the latest version of the schema for the most current information.

Authorization and Scope

This process follows the OAuth dance as described in Tokens Through 3-legged OAuth Authorization. When long-lived permissions are requested, the authorization does not expire so you will be able to access read-limited information using the same authorization code until the researcher revokes access. 

Scope Request Description
  /orcid-profile returns data from the entire record
  /orcid-bio returns data from the biographical section of the record
/read-limited /orcid-works returns research works data
  /funding returns funding data
  /affiliations returns affiliations data

Retrieve data

The first example URL (with your own client-id and redirect-url) can be pasted directly into a web-browser. It will take you through the authorization steps in the User Interface where you can log into an existing ORCID account (in this case on the sandbox) and it returns you to the redirect-uri with a 6-character authorization code appearing at the end of that URL.

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI&response_type=code&scope=/read-limited&redirect_uri=https://developers.google.com/oauthplayground

With this example, the final URL with the authorization code looks like

https://developers.google.com/oauthplayground/?code=Q70Y3A

You can then immediately exchange the authorization code for an access token. (This exchange should occur within 10 minutes at least. The auth code will expire within 24 hours.) An example cURL statement and response is below

curl -i -L -H "Accept: application/json" --data "client_id=APP-NPXKK6HFN6TJ4YYI&client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97&grant_type=authorization_code&code=Q70Y3A&redirect_uri=https://developers.google.com/oauthplayground" "https://sandbox.orcid.org/oauth/token"

response

HTTP/1.1 200 OK
...
{"access_token":"c47026d9-90bf-4480-a259-a953bc103495","token_type":"bearer","expires_in":631138517,"scope":"/read-limited","orcid":"0000-0003-1495-7122","name":"ORCID Test"}

Once you have an access token, you can complete the call to GET the full XML. 

curl -H "Content-Type: application/vnd.orcid+xml" -H "Authorization: Bearer c47026d9-90bf-4480-a259-a953bc103495" -X GET "https://api.sandbox.orcid.org/v1.2/0000-0003-1495-7122/orcid-profile" -L -i 

The response will be the record in XML.

HTTP/1.1 200 OK
...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orcid-message xmlns="http://www.orcid.org/ns/orcid">
...

</orcid-message>

For troubleshooting errors in this process please see API Error Codes.