Hands on with the ORCID API

Things to complete before you start

Before you can make a start with this tutorial you need to have completed the 3 steps below:

• Request Sandbox Member API Credentials
• Create a Sandbox ORCID account
• Configure your google oauth playground

For this tutorial, we’ll use ORCID’s test environment, the ORCID Sandbox. The Sandbox works just like the production ORCID Registry, with a few exceptions:

• Sandbox only sends emails to mailinator.com addresses
• The majority of the Import wizard tools don’t work in the Sandbox
• Menu links to informational content (About, For Researchers, Membership, etc) don’t work in the Sandbox
• Sandbox doesn’t contain any production data

Request Sandbox Member API Credentials

API credentials consist of a client ID and a client secret which are needed in order to collect authenticated iDs and/or user permissions to interact with their ORCID record.  Please apply for your Sandbox credentials here. Add a note to advise that you are testing with google OAuth Playground. Please be aware that this is a manual process and can take up to 24 hours for the credentials to be created. 

Create a Sandbox ORCID account

In a new window or tab, visit https://sandbox.orcid.org/register

1. Enter your name and email address, and then click the “next” button. IMPORTANT! Don’t use a real email address! Instead, make up an address ending in @mailinator.com
2. Complete step 2 of the registration form with a password, and move on to step 3.
3. Select your preferred visibility setting, accept the terms of use, click the box next to the text “I’m not a robot”, and finally click the “register” button. 

Remember the email and password – you’ll need these throughout the tutorial!

Configure your Google OAuth Playground 

1. Go to Google OAuth Playground 
2. Click the gear icon in the upper right corner to open the OAuth 2.0 Configuration

3. Change the Oauth endpoints drop-down to Custom and enter the following settings and click Close

Important! Keep the Google OAuth Playground open so that you don’t lose the configurations you have made in the steps above. You can also save the URL that allows you to initialize the Playground with these configurations (to get the URL, click the link icon next to the gear icon in the upper right corner).

Collecting authenticated ORCID iDs and permissions

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 read and write permissions. 

In this section, we’ll walk through the steps that your own custom integration would need to complete in order to get an authenticated iD and permission to read and write to an ORCID record

Getting an Authenticated iD and record access permission from a user involves following OAuth 2.0, an industry-standard protocol for authorization. OAuth allows a user to give a website or application access to account information stored on another site, without giving that site their password.

If you’ve ever signed into a site using Google or Facebook instead of your credentials for that particular site, you’ve already used OAuth!

The OAuth process includes 3 steps:

1. Create an authorization URL
2. Get an authorization code
3. Exchange the authorization code for an access token

To kick off the OAuth process, we’ll need to create a special authorization URL that sends users to an ORCID sign-in screen. This URL consists of Authorization endpoint, plus Parameters that identify your organization and the permissions you want to request.

To request permission to add/update activities (affiliations, funding, works, peer review, research resources), and to add/update personal items (other-names, keywords, countries, researcher-urls, websites, and personal external identifiers) the authorization URL will be: 

https://sandbox.orcid.org/oauth/authorize?client_id=[APP-****************]&response_type=code&scope=/read-limited%20/activities/update%20/person/update&redirect_uri=https://developers.google.com/oauthplayground

But we can use Google OAuth playground to help us to build the authorisation URL

Add /activities/update, /person/update, /read-limited into the scopes field and click authorize API’s. 

The authorization URL would have been created using the information that you have entered into the configuration and the scope fields. 

An ORCID sign-in screen will appear; sign into your Sandbox account with the email address and password that you used to create your ORCID account at the start of this tutorial. Once you have signed in, the OAuth screen will appear. The client name and the relevant scopes that were included in the authorization URL will show on this screen. To grant access you need to click ‘Authorize access’

After granting permission, you’ll be redirected back to the Google OAuth Playground as this was the redirect URI associated with your Sandbox credential. A 6-character authorisation code will appear at the end of the redirect URI in the browser address bar (and under the Step 2 section on the left of the page in google oauth playground)

Exchange authorization code for access token and authenticated iD

Once you have an Authorization Code, you can exchange it for an access token and the Authenticated iD of the user who signed in, which you’ll need in order to take the API action(s) you requested permission for.

