ORCID US Community member organizations have access to five premium ORCID member application programming interface (API) keys that can be used for reading data from people's ORCID records and/or writing data to ORCID records, such as employment affiliations, funding received, works produced, and other relevant information

Overview

ORCID US Community member organizations have a few options for writing data to ORCID using the ORCID API:

  • ORCID’s Affiliation Manager tool - allows an organization to upload a CSV file containing researchers’ affiliation information (employment, education, qualifications, invited positions, distinctions, memberships, and service) and download unique permission links that can be sent to each researcher to approve. Once approved, data uploaded via CSV will be automatically written to each person’s ORCID record. The Affiliation Manager tool requires use of one ORCID member API key.
  • Vendor systems - some vendor systems have the ORCID API built-in with functionality including writing data such as employment and works information to ORCID records. (To check the status of your systems, visit our common systems for ORCID integration list.) For example, the following systems are enabled to write data to ORCID records:
    • Artifacts - works
    • Converis - works
    • DMP Tool - works
    • Editorial Manager - peer review
    • Esploro - employment
    • Figshare - works
    • OJS - works, peer review
    • Pure - employment, works
    • Symplectic Elements - employment, works 
  • Custom ORCID member API integration - organizations can build a custom integration through which researchers can connect their ORCID iD with the organization and authorize the organization to add information to their ORCID record. (Visit our custom integration guide to learn more.) This blog is focused on writing data to ORCID records via a custom ORCID member API integration.

Initial Considerations & Logistics

When embarking on a custom ORCID API integration, there are a few considerations for getting started:

  • Your organization needs to be an ORCID member
  • You will need to use one of your organization’s member API keys
  • You will need a developer to build the integration
  • You will need to determine what data you want to write to ORCID records
  • You will need to format the data in either XML or JSON according to ORCID’s schema
  • Do you have access to curated, accurate data about your researchers?
  • What other internal organizational stakeholders need to be involved?
  • How will you make sure that data stays up-to-date?

Researchers must connect their ORCID iD with your ORCID API integration via the ORCID authentication (OAuth) process, which provides your organization with the ORCID iD and access token for each individual person. API calls can then be used to write data to ORCID records using the ORCID iD and access token for each person. For more information, see ORCID’s API tutorial on writing to ORCID records.

Every item that is written to ORCID will have a PUT code associated with it, returned via API once an item is posted to an ORCID record. PUT codes need to be stored securely so that updates can be made to entries in the future if needed (for example, updating the end date on an employment affiliation).

Stanford University Case Study

Over the past few years, Stanford University has implemented a custom ORCID API integration that connects researchers’ ORCID iDs with their Stanford (SUNet) identifier, thanks to support from multiple stakeholders across campus and executive sponsorship from the Office of the Vice Provost and Dean of Research. More recently, the Stanford University Libraries have been partnering with the Stanford Profiles team to leverage the reading and writing functionality that the ORCID API provides and streamline Stanford Profiles workflows. Stanford Profiles is a profile site that represents faculty, staff, and students at Stanford and other relevant institutions to foster collaboration and community and simulate research through the sharing of academic output and interest. 

Researchers that are represented in Stanford Profiles can review and curate a list of publications and other works, provided by the Libraries, and those works can then be written to their ORCID records via an automated process that updates every two days. To do this, the researcher goes to the Stanford ORCID portal to start the process of connecting their ORCID iD to the organization:

The researcher completes the ORCID OAuth workflow via Stanford’s ORCID portal, to grant permission for Stanford to interact with their ORCID record as a trusted organization.

Behind the scenes, the researcher’s authenticated ORCID iD and access token gets passed from ORCID to Stanford, where this information is stored securely along with the researcher’s SUNet ID in a database managed by Stanford’s Middleware and Integration Services unit (see diagram below).

The researcher can then go to their profile in Stanford Profiles to select which publications they want to have added to their ORCID record: 

Publications that are public, have identifiers, and have been approved by the user are written to the user’s ORCID record, with the “source” of the information appearing as “Stanford University”:

Other units on campus can use ORCID access tokens in order to read and/or write data to researchers’ ORCID records, but the access tokens are only stored centrally in one place. However, any unit that writes to ORCID must store the PUT codes for the items that they have written, so those items can be updated in the future if needed. Since Stanford University Libraries are writing publication information to ORCID records, the Libraries are responsible for the PUT codes of those publication entries.

