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:

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

    Google OAuth Playground HTTP method set 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

    Google OAuth Playground request URI configuration for adding an education affiliation

  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
    Google OAuth Playground Request Body configuration for new education affiliation

  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!
    Google OAuth Playground response for successful education affiliation POST request
  11. Visit the public view of your Sandbox record at https://sandbox.orcid.org/[ORCID ID] to see your new education affiliation.
    ORCID record with new education affiliation item added
    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.*