Introduction to the ORCID Member API

Welcome to the ORCID Member API! This document is intended to start you on the path to developing tools to interacting with the ORCID Registry. If you have questions at any point please contact support@orcid.org. This document outlines the typical path followed by our API developers, but feel free to change the order or skip steps as works best for you.  You may also want to read our API FAQs.

If you are integrating ORCID into a production that already supports ORCID, you'll want to jump to our documentation on ORCID-enabled systems.

  1. Register for Sandbox Credentials
  2. Get Connected
  3. Learn about how the API and OAuth works
  4. Create a test ORCID iD through the Sandbox User Interface
  5. Test one or more of the common API calls on the Sandbox
  6. Familiarize yourself with the ORCID Messages Schema
  7. Build an application to complete an API interaction on the Sandbox
  8. Check in with ORCID staff to show us how your application works
  9. Register for Production Credentials (must be an ORCID member)
  10. Transfer your application to the ORCID Production Registry and Launch

 

1. Register for Sandbox Credentials

Request testing client credentials (client ID and secret) for the ORCID Sandbox API

When you are first planning your integration with the ORCID Registry, you should register for credentials on the ORCID sandbox testing environment. The sandbox provides a place to develop where you can create test user accounts and you don't need to worry about affecting production data. Once you submit your request, ORCID will issue you sandbox credentials within one working day. These credentials will allow you to make calls to the ORCID sandbox member API, in methods described in our API documentation and tutorials. Anyone who is interested in testing out the ORCID member API can register for credentials for the ORCID sandbox, even if they are not an ORCID member organization.

The sandbox behaves the same way as the production ORCID Registry with a few exceptions. The most notable differences are that a) the Search & Link works and funding import tools on the sandbox generally do not function, and b) emails are not send to addresses stored in the sandbox in order to prevent accidental notifications from being sent from the test environment (and spamming mail servers). Exception: To allow for testing, we have enabled receipt of email addressed to the domain mailinator.com. Mailinator is a free service that is not managed or maintained by ORCID. We recommend that you review how this service works and its limitations before using these addresses. To receive emails from the sandbox, use a mailinator.com email address when creating the record, or add a mailinator.com address to the account as the primary address.

Note: If you are using a vendor system that already supports ORCID, you may not need to register for sandbox testing credentials. Check the list of vendor systems which are plumbed to support ORCID iDs, and contact your vendor to find out whether they support testing on the ORCID sandbox.

 

2. Get connected

  • Join one of out ORCID technical introduction webinars.
  • Sign up for our API users mailing list. This list is where we provide information about updates to the API and ORCID Message Schema and we suggest all ORCID integrators join. You can also use this group to send questions to other ORCID API integrators.
  • Check out what the ORCID team is working on in Trello or Github.
  • Contact the ORCID team for help anytime at support@orcid.org or submit suggestion improvements or features you would like to see at the ORCID iDeas Forum.
  • See who else has built integrations.

 

3. Learn about OAuth and the ORCID API

If you haven't worked with APIs and OAuth before you may want to start with general guides on how OAuth 2.0 works. A couple we suggest are:

For more information about how ORCID uses OAuth and how the API works, look over the these documents:

 

4. Create a test ORCID iD through the Sandbox user interface

Your application will connect to the ORCID Sandbox API with your requested credentials, but for testing it is often easiest to set up a test ORCID record on the Sandbox at https://sandbox.orcid.org/register -- remember to use a mailinator.com email address. Register for an account as you would on the production registry and remember your username and password as you will be using them to grant authorization to your application when testing.

 

5. Determine how you want to use the ORCID API

The ORCID API can be used to read, add to, or update information on a user's ORCID record. A more detailed lists of the tasks you can do is on the list of scopes. Or you can find an overview and examples of the most common integration types by sector:

 

6. Learn details about the ORCID Message Schema

When interacting with the ORCID API you will send and receive information in the ORCID Message XML format. You access the entire Schema or follow our guides explaining how the portions of the XML are formatted at ORCID XML.

 

7. Build an application to complete an API interaction on the Sandbox

We encourage members to first build tools that interact with the ORCID Sandbox, so you don't have to worry about affecting production data during testing.

An important part of any application is logging interactions. Your application should record both calls made and responses received; this is necessary so our team can help if a problem develops later. In addition, you should store any access tokens you may want to reuse.

 

8. Check in with ORCID staff to show us how your application works

Before you start interacting with the production registry, our staff can help test your API tools and double check that everything you have built for the Sandbox will also work on production. We also love to see the cool things our members build! Contact us at support@orcid.org to set up a time for a demo, or send us your site where we can demo your application.

9. Register for Production Credentials (ORCID members only)

The process is the same as applying for Sandbox credentials. If you haven't already you must become an ORCID Member.

To get credentials fill out the form at register a client application.

10. Transfer your application to the ORCID Production Registry and launch!

After you have tested your application on the Sandbox you can change it to work on the ORCID Production Registry. ORCID staff can help with this transition if needed.

Once your application is working on the ORCID Production Registry you are ready for it to be publicly available.  Let our staff know when you reach this point as can help promote your integration.