Workflow: Funding submission systems

This workflow sets out a process in which a typical funding submission 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 funding items to ORCID records, and updating funding items which you have previously added to ORCID records. It is based on version 2.0 of the ORCID message schema.

Not every funding submission system will fulfil every element of this process—many systems may only collect researchers’ iDs and display them in grant records and metadata. You can also take your integration one step further by recognizing reviewers’ peer review activity on their records.

Introduction

Understanding the impact of your funding programs is vital to your strategy, program design, and mission alignment. By embedding ORCID iDs in your funding workflows, you can reliably connect your awardees and funding programs—as well as saving everyone time and reducing errors caused by manual keying of information. Using ORCID in your system(s), you can play your part in building a trusted research information infrastructure by asserting connections between individuals and the grants you award them.

Common integration points for funding submission systems:

  1. Before you start: system setup
  2. Collect grant applicants’ ORCID iDs
  3. Display iDs in your systems and website
  4. Connect grant information to awardees’ ORCID records
  5. Synchronize 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 messages, which can be on pages pages:
    • Start message: Where researchers initiate the connection process
    • Connection-success message: This message should display 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 thank you or acknowledgement message.
    • Connection-failure message: This message should display 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.
  • 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 grant applicants’ iDs and biographical information

Research funders, including professional and scholarly associations, can integrate ORCID into existing application and review systems to collect authenticated ORCID iDs and to gain permission to read from/write to your applicants’ and reviewers’ ORCID records (either immediately, or in the future).

The ORCID iDs that you collect can be used in your local systems to uniquely identify individuals. You can also request permission to use their ORCID record information, such as name, education, current affiliation, and contributions to populate their profiles in your systems. You can collect iDs at the time of application or when a grant is awarded.

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, on the submission form itself, or even in a customized email to an applicant. 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 grant applicant’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 and in grants, then you need only /read-limited access to an ORCID record. (If you are using the public API, replace this with /authenticate.)

If you are planning to add funding information to awardees’ ORCID records, then you should request both /read-limited and /activities/update access.

The below example requests permission to read data visible to trusted parties as well as to write activities to ORCID records on the sandbox server. 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&redirect_uri=[Your landing page]

Obtain an access token to get the grant applicant’s ORCID iD: The applicant 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 applicant, e.g. “Thanks for connecting your ORCID iD!” or simply display their iD in full—see Display.

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","orcid":"0000-0001-2345-6789","name":"Sofia Garcia"}

If the user denies your system access: ORCID returns the applicant 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 display the connection-denied message or direct the applicant to a connection-denied landing page. We strong recommend that you use this opportunity to explain more fully to the applicant 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 ORCID iD and access token in your system in a safe and secure manner. Both items will be required to perform any action to the 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 to read public data.

Use the grant applicant’s iD and access token to read their record and populate their profile in your system: Save applicants time by allowing them to quickly and easily transfer data from their ORCID records to your system by making a call to their record; the below example calls the member API on the sandbox server:

  Method: GET
  Accept: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/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 within your system

The best way to signal that the iDs you collect are actually being put to use is to display them—on your website, with an applicant’s user profile, with their award—and to embed them in your metadata. This also helps familiarize all researchers with the ORCID iD icon so they recognize it and know to use their own iD in future.

Including ORCID iDs in metadata and displaying it on your website and systems requires that you have collected validated ORCID iDs from researchers as described above in Collect.

Once a researcher has connected their ORCID iD to your system, clearly display their iD within their profile and/or on their submission 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 iconhttps://orcid.org/0000-0001-2345-6789


Connect information about the grant to awardees’ records

You can help make life easier for your awardees by connecting validated information about grants and funding to their ORCID records—and you will also be helping to build trust in scholarly communications. Document the grant by adding an entry to the Funding section of awardees’ ORCID records. You can also recognize project collaborators whose authenticated ORCID iDs you have collected in each item’s contributor section. This benefits you, your awardees, and the wider scholarly community.

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. 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.

Adding funding to an ORCID record

Format the funding item in ORCID Message Schema: The work must be created in XML or JSON in the ORCID Schema.  Sample XML for for creating works can be found in our GitHub repository.

At the minimum, the funding item must include the following elements:

  • Funding title
  • Funding type: grant, contract, award, or salary oward
  • Unique funding identifier: Add as many of these as your system is aware, as it aids in grouping on ORCID records.
    • Funding identifier type (only grant_number is allowed)
    • Value of the identifier
    • Identifier URL (option)
    • Relationship: self/part-of
      This is to indicate the relationship of the funding item to the identifier. For example, if the funding item is for one phase of a multi-part grant, and the identifier is for the multi-part grant, then the relationship would be “part-of”; if the identifier is for the individual phase, then the relationship would be “self”.
  • Funding agency (organization)
    • Name of the agency
    • Address (city and country)
    • Organization identifier: We support the use of FundRef IDs

We also suggest that you include all other known metadata available for a funding item, in particular:

  • Start and end dates for the funding.  
  • Contributors information
    • ORCID iD: The ORCID iD of each collaborator to the funding project; only include authenticated ORCID iDs
    • Role: The nature of the contribution by the researcher

Add the funding item to the researcher’s ORCID record: Use the ORCID iD and access token you have stored for the researcher to add the item to their record using the 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 funding item to add
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/funding
  Example call: GitHub

Save the returned put code(s) in your system in association with the funding item. The API will return a 201 Created message to indicate that the item posted correctly. Check our troubleshooting page if a different message is returned.

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

Synchronize your system’s data with researchers’ ORCID records

Updating data between your system and your awardees’ ORCID records helps reduce the reporting burden for them—and you—and improves data quality for everyone.

Synchronize data between your system and ORCID by automatically updating ORCID records and 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 a funding item on an ORCID record

Funding items added by your system may in future need to be amended or deleted from researchers’ records. Data 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

Funding item incorrectly attributed to researcher

Adding new data, e.g. identifiers, end date

Peer review or funding item incorrectly added as work

Send a call to the API to update using the ORCID iD, access token, the updated funding item, and the item’s put code. Only one funding item can be updated at a time.

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

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

Add the updated funding item to the ORCID record: The final end point must be the corresponding put code of the funding itemto 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 funding item to update
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/funding/739286
  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 returned.

Deleting a funding item from an ORCID record

Use the ORCID iD, access token, and the item’s put code to delete the funding item via an HTTP DELETE command. 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]/funding/739286
  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 returned.


Take your system one step further

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

  • Recognize researchers’ peer review activity: Connect information about your peer reviewers’ activities to their ORCID record with as much or little detail as appropriate—see more at the Peer Review workflow