If you lose the access token you can complete the process again but first you would need to revoke permission for the client application if using the same ORCID iD. Permission can be revoked by removing the client application from the “Trusted organizations” section in “Trusted Parties” page

In a real-world situation, this exchange would be done by your system, using a programming language such as PHP, Java, or Ruby on Rails. For this tutorial, we’ll use Google OAuth Playground to simulate a web application.

Click ‘Exchange authorization code for tokens’

Once you click “Exchange authorization code for tokens” Your access token and Authenticated iD will appear in the Request/Response section on the right. Please see the example below:

Save this token!

It is important to save the token you received in the step above as you can easily create any calls you need to make with it. We would recommend that you store the full token exchange response

You have now collected an authenticated ID and permission from the user to read their ORCID record and update their ORCID record. 

Writing to an ORCID record (POST)

In this section, we’ll add an education affiliation to your Sandbox record. In the following example we are using the /education endpoint with the correct XML to add the information, but you can just as well add Employment or Works for example. See our Github documentation for more example files and endpoints and the permissions you need for each.

Here’s an example Education XML you can use for this exercise:

<?xml version="1.0" encoding="UTF-8"?>
<education:education
	xmlns:common="http://www.orcid.org/ns/common" xmlns:education="http://www.orcid.org/ns/education"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.orcid.org/ns/education ../education-3.0.xsd ">	
	<common:department-name>department-name</common:department-name>
	<common:role-title>role-title</common:role-title>
	<common:start-date>
		<common:year>1948</common:year>
		<common:month>02</common:month>
		<common:day>02</common:day>
	</common:start-date>
	<common:end-date>
		<common:year>1948</common:year>
		<common:month>02</common:month>
		<common:day>02</common:day>
	</common:end-date>
	<common:organization>
		<common:name>common:name</common:name>
		<common:address>
			<common:city>common:city</common:city>
			<common:region>common:region</common:region>
			<common:country>AF</common:country>
		</common:address>
		<common:disambiguated-organization>
            <common:disambiguated-organization-identifier>http://dx.doi.org/10.13039/100000001</common:disambiguated-organization-identifier>
			<common:disambiguation-source>FUNDREF</common:disambiguation-source>
        </common:disambiguated-organization>
	</common:organization>		
	<common:url>http://tempuri.org</common:url>  
	<common:external-ids>
        <common:external-id>
            <common:external-id-type>grant_number</common:external-id-type>
            <common:external-id-value>external-identifier-value</common:external-id-value>          
            <common:external-id-url>http://tempuri.org</common:external-id-url>
            <common:external-id-relationship>self</common:external-id-relationship>
        </common:external-id>
        <common:external-id>
            <common:external-id-type>grant_number</common:external-id-type>
            <common:external-id-value>external-identifier-value2</common:external-id-value>         
            <common:external-id-url>http://tempuri.org/2</common:external-id-url>
            <common:external-id-relationship>self</common:external-id-relationship>
        </common:external-id>
    </common:external-ids>
</education:education>

Return to the browser tab for Google Playground. If you didn’t keep the tab open, you can re-initialize the session with the URL you saved earlier (Clicking OK on the warning that comes up). Or you can set up for the call again by filling all the relevant fields, making sure they look like the screenshots below:

1. Make sure the configuration has your client ID and client secret
   
2. below Step 2 within the google oauth playground you should have your access token filled in
   It should either still have the token from earlier or you can fill it in from the previous exercise like so:
   
3. Beneath Step 3 Click Add headers, enter the values below, then click Add and Close
   • Header name: Accept
   • Header value: application/vnd.orcid+xml
4. Beneath Step 3: Configure request to API, set HTTP Method to POST.
   
5. In the Request URI field enter:
   https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education
   Replace [ORCID ID] with the iD for your Sandbox record, format XXXX-XXXX-XXXX-XXXX that you collected permission to interact with.
6. Click Content-type > Custom and enter application/vnd.orcid+xml Click Add, then click Close.
7. Click Enter request body.

Copy the education affiliation XML at the top of this section and paste it into the Request Body text box

OPTIONAL: In the Request Body text box, edit the XML to reflect your institution.
For <disambiguated-organization-identifier>, use the ROR Registry to find the ROR ID for your institution.

Click Close.

