Introduction

The ORCID API (Application Programming Interface) provides technical infrastructure that can be used to connect the ORCID registry (ORCID iDs and data in individual’s ORCID records) with local institutional systems and applications to help save time and reduce administrative burden for researchers, administrators, and other stakeholders in the research and scholarly communication ecosystem. The ORCID Member API is recommended for use in organizational systems. This guide provides instructions for how to set up a custom ORCID API integration, as a supplement to ORCID’s documentation on Getting started with your integration. For more information about the ORCID API, check out our ORCID API Basics and Benefits webinar recording and our documentation on how researchers can connect their ORCID iD with an organization via API. 

The ORCID Member API allows for the following functionality, depending on how the integration is configured:

• User can log in to an application using ORCID
• Application can get a user’s authenticated ORCID iD
• Application can read data (set to public and/or trusted parties only visibility) from a user’s ORCID record 
• Application can write data to a user’s ORCID record
• Application can receive webhooks notifications to enable syncing data between ORCID records and local system

An ORCID API “integration” typically consists of 3 main components:

1. An end-user facing web page (or “ORCID portal”) where the user is prompted to connect their ORCID iD to the institution/application via the ORCID authentication (OAuth) process
2. A secure back-end database where authenticated ORCID iDs and access tokens are stored after the user completes the OAuth process
3. API calls used to read data from and/or write data to a user’s ORCID record once the authenticated ORCID iD and access token have been retrieved and stored

Planning

When assessing where and how to use the ORCID API in institutional systems, the systems and software you are using should be considered:

1. If you are using vendor systems, your approach will be limited to how the vendor has configured their system to use the ORCID API. Some vendor systems have the ORCID API already built in to varying degrees of functionality, others don’t. If you are not satisfied with the current state of your vendor system with regard to ORCID, the best approach is to contact your vendor and let them know.
2. If you are using custom or open-source systems, you will have more flexibility in what you can do with the ORCID API. Some open-source systems already have the ORCID API built-in to varying degrees, others don’t. 

Check our list of common systems for ORCID integration to see the status of any systems that you might be using, as well as email templates for contacting vendors to request ORCID API functionality.

Implementation

Component 1: Create an end-user facing web page (or “ORCID portal”) where the user is prompted to connect their ORCID iD to the institution/application via the ORCID OAuth process. For details about how the OAuth process works, see our written documentation and/or video demonstration.

1. Decide what scopes (permissions) you want to ask researchers for during the OAuth process. Scope options include:

• • /authenticate - used to collect the user’s authenticated ORCID iD and read public data from ORCID record
  • /read-limited - used to read data from a user’s ORCID record that has been set to “trusted parties only” visibility
  • /person/update - used to update the following information on the user’s ORCID record: other names, keywords, countries, researcher URLs, websites, and personal external identifiers
  • /activities/update - used to update the following information on the user’s ORCID record: employment, education, qualifications, invited positions, distinctions, membership, service, funding, works, peer review, and research resources
  • /webhook - enables your local system to receive a notification when information on a user’s ORCID record has been updated

2. When setting up your integration, you will first use the ORCID sandbox. To get your ORCID sandbox API Client ID and Client Secret, fill out ORCID’s sandbox credential request form. When you are ready to move to production, contact orcidus@lyrasis.org and we will schedule an integration review (see below for details about the integration review).

3. Construct the Authorization URL, using your unique Client ID, the scopes that you want to use, and a redirect URI (the location where the user will be re-directed once they go through the ORCID OAuth process). 

• • Example of an Authorization URL: https://orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJYYI4&response_type=code&scope=/read-limited/activities/update&redirect_uri=https://bc.edu/orcid 

4. Decide where the ORCID portal page will live, and design ORCID portal page to include information about ORCID and a “Create or Connect ORCID” button (aka Authorization URL). Note, users are typically prompted to log in with their institutional credentials prior to connecting their ORCID iD, so your system can identify the proper institutional user with whom to connect each ORCID iD.

• • Example: University of Texas Southwestern Medical Center ORCID Portal
  • Example: Florida State University “ORCID @ FSU"
  • Example: University of Arizona “ORCID @ UA”

5. Configure application to store authenticated ORCID iD, access token, etc. in a secure back-end database (see Component 2).

Component 2: Set up a secure back-end database where authenticated ORCID iDs and access tokens are stored after the user completes the OAuth process.

