Workflow: Research information, HR, and profile systems

This workflow sets out a process in which a typical research information or profile system may integrate with the ORCID API. It gives a walkthrough of the process of receiving authenticated ORCID iDs from researchers, retrieving data from ORCID records, adding affiliations with your organization to ORCID records, adding personal information such as links to their profile on your organization’s website, and updating information you have previously added to ORCID records. It is based on version 2.0 of the ORCID message schema.

Not every integration will fulfil every element of this process -- many may only collect researchers’ iDs and display them within their systems. You can also take your integration one step further by adding researchers’ works, funding information, and peer review activity for your organization.

Introduction

For both individuals and organizations, ORCID can reduce the time-consuming process of maintaining up-to-date records in local faculty profile or research information systems. Research organizations can use ORCID data to populate local systems to support networking and collaboration, to populate institutional reporting systems, or for national assessment programs.

Common integration points for research information and profile systems:

  1. Before you start: System setup
  2. Collect researchers’ iDs and biographical information
  3. Display iDs within your research information or profile system
  4. Connect affiliation information to researchers’ ORCID records
  5. Synchronize your researchers’ ORCID records with your system
  6. Take your system one step further

Before you start: System setup

Please be sure to check that your system meets the requirements below. Additional setup requirements for more advanced integrations can be found in the relevant section(s).

  • Your system must be able to accept and store ORCID iDs together with the researcher’s information.
  • Your system must be able to capture a six-digit authorization code and exchange it for an access token immediately.
  • Your system must also be able to accept and store persistent access tokens together with the researcher’s information. We also recommend that you store refresh tokens (read more about why).
  • Customized interaction messages: We recommend creating at least three:
    • Starting message: Where researchers initiate the connection process.
    • Connection-success message: Displayed on the page the researcher is redirected to after successfully authorizing the connection with your system. It should display their ORCID iD and can also display a note of thank you or acknowledgement.
    • Connection-failure message: Displayed on the page the researcher is redirected to after denying authorization to your system. It should give the reasons you requested permission from the researcher and again offer the opportunity to grant permission via the 3-legged OAuth authorization process.
  • 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.

Collect researchers’ iDs and biographical information

Research organizations can integrate ORCID into their research information and profile systems to collect authenticated ORCID iDs and to gain permission to read from/write to researchers’ ORCID records, either immediately or in the future. The iDs that you collect can be stored and display within your system and shared with other systems in your organization.

It is critical that you collect ORCID iDs and obtain permission to read and update ORCID records by first prompting researchers to sign into ORCID from within your system and then retrieving their data from the ORCID Registry using the ORCID API. It is also essential to provide information within your system about why you are collecting ORCID iDs and why this is beneficial to your researchers.

The steps to complete the Collect process are:

Provide a hyperlinked ORCID-branded button for collecting authenticated ORCID iDs: This can be at sign-in, within the researcher’s personal profile, or even in a customized email to a researcher. 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.


Example button graphics and code

Customize the user experience! You can specify a display language, pre-fill the researcher’s name, and include a state parameter which will be returned with the user to your system.

Configure the button’s link to request permissions to access the researcher’s ORCID record via the API: You'll be getting the ORCID iD by obtaining an access token through three-legged OAuth authorization, and this starts with a link customized with your API credentials and scopes that represent the access permissions you're requesting. If you are only planning to collect and display ORCID iDs within your system then you need only /read-limited access to an ORCID record. (If you are using the public API, replace this with /authorize.)

If you are planning to connect to researchers’ ORCID records then you should request both /read-limited and /activities/update access. If you plan to add biographical information, such as a link to their profile page within your system to the Websites or External identifiers section of the ORCID record, you should request  /person/update.

The below example requests permission to read limited-access data as well as to add and update biographical information and information about research activities to ORCID records. Replace the bracketed data with your client information and paste directly into your web browser to generate an access token for testing (be sure to remove the brackets!).

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited%20/activities/update%20/person/update&redirect_uri=[Your landing page]

Obtain an access token to get the researcher’s ORCID iD: The researcher signs into their ORCID account and simultaneously authorizes the connection. They are sent back to your landing page—the Redirect URI specified in the OAuth link. Appended to the end of that link will be a six-digit authorization code:

https://[Your landing page]?code=gtYn37

At this point, your system’s user interface should display a helpful message to the researcher, e.g. “Thanks for connecting your ORCID iD!” or simply display their iD in full—see Display below.

In the system backend, immediately exchange the authorization code. The authorization code expires upon use.

  URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=[Six-digit code]
    redirect_uri=[Your landing page]

  Example call: 3-legged OAuth

ORCID will then return the researcher’s validated ORCID iD and an access token:

{"access_token":"c47026d9-90bf-4480-a259-a953bc103495","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138517,"
scope":"/read-limited /activities/update /person/update","orcid":"0000-0001-2345-6789","name":"Sofia Garcia"}

If the user denies your system access: ORCID returns the researcher to the specified landing page and attaches an error message:

https://[your landing page]?error=access_denied&error_description=User%20denied%20access 

Your system should read this and automatically direct the researcher to the connection-denied landing page. We strongly recommend that you use this opportunity to explain more fully to the researcher why you are collecting ORCID iDs and requesting permission to access their record, and to prompt them again to sign in and authorize the connection to your system.

Store the token exchange result (ORCID iD, access token, refresh token, scope, and scope expiry) in your system in a safe and secure manner. The ORCID iD and access token will be required to perform any action to their ORCID record: read, write, update. If you are only requesting /authenticate access, access tokens can be stored to indicate that the iD has been authenticated, as well as read public access data.

Use the researcher’s iD and access token to read their record and populate their profile in your system: Save researchers time by allowing them to quickly and easily transfer data from their ORCID records to your system by making a call to their record:

  Method: GET
  Accept: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Token from previous step]
  URL:  https://sandbox.orcid.org/v2.0/[ORCID iDp/record
  Example call: GitHub 

Once you have obtained the record data, you can use it to update your system. Our recommended process is by searching the external identifiers for the relevant item, e.g. works, and then querying the identifier source to obtain robust metadata for each item. Alternatively, you can use the put code to read all of the data that was added to the ORCID record for that specific item. See Read data on an ORCID record for more information on reading the ORCID record, and Read ORCID XML 2.0 for more information on interpreting the ORCID message schema.


Display iDs of researchers within your system

Research information and profile systems can display ORCID iDs to clearly signal to your researchers and affiliates that your system supports ORCID. Displaying ORCID iDs requires that you have collected validated ORCID iDs from researchers as described above in Collect. To complete the Display process:

Once a researcher has connected their ORCID iD to your system, clearly display their iD on their profile within your system so that they know that they have successfully connected and asserted their identity. Format the iD as a hyperlinked URI and include the green iD icon, per our iD Display Guidelines.

ORCID iD iconorcid.org/0000-0001-2345-6789

You may also wish to display researchers’ iDs in other systems that are connected to your research information or profile system -- see Take your system one step further for more.


Connect information to researchers’ ORCID records

You can help make life easier for your researchers by connecting validated information about their affiliations to their ORCID records. At the same time, you will be helping to build trust in scholarly communications. By asserting the connection between individuals and your organization -- connections that only your organization can assert resolutely -- you ensure that your organization is appropriately acknowledged as your employees and affiliates make professional contributions.

Adding information to ORCID records involves sending formatted data to the ORCID Registry using the ORCID API and saving the put code that the ORCID Registry returns for each item. Doing this requires that you have collected both ORCID iDs and update permission as described in Collect above.

System setup:

  • Your system must be able to save a put code, a unique identifier for items within the ORCID Registry, for each work item added to the ORCID Registry. Every item that is added to the activities section of the ORCID record is returned a put code—even if you add multiple items at once. If you ever need to read, edit, or delete the item you added, you will use the put code.
  • Your system must be able to send data in XML or JSON formatted in the ORCID Message Schema.

The steps to complete the Connect process are listed below. Note that these only cover adding affiliations and links to websites to researchers’ ORCID records; see Take your system one step further for how you can add other items.

Adding an education or employment affiliation to an ORCID record

Format the affiliation in ORCID Message Schema: The affiliation must be created in XML or JSON in the ORCID message schema. Note that v2.0 requires that employment and education affiliations be formatted in separate files, and added or amended using separate endpoints. However, the basic formatting of the two are more or less the same. Sample XML for for creating an affiliation item can be found in our GitHub repository.

At the minimum, the education or employment affiliation must include the following elements:

  • Organization:
    • Organization name: The name of the organization at the highest level (e.g. "Boston University", rather than "Boston University School of Medicine").
    • Address: The city, region, and country (or region) where the organization is located. Only city and country are required, and the country should be populated with the two letter ISO 3166 Alpha-2 country code.
    • Organization identifier and identifier source: A unique identifier for the organization and its source. Currently ORCID supports Ringgold identifiers, so this should be the organization’s Ringgold ID. If you do not know your institution’s Ringgold ID, you can look it up in the Ringgold registry or contact ORCID.

We recommend that you populate the other available fields as well. By including more information, you enable your researchers to share more complete data with other systems they connect to, and strengthen your system’s position as a service.

  • Department name: Any subdivision of the parent organization.
  • Role title/Degree: The position held, or the degree awarded or to be awarded.
  • Start date:  The date the relationship between the researcher and organization began (can be specified down to year, month, and day).
  • End date: The date the relationship between the researcher and organization ended (can be specified down to year, month, and day).

