Advance Notice: All ORCID websites, including the Registry (Public and Member APIs and the user interface), orcid.org and members.orcid.org, will be unavailable from 2pm UTC on December 15 for up to eight hours for a scheduled hardware upgrade. We apologize for any inconvenience.

Workflow: Vendor systems

Vendors can offer clients ready-built ORCID integrations, providing them the full benefits of their ORCID membership without having to build their own integration. This workflows outlines overall guidelines for building an ORCID integration as a vendor offering software to customers. It is not industry specific.

See our thematic workflows for specific technical workflows various sectors, 

See our API credentials checklist for our criteria for issuing member API credentials.


Contents


Vendor requirements

When building your ORCID integration you will need to ensure that your integration allows your customers to meet the requirements for issuing Member API credentials (see system setup below), as well as the minimum elements of Collect and Connect -- both technically and in terms of good user communications about what the system does and why. Read the full criteria for Collect & Connect badges

At minimum your system must meet Authenticate, and we recommend that you enable members to meet Display

  • Authenticate ORCID iDs using the OAuth process for individuals to ensure they’re correctly associated with their affiliations and contributions.
  • Display the authenticated iDs publicly in your system as per our display guidelines, to signal to researchers that your system is plumbed to support their use of ORCID.
  • Connect users’ data from your system to their ORCID records, enabling your customers to update their researchers records where required.
  • Collect users' data from their ORCID record to help populate data within your system or forms.
  • Synchronize your system’s data with the ORCID Registry via a bidirectional information flow.

System setup

All systems that connect with ORCID need to store the ORCID iDs and access tokens collected, and you can also store information read from the ORCID record.

  • Store authenticated iDs: Your system must be able to accept and store ORCID iDs together with the user’s information.
     
  • Exchange authorization code: Your system must be able to capture a six-digit authorization code and exchange it for an access token immediately.
     
  • Store the full token response: Your system must also be able to accept and store the full token response together with the user's information, including:
    • Persistent access tokens
    • Refresh tokens
    • Requested scopes
    • Scope expiry
       
  • Customized user interaction messages: We recommend creating or designating at least three pages where messages can be displayed:
    • Start connection: Where the end user initiates the connection process between your system and ORCID.
    • Connection-success: The page the user will be redirected to after successfully authorizing the connection with your system. It should display their ORCID iD and can also display a thank you or acknowledgement message -- as well as the option to unlink the ORCID iD.
    • Connection-failure: The page the user will be redirected to after denying authorization to your system. It should give the reasons you requested permission from the researcher and offer the opportunity to again grant permission.
       
  • Items to store when writing data: If your system writes data to ORCID records:
    • Your system must be able to save a put code for each item added toan ORCID record (and group ID for peer review). Put codes are unique identifiers for items within the ORCID Registry (read more).
    • Your system must be able to send data in XML or JSON formatted in the ORCID message schema.
       
  • Log interactions: Your system should record both calls made to the ORCID API and responses received; this is necessary so our team can help if a problem develops later. Ideally your client should also be able to read and share these logs.
     
  • API selection: Your system should allow clients to select whether they are using public or member API credentails (if your system allows both).
     
  • Data export: Your system must offer a way for your clients to export the stored ORCID iDs and token exchange data (access tokens, refresh tokens, scopes, scope expiry). If your system also writes data, then it must also include the relevant put codes with data exports. 
     

ORCID API credentials

ORCID requires that the organization requesting the data, i.e. your client, use their own ORCID API credentials. This clearly indicates who is requesting access to update ORCID records and is required by ORCID’s membership agreement. The organization must obtain the ORCID API credentials on their own. If you are assisting the organization in managing the system and their API credentials require changes such as updating the redirect URIs, the organization must submit the request for changes. 

When talking to your clients about what they need to do to obtain, set up, and test credentials to access the ORCID APIs, please:

  • Clearly explain which API is required to use your system:
    • Public API: authenticate and read public data only
    • Member API: read limited access data and update records
    • Premium Member API: register webhook notifications
       
  • Provide clear direction on how to complete the application forms for ORCID credentials (contact us for assistance pre-filling the credentials form): 
    • Where to fill out the application
    • The full list of redirect URIs
    • System website URL
    • A suggested description (the API client name should include the organization which owns the credentials, not just your system name)
    • Populating the note to ORCID staff that they are using your system
       
  • Allow your clients to enter their ORCID credentials (client ID and secret) within your system -- they should not be sending this data to you.
     
  • Provide an option for testing on the ORCID sandbox, where clients can enter sandbox credentials and make test connections to the sandbox system.
     
  • Consider providing an option to test that credentials were entered correctly by requesting a two-legged OAuth /read-public access token.
     

Communicating about ORCID to your users

Researchers will be connecting to ORCID from your interface, so we strongly encourage you to make sure that they understand how and why, including providing information about how your system interacts with ORCID. This will help you and your clients meet the communications component of each element of the Collect & Connect program. Check our communications resources and graphics for suggested language and graphics.

This includes:

  • Providing a hyperlinked ORCID-branded button for collecting authenticated ORCID iDs: Using the ORCID button consistently helps ensure that researchers associate it with being asked to securely provide their iD, which in turn builds trust in ORCID as a reliable identifier.
     
  • Displaying ORCID iDs in your system formatted per our iD Display Guidelines
  • Clearly communicating your integration and its benefits to users: Why your system collects ORCID iDs, why it requests permission to read/update ORCID records (where relevant), and how it benefits your users.
     
  • Providing a link to learn more about ORCID.
     
  • Allowing clients to provide links to local documentation or to customize the information provided about how they are using ORCID.
     

Let us know about your system

As part of our service to ORCID members, we’re happy to help you test your system and let the ORCID community know about it on our ORCID-enabled systems pages.

Once you’re ready to release your system, contact us to get the process started. We'll need to know:

  1. Your system’s name and developer's name.
     
  2. A brief description of its functionality and how it connects to the ORCID Registry.
     
  3. Your availability for an integration review, so we can determine whether ORCID members must undergo a full integration review before receiving API credentials, as well as confirm how your system helps members meet Collect & Connect.
     
  4. Links to pages, presentations, and/or demo systems to which we can refer organizations so they can learn more about your system.
     
  5. Technical and administrative contacts whom we can invite to join the API users list as well as liaise directly, so you can provide your clients with the latest functionality.

We are also always interested to learn more about non-member integrations, so please keep us posted!