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 any of our APIs on our sandbox testing server.
Before you start
As you are getting started with your integration planning, you should consider:
- What you want to do with the ORCID API— please visit our workflows.
- Whether your organization is already an ORCID member or is planning to become one. Only ORCID members can add items to ORCID records.
- Whether you are using a system that already supports ORCID. If you are, it may be as simple as configuring your system to work with ORCID.
- How you will communicate with your researchers about the changes being implemented, what you’ll need from them, the benefits to them, and what they will need to do. Visit our Outreach Resources page for ideas on how to build a communications campaign around your new integration.
Register for sandbox credentials and create a test ORCID iD
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.
You can 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.
Note: If you are using a third-party system that already supports ORCID, you may not need to register for sandbox API credentials.
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.
Creating a test account
In order to test the ORCID 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.
Mailinator email addresses
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. Find out more about their free to use public inboxes here. 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 an email service that has a public free service and a private paid service. For testing you can use the completely free public service. Find out more about their tiers here.
Mailinator is a third party 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.
Determine the user permissions you’ll need
The ORCID Member API can be used to read, add, or update information on a user’s ORCID record—you just need to request permission from your researchers. The scopes you need will largely affect which API best suits your system.
When requesting permission to interact with an ORCID user’s record, you specify one or more ‘scopes’. Each scope allows you to do certain things, such as read the record, or update a particular section.
3 legged refers to the three actors involved in obtaining permission from a user; ORCID, your system and the user themselves.
/authenticate 
This scope is used to collect the ORCID iD and read public information on the record only. All other 3-legged scopes include the authenticate permission, so this scope can be omitted if asking for any other access. This scope is available on the Member or Public API.
/read-limited (Member API only) 
This scope is used to get access to read public and limited visibility items on an ORCID record. This scope is only available on the Member API.
/activities/update (Member API only) 
This scope is used to write, update and delete items in the affiliation, funding, works and research resources and peer-review sections of an ORCID record. This scope is only available on the Member API.
/person/update (Member API only)
This scope is used to write, update and delete items in the other-names, keywords, countries, researcher-urls, websites, and personal external identifiers sections of the record. This scope is only available on the Member API.
openid
This scope is used by OpenID integrators when an id_token is required. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user. This scope is available on the public and member API.
Please note that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification. Please see our OpenID documentation for more information.
Multiple scopes
Multiple scopes can be requested in a single interaction by listing the scopes in the authenticate URL with an encoded space between each, such as scope=/read-limited%20/activities/update%20/person/update
Complete access
If you want full access to read and edit a record include three scopes in your authenticate URL: /read-limited, /activities/update and /person/update. In the URL they would appear as scope=/read-limited%20/activities/update%20/person/update
2-legged (client credential) scopes
For some activities you do not have to ask the user for permission. Two legged OAuth scopes are requested directly from the ORCID API and do not require the researcher to grant permission. Tokens with these scopes are valid for 20 years and can be reused
/read-public
This scope is used to read public information on a single ORCID iD or search for ORCID records. This scope is available on the Member or Public API.
/webhook
This scope allows a client application to register a webhook on an ORCID record, in order to receive notifications when a record is updated. This scope is available to premium ORCID members only. If you are not a premium member, but wish to test this function in the Developer’s Sandbox, please contact ORCID Community.
- In the past ORCID supported other scopes, that have now been phased out.
- You can find out which scopes are required to add or update a particular sections here.
Make sure you can store the data securely
It is important that your system be able to store information in a secure manner.
Integrations need to store more than just ORCID records. Your system will need to be able to:
- 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. Our recommendation is to store the full https URI: https://orcid.org/0000-0001-5727-2427.
- Accept and store persistent access tokens and refresh tokens: Access tokens can be used to read and update records, as well as indicate that the iD has been authenticated. Persistent tokens are valid for approximately 20 years or until the user revokes them. Refresh tokens can be used to create new access tokens with the same or limited scopes. Store the tokens together with the researcher’s information. We also recommend you store the token scope, and the‚token expiry.
- 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.
Check in with the ORCID team to demonstrate how your application works
Before your integration can go live on the ORCID production registry, our Engagement Team will double check that everything you have built on the sandbox will also work on production. If you are using a system with built in ORCID support, this step may be able to be skipped.
I have developed my integration using the Sandbox, how do I get Production member API credentials?
Member organizations request ORCID Member API credentials on the production (live) server by completing the Production Member API client application form. Before issuing production Member API credentials, the ORCID Engagement team will review a demo of your integration in the ORCID sandbox. This gives us a chance to see the great integrations you have built and offer workflow improvements, as well as check that all integrations meet our best practices.
To provide a demo of your system you’ll need to set up a working integration with the ORCID sandbox that the ORCID team can preview. There are a few ways to share your working sandbox integration:
- Recommended: Live demo: Contact us to schedule a live demonstration. We’ll provide meeting software that allows you to share your screen for you to demo your integration. This also gives us an opportunity to learn more about how your system works, and how you‚re explaining the benefits of your ORCID integration, so we can provide better support for you and your users.
- Test site: If your development site is public, send us the URL along with test credentials (if needed) to access your system and instructions describing how to use your system’s ORCID features. Provide additional documentation to verify what we would not be able to see from the user end, e.g. API version used, what data is stored by your system, etc.
- Screencast or screenshots (recommended for ORCID-enabled systems which require a demonstration): Send a recording or a set of screenshots with descriptions clearly explaining and demonstrating how your integration works at each step, including what happens if a user denies access or disconnects their iD. Be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored.¬¨‚
If you are using one of the ORCID-enabled systems that does not require a demonstration, you can directly request production Member API credentials. Be sure to specify which system (and, if applicable, version) you’re using in the notes.
There are a number of requirements that we expect all member integrations to meet. The ORCID team will ensure these requirements have been met as part of the integration review process.
- Use OAuth to authenticate ORCID iDs (Do not allow users search for or type in ORCID iDs.)
- Include an ORCID branded button or link on your site to initiate authentication of the iD.
- Present the OAuth authorization screen according to our guidelines
- Use HTTPS for your site’s redirect URIs and on ORCID API calls
- Accept and store all data returned in the token exchange together with the user’s data in your system
- Use appropriate scopes and request methods (e.g. POST calls to add new information and PUT calls to update existing information)
- Publicly display the authenticated ORCID iDs. iDs should be displayed following our trademark and iD display guidelines.
Request credentials on the production server
You can apply for member API credentials once your integration has been reviewed by the ORCID team or if you are using a service provider system that has a built in ORCID integration.
You will need to fill in the form to register a client application. Below is a quick overview of the requested fields:
Notes for ORCID staff: Use this field to let ORCID know if you’re using a vendor system, integrations been reviewed etc.
Contact email address: We will send the credentials to this address. This should be the contact that we have been working with on the integration or the technical contact that we hold for your organisation.
Contact for receiving PIN to access credentials: We send the full credentials to you in a secure way. We will send a passcode to access your API credentials to this contact. This needs to be a different contact to the previous contact listed.
Short description of your client application: This text will be displayed on the authorization screen with question mark icon to your integration users. A short description of your integration is required.
URL of the home page of your application: Displayed as a link on the list of trusted organizations within the users ORCID trusted parties page. This should be a link back to your organization or the main page of your application.
OAuth2 redirect URIs or callback URLs for the client: Permitted URL(s) in your web application where users will be returned to after they authorize access to their ORCID record data. All redirect URIs must be HTTPS for production (live) server clients.
Once you have made your request, a manual process happens to issue you credentials and you will get an email with your client iD and client secret. Typically these requests are process in less than 48 hours.
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.
Launch—and let everyone know
Taking an application live isn’t the last step—you need continue to communicate to your users so they know to connect their ORCID iD to your system quickly and easily. Effective integrations contain both a technical component (which this guide covers) as well as a social component. 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.
- 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.
To support the social component we offer a toolkit of Outreach Resources to help you develop a campaign to support your integration, and communicate to your researchers:
- What ORCID is.
- Why your system collects iDs and how your system will perform tasks, such as updating their records.
- Why your researchers will benefit by creating an ORCID iD and connecting their iDs to your system.
- How ORCID benefits the wider, global research community.
We will be continually building out this “library” of resources based on feedback from the community. If you have an idea for something you might like to see, please feel free to contact us.