Getting started with your ORCID integration

Upgrading from 1.2 to 2.0? See our upgrade guide!

ORCID offers several APIs that allow your systems to connect to the ORCID registry, including reading from and writing to ORCID records. Some API functions are freely available to anyone (Public API); others are only available to ORCID member organizations (Member and Premium Member API). Anyone is free to test the API on our sandbox testing server

Contents

  1. Register for sandbox credentials
  2. Learn about APIs, OAuth, and how to access the ORCID API
  3. Create a test ORCID iD through the sandbox user interface
  4. Determine how you want to use the ORCID API and what permissions you’ll need
  5. Build and test your application on the sandbox
  6. Create communication points to your users
  7. Check in with ORCID staff to demonstrate how your application works
  8. Register for credentials on the ORCID Production Registry
  9. Transfer your application to the ORCID Production Registry
  10. Launch—and let everyone know

1. Register for sandbox credentials

The first step is always to request sandbox Member API credentials to build and test your application. These credentials allow you to make calls to the sandbox member API to read, write to, and update ORCID records. Access to the sandbox testing environment is freely available to anyone, even if you're not an ORCID member organization.

The sandbox lets you create test user accounts and develop your integration without having to worry about affecting data on the live (production) ORCID Registry. The sandbox behaves the same way as the production ORCID Registry with a few exceptions: 

  • Search & Link wizards in the funding and works section generally do not function,
  • Only sends notifications, e.g. email verification requests, to @mailinator.com addresses. (Read more in item 3 below.)

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


2. Learn about APIs, OAuth, and how to access the ORCID API

We’ve put together resources to help you get started:


3. Create a test ORCID iD on the sandbox user interface

In order to test the ORCD API and API calls, such as a reading and adding information to an ORCID record, you will also need to create a test ORCID record in the sandbox. This can be done through the user interface, much like on the production ORCID Registry. Go to https://sandbox.orcid.org/register and register for an account.

Registered email address: The sandbox server sends notification emails only to Mailinator (@mailinator.com) email addresses in order to not spam mail servers unintentionally. You will not receive a verification email or password reset notification unless you use a @mailinator.com address, and verification is required in order to make any manual edits to sandbox records. If you do not wish to use a Mailinator address, then please make note of your username and password (as you will be using them to grant authorization to your application when testing), and contact us to request assistance with verification.

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.


4. Determine how you want to use the ORCID API—and the user permissions you’ll need

As you are getting started with your integration planning, you should consider:

The ORCID API can be used to read, add, or update information on a user's ORCID record—you just need to request permission using either three- or two-legged scopes. The scopes you need will largely affect which API best suits your system. You can find a full list of the the ORCID scopes in the ORCID GitHub Registry, along with information such as which API can use them.

>You can also consult our Resources Center for examples of custom and vendor integrations which have been built and shared by members of the ORCID community for an idea of what is possible.


5. Build and test your application on the sandbox

We require you to first build tools that interact with the ORCID sandbox to prevent affecting any data on the production registry during testing—or your own systems.

It is important that your system be able to do the following in a secure manner:

  • Accept and store ORCID iDs: Your system will need to know the iD of the ORCID record to update. Store it together with the researcher’s information.
  • Accept and store persistent access tokens: Persistent tokens are valid for approximately 20 years or until the user revokes them.
  • Accept and store put codes (if updating ORCID records): Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API. Save this put code along with the item in your system—it’s how you’ll identify which item needs to be read or updated.
  • Log interactions: Your system should record both calls made to the ORCID API and responses received. This is necessary so ORCID can help if a problem develops later.
  • Provide error messages and a support contact when an interaction does not go as expected.

We also suggest the following best practices:

  • Customize the user experience: Use data your system has stored to pre-fill the OAuth sign in/registration screen. You can also include state parameters to identify the user in your system.
  • Sign users out of ORCID before they connect their iDs: To help ensure that no iDs are incorrectly linked.
  • Provide an option for users to remove their ORCID iD and data from your system: In rare cases, a user may connect the wrong ORCID iD.
  • Use the access token to check for existing permissions: Once you have received permissions from the user once, you should not need to request them again.
  • Update added items when corrections are needed using the item’s unique put code.

6. Create communication points to your users

Communicating to your users throughout your integration workflow is just as important as developing the technology. Researchers need to be informed as to what ORCID is, why you are requesting access to their ORCID record, and what you will do with their data. Our Collect & Connect program is designed to help with this, including encouraging integrators to use the same standards in your integrations to provide a consistent user experience.

Some communication we encourage that you add to your system:

  • Explain to your researchers the benefits of creating an ORCID iD and connecting it to your system.
  • Explain why you collect iDs and perform other tasks such as updating their records.
  • Display the hyperlinked ORCID iD with the iD icon, following ORCID guidelines to help create a consistent user experience and associate the iD icon with a trusted assertion process.
  • Explain the benefit of your system connections with ORCID and in turn how they benefit the researcher.

7. Check in with ORCID team to demonstrate how your application works

Before your integration can go live on the ORCID production registry, our Community team will test your API tools and double check that everything you have built on the sandbox will also work on production. Let us know when you’re ready and we will work with you to find the best way to review your integration.

If you are using a system with built in ORCID support, this step may be able to be skipped. Check with the Community team about which third-party systems do not require sandbox demonstation before launch.


8. Request credentials on the production server


9. Transfer your application to the ORCID production registry

Once you have your credentials, you’re ready to take it live.

If you would like to test your integration before it launches to the public, please use the tester’s own ORCID record or a colleague’s ORCID record. You can also create a new record with an email address to which you have access, and then deactivate the record when your testing is complete.


10. Launch and let everyone know

Taking an application live isn’t the last step—you need to let everyone know about it so they can connect their ORCID iD to your system quickly and easily.

We suggest that you:

  • Create a communication timeline: make sure that stakeholders are aware of your ORCID project well before you launch.
  • Use a combination of top-down and bottom-up communications.
  • Promote your ORCID integration often and to different audiences.
  • Create local resources to support your users, such as FAQs, libguides, web pages, tutorials, and videos.
  • Nominate a local contact person for ORCID-related questions.

You can find ORCID logos, fliers, videos, presentations, and other downloadable templates in our Outreach Resources and example of other members’ communications at our Resources Center.

Don’t forget to let us know!

It’s very important that you let us know when your integration launches. This enables us to know how the community is engaging with ORCID and better support our users if they have trouble linking their ORCID iD to your system.

In addition, for ORCID member organizations, we will add your integration to our list of live integrations, add information about your Collect & Connect status, and include it in our monthly member newsletter. We will also share news about your integration on Facebook and Twitter and would be happy to talk to you about other opportunities to publicize your integration.