FAQ: Writing Data to ORCID Records

Organizations that are currently or planning to write data to ORCID records have thought about the following questions, and conversations about these considerations are expected to continue amongst members of the ORCID US Community as we strive to identify best practices as a national ORCID community of practice in the US.

  • Is there an estimate of development effort/time needed to build a custom ORCID API integration?
      • It really depends on the staff time and expertise available. If you have a developer that is already familiar with the ORCID OAuth process, it may be quicker. It also depends on what other projects the developer is working on simultaneously. The development work can take anywhere from a few days/weeks to several months depending on these factors. However, stakeholder discussions about workflow would need to have taken place prior to starting development. Contact orcidus@lyrasis.org so we can explore the options for your specific context.
  • What does a custom integration afford that a vendor solution may lack?
      • Custom integrations offer more flexibility whereas vendor system integrations are often limited to what the vendor has set up and you have less control over the type of data you want to write to ORCID, etc.
  • What is the expiration time for the access token?
      • Access tokens expire after 20 years by default, unless the user revokes the token before that. After 20 years, the refresh token can be used to renew the token.
  • If a researcher deletes an entry that was added to their ORCID record by an institution, is the institution alerted to the deletion? 
      • If a user deletes an item, the member organization will not receive a notification that that item was deleted. If the member org has registered webhooks they will receive a notification just saying that something has changed on the ORCID record but not specifying what the change was. Since these webhook notifications are empty, the member will need to do a GET call to the record and confirm what was changed. If they do a GET or a PUT call to a deleted item, they will get a "404 Not Found" error message. Learn more about webhooks.
  • What if a researcher disconnects their ORCID record from the institution and then leaves the institution?
      • If a user revokes their access token/connection with your organization and then leaves the institution, you would no longer be able to update the data you had entered on their ORCID record. However, you could still delete an entry after their token was revoked if needed.
  • How to decide what data to write to ORCID?
      • Think about what data you have access to and whether that data is trustworthy, accurate, reliable, etc. Ideally the data will be curated ahead of time to the extent that your organization is confident that the data is accurate before writing it to ORCID. Learn more about the types of data that can be included on an ORCID record.
  • Should an institution write data to ORCID automatically or have each researcher select what data they want added to their ORCID record?
      • It depends and is really up to each organization. If you are going to just add all data to ORCID, let your users know that ahead of time. Users can always delete items or change the visibility of items that you add to their ORCID record. Or, you can allow the users to select which items they want to be written to their ORCID record, you just need to build a user interface to allow for this. Either way is acceptable, just make sure to communicate your approach to your researchers.
  • How trustworthy is data that users entered to ORCID themselves vs. data that was entered by an organization via the ORCID API?
      • It depends on how much you trust your researchers. ORCID does not have a mechanism built in for fact-checking entries.
  • Where to store PUT codes when writing data from different units across an organization?
      • This is up to you. At Stanford, the unit that added the data to ORCID is responsible for storing those PUT codes. For example, Stanford University Libraries (SUL) is writing publication information to ORCID records, so SUL is storing those PUT codes.
  • How much control do researchers have over their ORCID record?
      • Users are always able to change the visibility settings for each individual piece of data in their ORCID record despite the default visibility settings they selected when they registered for their ORCID iD. Users can also always choose to delete any items from their ORCID record. Learn more about ORCID visibility settings.
  • What happens when multiple organizations are writing the same information to a researcher’s ORCID record?
    • If multiple organizations are writing the same data to ORCID records, the user could choose to leave all of the entries or select one they want to keep. For works, duplicate entries are detected based on the presence of an identifier, such as a DOI. So if the same work with the same DOI is added by multiple sources, the entries are automatically grouped together and the user can choose which one shows up on top as their preferred source. Duplicate works entries that do not have identifiers can be manually grouped together by the user. You might also want to read data from each ORCID record first to check what is already there and identify duplicates before writing to ORCID. 

For questions about this blog post, or to contribute to the conversation, please email orcidus@lyrasis.org. Many thanks to Darryl Dieckman, Tina M. Del Cont, and Zach Chandler at Stanford University for presenting their “writing to ORCID” case study at the ORCID US Community call in April 2022.