1.2 Tutorial: Update bio (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.

Introduction

This tutorial will walk you through updating biographical information in an ORCID record using the PUT commands in cURL. Note that using PUT updates all information and will replace the existing biographical information in a researcher’s record that you have added. (You will be unable to edit or replace any information which you did not add.) The text in bold in each example should be replaced with your own credentials, 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.

 

XML

The XML used in the orcid-bio section is described at XML for ORCID Bio.

 

Authorization

Updating biographical information follows the OAuth dance as described in Tokens Through 3-legged OAuth Authorization. The access tokens 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.

 

PUT Biographical information

Putting biographical information uses the scope /person/update. An example call to get an authorization code is below. This example can be pasted directly into your web browser -- be sure to first replace with your own client ID and redirect URI. When you will go to the link below, you'll be taken through the authorization steps in the user interface, signing into an existing ORCID account (in this case on the sandbox). After signing in, you will be returned to the specified redirect URI, which will be appended with a 6-character authorization code.

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

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 to exchange it:

curl -i -L -H "Accept: application/json" --data "client_id=APP-NPXKK6HFN6TJ4YYI&client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97&grant_type=authorization_code&code=w7oay3&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":"/person/update","orcid":"0000-0002-2389-8429","name":"Sofia Hernandez"}

As the PUT function will overwrite existing biographical information in the profile that you have added, you must first GET the existing biographical information to edit it. With the above access token you will be able to return both public and read-limited information. For more information about the fields in the bio section see XML for ORCID Bio.

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa466b4-04ff-4471-890d-71cf6bb8438e" "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-bio" -L -i

Finally you can update the biographical information with your access token and a PUT command.

curl -H "Content-Type: application/vnd.orcid+xml" -H "Authorization: Bearer aa466b4-04ff-4471-890d-71cf6bb8438e" -d "@/Documents/updated_bio.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-bio"
 

When successfully updated, the record will be returned as a message.

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