This guide now lives at https://info.orcid.org/hands-on-with-the-orcid-api/ please go there for the latest version. Thank you.

In this section, we'll add an education affiliation to our Sandbox record. As you have seen, you can use the API to GET (read) items on the record, and you can also POST (add), PUT (update), and DELETE any section of the record. The only things you need to change are the endpoints and the XML for each section. 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.

Add an education affiliation

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: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>

Still have that Google OAuth Playground window open? If so, continue with step 1 below. If not, you have two options:

• if you saved your authorization token from earlier fill out the Oauth Playground window as you had it on Read the record
• if not, go back and repeat the Get an authorization code and Exchange authorization code for an access token steps from the previous section before moving on to the steps below.

1. Beneath Step 3: Configure request to API, set HTTP Method to POST.

   

2. 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
   

   

3. Click Content-type > Custom and enter application/vnd.orcid+xml
   

4. Click Add, then click Close.

5. Click Enter request body.

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

7. OPTIONAL: In the Request Body text box, edit the XML to reflect your institution.
   For <disambiguated-organization-identifier>, use the Ringgold Identify database to find the Ringgold ID for your institution (you'll need to register a free Ringgold account in order to search the database).
8. Click Close.
9. Click Send the request.
10. 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!
    
11. 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.*