Step 3 (of 5)
3. Write to an ORCID record (POST)
Congratulations! You’ve set everything up and are collecting iDs and permissions – now for the fun part! In this lesson you will learn how to write data to an ORCID record.
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 Developers OAuth 2.0 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:
Make sure the configuration has your client ID and client secret
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:
Beneath the Step 3 within Google Developers OAuth 2 playground click Add headers, enter the values below, then click Add and Close
Header name: Accept
Header value: application/vnd.orcid+xml
Beneath Step 3: Configure request to API, set HTTP Method to POST.
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.
Click Content-type > Custom and enter
application/vnd.orcid+xml
Click Add, then click Close.
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.
Click Send the request.
The results will appear in the Request/Response section on the right. Scroll to the bottom of the response – if you see HTTP/1.1 201 Created, your education affiliation was successfully added! Below you can see excerpt an example of how the XML will appear with the 201 created message at the bottom.
... <common: month>01</common: month> <common: day>01</common: day>
</ common: start-date> <education:organization>
<common: name>My University</common: name> <common: address>
<common: city>Some City</common:city> <common: region>Region</common: region> <common: country>US</common:country>
</ common: address>
HTTP/1.1 201 Created
Content length. A X-xss-protection: 1; mode=block X-content-type-options: nosniff
Expires: 0
Server: nginx/1.10.0
Connection: keep-alive
Location: http://api.sandbox.orcid.org/v3.0/0000-0002-4456-8947/education 26971
Pragma: no-cache
Cache-control: no-cache, no-store, max-age=0, must-revalidate
Date: Thu, 15 Jun 2017 20:44:09 GMT
Access-control-allow-origin: *
Content-type: application/vnd.orcid+xml: qs=5;charset=UTF-8
X-frame-options: DENY
Please save your put code it will be required in the next section to update items!
Save your put-code
Put codes are short numeric codes that reference a particular item on the ORCID record.
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.
In the above example the put code is the 5 digits at the end of this line: Location: http://api.sandbox.orcid.org/v3.0/0000-0002-4456-8947/education 26971
If there is an error in your response, check that there are no typos in your XML tags and that you have entered all other details correctly. The slightest typo can break everything!
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.