1. Identify where ORCID data will be stored. It can be any secure database, such as an enterprise data warehouse, a database within or alongside an HR system such as Banner or PeopleSoft, or any database containing user data for the system, institution, or platform.
   • Example: UTSW stores ORCID data in an enterprise data warehouse: https://lyrasisnow.org/orcid-for-learners-at-ut-southwestern-medical-center/ 
   • Example: Boston College stores ORCID data in a database alongside PeopleSoft: https://lyrasisnow.org/orcid-at-boston-college-create-connect-with-peoplesoft/ 
2. ORCID recommends storing the following data for each user upon completion of the ORCID OAuth process:
   • Name
   • ORCID iD
   • Access Token
   • Refresh Token
   • Scopes
3. Once you have the authenticated ORCID iD and access token for a user, you can display the ORCID iD anywhere that makes sense and use the API to read and/or write data from/to ORCID (see Component 3).

Component 3: Use API calls to read data from and/or write data to a user’s ORCID record once the authenticated ORCID iD and access token have been retrieved and stored.

1. Note that API functionality will depend on the scopes that were used in your Authorization URL and subsequently approved by each user.
2. To read data from ORCID:
   • Decide which parts of the ORCID record you want to read. A list of all possible data types in ORCID can be found at https://orcidus.lyrasis.org/data-fields/. Note that metadata is returned in either XML or JSON format.
   • Follow this tutorial: https://info.orcid.org/documentation/api-tutorials/api-tutorial-read-data-on-a-record/ 
3. To write data to ORCID:
   • Decide what type of data you want to add to your researchers’ ORCID records. A full list of data types, with links to required metadata, can be found at https://orcidus.lyrasis.org/data-fields/. Note that typically an organization should only add information to someone’s ORCID record that the organization has the authority to confirm, such as an individual’s employment affiliation, or works that are stored in the organizations’ repository, for example.
   • You will need to construct either XML or JSON files containing the relevant metadata for the information you want to write to ORCID records.
   • Follow this tutorial: https://info.orcid.org/documentation/api-tutorials/api-tutorial-add-and-update-data-on-an-orcid-record/ 
4. If you want to use webhooks notifications, you can either include the /webhook scope in your Authorization URL, or you can register webhooks on authenticated ORCID iDs after they are stored in your database. Follow this tutorial for more info on webhooks: https://info.orcid.org/documentation/api-tutorials/api-tutorial-registering-a-notification-webhook/ 

Integration Review

When you have completed development of your custom integration, please contact orcidus@lyrasis.org to schedule an integration review via Zoom, where we will ask to see a demo of the integration. For the demo, we will ask you to walk us through the ORCID OAuth process that you have set up using the ORCID sandbox environment, where we will be looking for the following:

• Required:
  • Confirm use of OAuth to collect authenticated ORCID iDs. Specify scopes used.
  • Do not allow users to edit, search for, type in ORCID iDs.
  • Confirm that ORCID iDs are being publicly displayed. Check display formats.
  • Confirm that at minimum the authenticated ORCID iD and access token are being stored securely.
  • Use HTTPS for your site’s redirect URIs and on ORCID API calls.
  • If your integration is set up to write information to ORCID records, we will also need to confirm that put codes are being stored. (Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API, and you will need the put code if you need to update the item later, for example, updating the end date on an employment affiliation.)
• Recommended:
  • Confirm use of Branded buttons and other UX guidelines.
  • Confirm workflow if the user clicks “deny” during the OAuth process (see sample “Deny” text).
  • Confirm option to allow the user to disconnect their iD from the application.
  • Confirm user-facing text that explains the purpose of the integration, why the user should connect their ORCID iD, and how the ORCID iDs and ORCID data will be used by the organization.
  • See ORCID’s additional best practices

After the integration review, you can get your production API Client ID and Client Secret by filling out ORCID’s production credential request form.

Assessment & Maintenance 

• Make sure you are using the most current ORCID API version. As of Feb. 2022, the most current ORCID API version is v3.0.
• If writing affiliations to ORCID, make sure to update end-dates when someone leaves and is no longer affiliated with your organization. If a user has revoked their access token, you will no longer be able to update their record, but you can still delete any affiliation entries as needed.
• Consider adding more value by reading and/or writing more fields to ORCID records.
• Make sure your researchers know about your ORCID integration so they can take the necessary steps to connect their ORCID iD. Conduct additional outreach to researchers as needed, using resources available on our ORCID Outreach Resources page.
• Check your integration reports in the ORCID Member Portal (log in at https://member-portal.orcid.org/) to monitor usage and connections. 
• Contact orcidus@lyrasis.org for any questions.