8. Click Send the request.

The results will appear in the Request/Response section at right. Scroll to the bottom – if you see HTTP/1.1 201 Created, your education affiliation was successfully added!

Also save your put code that will be required in the next section! 

Visit the public view of your Sandbox record at https://sandbox.orcid.org/[ORCID ID] to see your new education affiliation.

Notice that Source shows the name of the API client that added the affiliation – this is a key element that helps other systems consuming ORCID data determine whether this piece of information is authoritative.

Updating an ORCID record (PUT)

In a real-world situation, you may need to update a researcher’s affiliation. In this section, we’ll update our education affiliation to include an end date.

Put codes are short numeric codes that reference a particular item on the ORCID record. You use the put code with the API calls to update, delete or read a particular item (as opposed to a summary of items.)

Each item in the ORCID iD is assigned a put code which uniquely identifies it. When reading an entire record or section, the put code can be found as an attribute of the item. When calling a specific item on a record, the put code is used to identify the item. Put codes are unique within the type of item they refer to. Using this example, only one work in the ORCID Registry will have the put code 733535, though 733535 may also used as a put code for a funding item or a keyword.

When you post an item to a researcher’s record, the API response will contain the put code for that item. You can store the put code to use it later if you need to read, update, or delete that item.

To find out the put code for a particular item we don’t have, we just need to read the record or a summary of the section where that item is located. The put code for the item we want to modify will be returned in the response.

In the example below we are updating a single education item.

Note: if you saved the put code for your education affiliation, you can skip to step 4 below. If you didn’t save the put code, please start with step 1 below.

1. First we need to get a put code for the education affiliation you just added so open a new Google Playground window and set it up following the first 4 steps from the getting started section
2. This time in the Request URI field enter https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/educations . Note that we have added /educations to the end of the URI and that it is plural. This means we are fetching a summary of all the education items on this record, not just one (we would put it singular and added the /put-code of the item at the end)
3. Hit the ‘Send the request’ and you should see something like the image below in the Request/Response section. Find the put-code for the education affiliation that you added in the previous section (it will be a different number to the one highlighted here).
   
4. Change HTTP Method to PUT
5. Click Add Headers and make sure that Accept and Content-type are both set to application/vnd.orcid+xml
   
6. In the Request URI field enter:
   https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education/[PUT CODE]
   Replace [ORCID ID] with the iD for your Sandbox record, format XXXX-XXXX-XXXX-XXXX and [PUT CODE] with the put-code for your education affiliation
7. Grab the XML from the POST section again and the click Enter request body and paste it in.
8. Edit the end date for your education affiliation
9. Click Close.
10. Click Send the Request.
11. The results will appear in the Request/Response section at right. Scroll to the bottom – if you see HTTP/1.1 200 OK, your education affiliation was successfully updated! If you see an error message, check that the header values in Add headers have not been changed to garbled text, ex: application%2Fvnd.orcid%2Bxml”
    
12. Visit the public view of your Sandbox record at https://sandbox.orcid.org/[ORCID ID] to see your updated education affiliation with the new end date populated.
    

Reading an ORCID Record (GET) 

Return to the browser tab for Google Playground. If you didn’t keep the tab open, you can re-initialize the session with the URL you saved earlier (Clicking OK on the warning that comes up). Or you can set up for the call again by filling all the relevant fields, making sure they look like the screenshots below:

1. Make sure the configuration has your client ID and client secret
2. Step 2 you should have your access token filled in
   It should either still have the token from earlier or you can fill it in from the previous exercise like so:
   
3. Step 3 Click Add headers, enter the values below, then click Add and Close
   • Header name: Accept
   • Header value: application/vnd.orcid+xml
4. The step 3 Configurations should look like the screenshot below:
   
5. Set the HTTP Method to GET.
6. In the request URI field enter :
   https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/record
   Replace [ORCID ID] with the iD for your Sandbox record, format XXXX-XXXX-XXXX-XXXX
   
   Note: the endpoint is the word at the end of the URI. In this case we are reading a summary of the whole record so we end the URL with /record as shown above.
   
7. Click Send the request
   In the Request/Response field you should see an XML summary of the whole record. It will look a bit like the example below which shows the first part of the response. We have highlighted the put codes as discussed in the previous section