1.2 Tutorial: Add activities (archive)

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.

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.

Introduction

This tutorial will walk you through adding affiliations, works or funding items to an ORCID record using the POST command in cURL; and updating affiliations, works or funding items that you have presiously added to an ORCID record. Updating these activities require the PUT command in cURL. The update scopes will only allow you to update activities which your client is source of, and it will update all items that you are the source of. Items you do not wish to have removed from the record must be included in the updated file.

The text in bold in each example should be replaced with your own credentials, ORCID iD, and system responses.  The access tokens from this process allow you to add multiple items at once, and multiple scopes can be requested at one time.

 

Scopes and Requests

Scope Request Description XML
/activities/update /orcid-works, /affiliations, or /funding Add and update items in the affiliations, funding and works sections of the ORCID record. XML for activities
/activities/update /orcid-works Add works to the ORCID record XML for works
/activities/update /affiliations Add education or employment items to the ORCID record XML for affiliations
/activities/update /funding Add funding items to the ORCID record XML for funding
/person/update /orcid-bio/external-identifiers Add an identifier from another system to the ORCID record XML for bio

 

XML

Before you can add an item to the ORCID record you will need to create it in XML or JSON, and before you update it, it has to have been created. See the XML section for examples.

 

Authorization

Adding information to a record follows the OAuth Dance as described in Tokens Through 3-legged OAuth Authorization. The access tokens returned in this can be short lived (expiring one hour after issue) or long lived (expiring 20 years after issue), either type of token can be used multiple times before it expires.

 

Posting an item

An example call to get an authorization code to add a work is below. The URL to ask for permission can be pasted directly into a web-browser (with your own client-id and redirect-uri) and the scope can be changed to match the item type you wish to add. It will take you through the authorization steps in the User Interface where you can log-in to 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=/activities/update&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=Mo0WOt

You should 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=Mo0WOt&redirect_uri=https://developers.google.com/oauthplayground" "https://sandbox.orcid.org/oauth/token"

response

HTTP/1.1 200 OK
...
{"access_token":"aa2c8730-07af-4ac6-bfec-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/activities/update","orcid":"0000-0002-2389-8429","name":"Sofia Hernandez"}

Once you have an access token, you can complete the call that will add the item to the user"s record using a POST method.

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/new_work.xml" -X POST "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-works"

If the item posted correctly you should see a 201 Created message.  If you receive a different message, you should check the list of API Error codes.

 

Updating an item

An example call to get an authorization code to update an activity is below. (Note that you can only update activities which your client has added.) The URL to ask for permission can be pasted directly into a web-browser (with your own client-id and redirect-uri) and the scope /activities/update . It will take you through the authorization steps in the User Interface where you can sign into an existing ORCID account (in this case on the sandbox) and return you to the specified redirect URI with a 6-character authorization code appended to the end of that URL.

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI&response_type=code&scope=/activities/update&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=Me0WOt

You can then exchange the authorization code for an access token. An example cURL statement and response:

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

response

HTTP/1.1 200 OK
...
{"access_token":"bb2c8730-07af-4ac6-bfec-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/activities/update","orcid":"0000-0002-2389-8429","name":"Sofia Hernandez"}

Once you have an access token, you can complete the call that will update the item to the researcher's record using a PUT method.

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer bb2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/update_work.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-works"

If the item is updated correctly, the record will be displayed.  If you receive an error message, check the list of API Error codes.

 

Example to add an affiliation

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

--

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer e6483ccd-0371-4c2d-b19a-e093e2ff4a1b" -d "@/Documents/affiliation.xml" -X POST "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/affiliations"

 

Example to update an affiliation

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer bb2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/update-affiliation.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/affiliations"

 

Example to add a funding item

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

--

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer b2c814ce-fee1-4b3b-87f9-772fda3d7555" -d "@/Documents/grants.xml" -X POST "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/funding"

 

Example to update a funding item

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer bb2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/update-grants.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/funding"

 

Example to add an external identifier

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

--

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer 78012684-889d-4292-8cb2-b749ebedb76f" -d "@/Documents/ex_id.xml" -X POST "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-bio/external-identifiers"