Add the affiliation to the relevant ORCID record: Use the ORCID iD and access token you have stored for the researcher to add an affiliation using an HTTP POST call to the relevant endpoint: /education or /employment:

  Method: POST
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  Data: [Link to file or text of URL item to add]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/education
  Example call: GitHub

Save the returned put code(s) in your system in association with the affiliation. You’ll need these for later to read, update, or delete the affiliation. The API will return a 201 Created message to indicate that the item posted correctly. Check our troubleshooting page if a different message is received.

  HTTP/1.1 201 Created [...]
  Location: https://api.sandbox.orcid.org/v2.0/0000-0001-2345-6789/education/739287

Adding a link to a researcher profile to ORCID records

Once you have obtained permission to update a researcher’s biographical information, your system can add multiple biographical items to their ORCID record: other names by which they are known, keywords, links to external websites (e.g. faculty profile pages), their country or region, and unique identifiers within your system.

The following example demonstrates adding a website link to an ORCID record. Adding other biographical information follows the same process, but with different endpoints.

Note on adding external identifiers: Many organizations collect researchers’ other external identifiers, e.g. ResearcherID, Scopus Author ID, but only the issuer of those identifiers can assert them with authority. Only add identifiers which your system alone creates and uses to identify researchers.

Add the website to the relevant ORCID record formatted in the ORCID message schema: Create the website link to be added in a separate file and use the ORCID iD and access token you have stored for the user to add the website link using the ORCID member API.

  Method: POST
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  Data: [Link to file or text of URL item to add]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/researcher-urls
  Example call: GitHub
  Example XML: GitHub

Save the returned put code(s) in your system in association with the website link(s) so you can read, edit, or delete it later.

  HTTP/1.1 201 Created [...]
  Location: https://api.sandbox.orcid.org/v2.0/0000-0001-2345-6789/researcher-urls/41833

Synchronize your system’s data and researchers’ ORCID records

Updating your researchers’ data within your system, to reflect changes in their affiliations or in recognition of other published work, helps reduce the reporting burden for your researchers and improves data quality.

Synchronize data between your system and ORCID by automatically updating ORCID records and regularly querying the researcher’s ORCID records for any new changes. This requires persistent (long-term) update tokens. (Premium members can register Webhooks to receive pings from ORCID when monitored records are updated.)

Be sure to check the last modified date to find the latest information.

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record  [...]>
  <history:history>
    <common:last-modified-date>2016-11-29T11:29:23.584Z
    </common:last-modified-date>
  </history:history>
  [...]
  Example XML: GitHub

Updating information on an ORCID record

Information added by your system may in future need to be amended or deleted from researchers’ records. Information should be updated as a best practice, rather than deleted and reposted, but there are some cases where deletion is preferable:

Update

Delete

Correcting data, e.g. typos, formatting errors

Website link added to the wrong ORCID record

Adding new data, e.g. end dates

Employment affiliation incorrectly added as education affiliation

To update, use the ORCID iD, access token, the affiliation or biographical information formatted in the ORCID message schema, and the item’s put code to update via an HTTP PUT command. Only one item can be updated at a time.
The below example demonstrates how to update an employment affiliation.

Format the updated item in ORCID message schema with the changed information and include the stored put code.

<?xml  version="1.0" encoding="UTF-8"?>
  <employment:employment put-code="[put code]" [...]  >
  [...] 
  </employment:employment>
  Example XML: GitHub

Send the updated information to the record: The final end point must be the corresponding put code for the item to be updated.

  Method: PUT
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type:  Bearer
  Access token: Stored access token
  Data: [Link to file or text of affiliation to add]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/employment/[put code]
  Example call: GitHub 

The API will return a 200 OK message to indicate that the item updated correctly. Check our troubleshooting page if a different message is received.

Deleting a website on an ORCID record

The below example demonstrates how to delete a website your system added to the researcher’s ORCID record.

Use the ORCID iD, access token, and the website’s put code to delete the link. Only one item can be deleted at a time.

  Method: DELETE
  Authorization type:  Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/researcher-urls/[put code]
  Example call: GitHub 

The API will return a 204 NO CONTENT message to indicate that the item updated correctly. Check our troubleshooting page if a different message is received.


Take your system one step further

Besides collecting researchers’ iDs and connecting them with their publications, your system can also:

  • Recognize researchers’ peer review activity: Connect information about your peer reviewers’ activities to their ORCID record with as much or as little detail as appropriate -- see more at the peer review workflow.
  • Add researchers’ works to their ORCID record: Many research organizations collect and verify information about researchers’ published work and research activity to aid the reporting process. If your system has already requested permission to update their research activities data, then you can use the same access tokens -- see more at the publishing systems workflow.
  • Add researchers’ funding activity to their ORCID record: Many research organizations collect and verify information about researchers’ funding information to aid the reporting process. If your system has already requested permission to update their research activities data, then you can use the same access tokens to add funding information -- see more at the funding submission systems workflow.