Integration and API FAQ

Items (works, employment, funding, peer review etc) can be added to an ORCID record either manually or using the ORCID member API. If you are an individual looking to update your record check out our help section on this here. If you are a member looking to add items to an ORCID record, you will need the following:

• The researchers permission
• Member API credentials
• And either:
  • A vendor system that integrates with the ORCID Member API
  • Your own system that integrates with the ORCID Member API

For a complete guide for members using the API to items to a record check out our API tutorial link below:

API Tutorial: Add and Update data on an ORCID record

To support the social component we offer a toolkit of Outreach Resources to help you develop a campaign to support your integration, and communicate to your researchers:

• What ORCID is.
• Why your system collects iDs and how your system will perform tasks, such as updating their records.
• Why your researchers will benefit by creating an ORCID iD and connecting their iDs to your system.
• How ORCID benefits the wider, global research community.

We will be continually building out this “library” of resources based on feedback from the community. If you have an idea for something you might like to see, please feel free to contact us.

Integrating ORCID into your system allows your organization to collect authenticated ORCID iDs and add them to your own data. At the same time, the researcher provides the organization permission to read and write to and from their ORCID record. 

To make this work, organizations MUST obtain authenticated ORCID iDs using the ORCID OAuth API.  This means they include an ORCID branded button or link within their system, that when clicked, asks the user to sign in to their ORCID record.

Once signed in, the user will be asked to authorize access to the system asking for their ORCID iD

The user’s ORCID iD and name on the ORCID record (depending on visibility settings) is returned to the organization as part of this process.   The system can then request additional data from the ORCID API.

The above described workflow for collecting authenticated APIs is available in both ORCID’s public and member APIs. The former is available for use free of charge by non-commercial services.

The process to get permission to add or update data on a user‚s ORCID record uses OAuth, as described in our 3 Legged OAuth FAQ. Only ORCID members can use the Member API to ask for update permissions. In simple terms it works like this:

• Your local system creates a special link
• When clicked, the user is sent to ORCID, signs in and grants permission
• ORCID sends the user back to your system with an ‘authorization code’
• Your system exchanges that code for an ‘access token’
• The access token lets you update the user’s record

ORCID strives to enable transparent and trustworthy connections between researchers, their contributions, and their affiliations by providing a unique, persistent identifier for individuals to use as they engage in research, scholarship, and innovation activities. Ensuring that the correct ORCID iD is associated with the right researcher is a critical step in building the trustworthiness of the ORCID dataset and the broader scholarly communications ecosystem. For this reason, ORCID does not permit the manual collection or entry of ORCID IDs in any workflow where it is possible to collect ORCID IDs directly from record holders themselves.

Researchers can easily and securely share their ORCID iDs with the systems they interact with, which proves they own their ORCID iD. Those systems can then share information about researcher activities with other systems, which creates a chain of validated and trusted assertions about researcher activity. The end result is that the correct person is associated with the correct activities across a broad range of scholarly information workflows.

For more information see: https://info.orcid.org/collecting-and-sharing-orcid-ids/

You can help make life easier for your users by connecting validated information to their ORCID records. You will also be helping to build trust in scholarly communications and, by keeping that data up to date, you can reduce the reporting burden for your users and improve data quality.

ORCID for Research Organisations

In addition to its use as a persistent identifier for your researchers, ORCID can help you take control of how your institution‚s name is used across research systems. In combination with other persistent identifiers ORCID enables you to authoritatively assert your staff, faculty, and student affiliations with your institution. You can also use ORCID APIs to receive real-time notifications about research activities, to auto-update forms, and to follow your alumni’s careers.

ORCID for Funding Organisations

By embedding ORCID iDs in your funding workflows, you can reliably connect your grantees and funding programs — and save everyone time and reduce 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.

ORCID for Publishers

Researchers are at the heart of everything that scholarly and research publishers do. Accurate author and reviewer information is vital to indexing, search and discovery, publication tracking, funding and resource use attribution, and supporting peer review.

ORCID serves as an information hub, enabling your authors and reviewers to reliably connect to their contributions, and to share information from their ORCID record as they interact with your publishing systems. Collecting iDs for all your authors and reviewers during the publication process — whether for books, journals, datasets, compositions, presentations, code, or a variety of other works — allows for information to be easily shared, ensures researchers can provide consent to share, saves researchers time and hassle, reduces the risk of errors and, critically, enables researchers to get the credit they deserve for the important work they’re doing.

Member organizations request ORCID Member API credentials on the production (live) server by completing the Production Member API client application form. Before issuing production Member API credentials, the ORCID Engagement team/Consortia Lead will review a demo of your integration in the ORCID sandbox. This gives us a chance to see the great integrations you have built and offer workflow improvements, as well as check that all integrations meet our best practices and minimal requirements for launch.

To provide a demo of your system you’ll need to set up a working integration with the ORCID sandbox that the ORCID team can preview. There are a few ways to share your working sandbox integration:

1. Recommended: Live demo: Contact us to schedule a live demonstration. We’ll provide meeting software that allows you to share your screen for you to demo your integration. 
2. Test site: If your development site is public, send us the URL along with test credentials (if needed) to access your system and instructions describing how to use your system’s ORCID features. Provide additional documentation to verify what we would not be able to see from the user end, e.g. API version used, what data is stored by your system, etc.
3. Screencast or screenshots :Send a recording or a set of screenshots with descriptions clearly explaining and demonstrating how your integration works at each step, including what happens if a user denies access or disconnects their iD. Be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored

Member organizations request ORCID Member API credentials on the production (live) server by completing the Production Member API client application form. If you are using a vendor system that is not on the list of ORCID Certified Service Providers, your integration will need to undergo a review process to guarantee that the minimum requirements for integration and best practices are met. 

You can contact your non-certified Service Provider and obtain evidence directly from them that the minimum criteria are met. You will need to send this evidence to the ORCID Engagement team or your Consortia Lead.

There are a few ways to share this evidence:

1. Screencast or screenshots: Send a recording or a set of screenshots with descriptions clearly explaining and demonstrating how your integration works at each step, including what happens if a user denies access or disconnects their iD. Be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored.
2. Publicly available integration documentation: Submit a publicly accessible and up-to-date link that includes a clear description of how the integration works at each step. As in option 1, be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored.

Public Client credentials are granted to individuals and not organizations. Credentials cannot be transferred from one individual to another but they can be converted to member API credentials if agreement is received from all parties and the organization is an active member of ORCID.

Moving the Client ID to the Member API won’t alter the Client ID, only the Client Secret, and you will keep the number of connected iDs with your read only permission.

When converting the Public API client into a Member API client the Public Client Terms of Service no longer apply, and they are substituted by the terms of the Member Agreement. 

For the transfer, we would need:

1. Confirmation of the Public API client ID to be converted.
    
2. That the organisation’s main contact and the record holder of the current Public API client ID agree with the change in the Terms of Service. (The record holder needs to be an employee, contractor or officer of the member organization) We will keep a record of both parties’ consent.

3. A date/time for the migration to happen. As part of this migration, we will update the client ID and send you a new client secret in an encrypted e-mail. Please note that once we update the client, your integration will not work until you update the client secret. This is why we need to fix a date and time for this to be done and to prevent inconveniences for users.

For the conversion to be completed, you will need to update: 

• The old client secret to the new client secret. 
• The API host from pub.orcid.org to api.orcid.org. 

With your converted Member API client ID, you can update the scopes to add member API scopes. This will require authorization from users, and new access tokens will be generated to include the new scopes/permissions.

Please note that we are not able to convert Member API clients credentials to Public API credentials.

To support the social component we offer a toolkit of Outreach Resources to help you develop a campaign to support your integration, and communicate to your researchers:

• What ORCID is.
• Why your system collects iDs and how your system will perform tasks, such as updating their records.
• Why your researchers will benefit by creating an ORCID iD and connecting their iDs to your system.
• How ORCID benefits the wider, global research community.

We will be continually building out this “library” of resources based on feedback from the community. If you have an idea for something you might like to see, please feel free to contact us.

You can request sandbox Member API credentials to build and test your application. These credentials allow you to make calls to the sandbox premium member API to read, write to, and update ORCID records. Access to the sandbox testing environment is freely available to anyone, even if you’re not an ORCID member organization.

Note: If you are using an ORCID certified service provider systemthat already supports ORCID, you do not need to register for sandbox API credentials unless you wish to try out the ORCID integration functionality within the Sandbox envrionment. 

The sandbox lets you create test user accounts and develop your integration without having to worry about affecting data on the live (production) ORCID Registry. The sandbox behaves the same way as the production ORCID Registry with a few exceptions.

Creating a test account

In order to test the ORCID API and API calls, such as a reading and adding information to an ORCID record, you will also need to create a test ORCID record in the sandbox. This can be done through the user interface, much like on the production ORCID Registry. Go to https://sandbox.orcid.org/register and register for an account.

Mailinator email addresses

The sandbox server only sends emails to Mailinator (@mailinator.com) email addresses in order to not spam mail servers unintentionally. You will not receive a verification email or password reset notification unless you use a @mailinator.com address, and verification is required in order to make any manual edits to sandbox records. Find out more about their free to use public inboxes here. If you do not wish to use a Mailinator address, then please make note of your username and password (as you will be using them to grant authorization to your application when testing), and contact us to request assistance with verification.

Mailinator is an email service that has a public free service and a private paid service. For testing you can use the completely free public service. Find out more about their tiers here.

Mailinator is a third party service that is not managed or maintained by ORCID. We recommend that you review how this service works and its limitations before using these addresses.

Integrations need to store more than just ORCID records. Your system will need to be able to:

• Accept and store ORCID iDs: Your system will need to know the iD of the ORCID record to display the iD and to update correctly. Store it together with the researcher’s information which is returned in the token exchange response. Our recommendation is to store the full https URI: https://orcid.org/0000-0001-5727-2427.
• Accept and store persistent access tokens and refresh tokens: Access tokens can be used to read and update records, as well as indicate that the iD has been authenticated. Access tokens are valid for approximately 20 years or until the user revokes them. We also recommend you store the token scope, token expiry and refresh tokens. Refresh tokens can be used to create new access tokens with the same or limited scopes if required. Store the access token token data together with the researcher’s information.
• Accept and store put codes : Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API. Save this 6 digit put code along with the item in your system‚ it’s how you will identify which item needs to be read, updated or deleted.
• Provide error messages and a support contact when an interaction does not go as expected.

We recommend that developers test the Public API in the sandbox testing server before using the production version. Below are the steps on how to register for public API credentials in both the Sandbox and Production environments.

• Sign into your ORCID record:
  Production server: https://orcid.org/signin
  Sandbox testing server: https://sandbox.orcid.org/signin
• Click on your name in the top right hand corner
• Click Developer Tools from the menu option
  Note: In order to access Developer Tools, you must verify your email address. If you have not already verified your email address, you will be prompted to do before you can register for public API credentials
• Read and agree to the ‘ORCID Public APIs Terms of Service
• Click the “Register for ORCID Public API Credentials” button.

Completing the Application Details Form

• Once you have registered for your Public API Credentials you will be directed back to Developer Tools (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• You need to complete the application details form presented to register a new application.
  • Name: The name of your application. This will be displayed to users when they grant your application permission to get their ORCID iD, and it will be displayed in their Trusted organization list. We recommend using the name of your organization or service (e.g. a journal name).
  • Application URL: The website the user can visit to learn more about your application. This will also be displayed in their Trusted organization list.
  • Application Description: Information about the application that you are developing and how you will use the user’s ORCID iD. This will be displayed to users on the OAuth screen.

Adding Redirect URIs

Once the user has authorized your application, they will be returned to a URI that you specify. You must provide these URIs in advance or your integration users will experience an error.

• Enter your redirect URI in the box provided
• If you need to enter more than 1 redirect URI, click ‘Add another redirect URI’

Please note:

• Only HTTPS URIs are accepted in production
• Domains registered MUST exactly match the domains used, including subdomains
• Register all redirect URIs fully where possible. This is the most secure option and what we recommend. For more information about redirect URIs, please see our redirect URI FAQ

Saving your application

Once you have completed the application form and added your redirect URIs you can save your application.

• Click ‘Save my application and generate my client ID and secret’

You will be directed back to the developer tools page which will now include your Public API client credentials

Updating your credentials

Making a change to your application information is very simple.

• Edit the relevant information and then click ‘Save application’

Use your credentials

Now that you have your credentials, it’s time to start using the ORCID Public API!

Please note that we can transfer your credentials to the member API if you become an ORCID member in the future.

There are a number of requirements that we expect all member integrations to meet. The ORCID team will ensure these requirements have been met as part of the integration review process. 

• Use OAuth to authenticate ORCID iDs (Do not allow users search for or type in ORCID iDs.)
• Present the OAuth authorization screen according to our guidelines
• Include an ORCID branded button or link on your site to initiate authentication of the iD.
• Use HTTPS for your site’s redirect URIs and on ORCID API calls
• Accept and store all data returned in the token exchange together with the user’s data in your system
• Use appropriate scopes and request methods (e.g. POST calls to add new information and PUT calls to update existing information)
• Publicly display the authenticated ORCID iDs. iDs should be displayed following our trademark and iD display guidelines.
• Do not request users to change their visibility settings for items on their ORCID record to use your integration.

You will need to fill in the form to register a client application. Below is a quick overview of the requested fields:

Name of organization: Your ORCID member organization name

Primary contact email address for credentials: We will use this email address to send you the credentials in an encrypted email, and to contact you if any questions or errors come up with your integration

Secondary email for password: An email address that we can send your encrypted email password to.

Name of your client: This will be your ORCID member organization name. If you have more than 1 integration then we will append the application to the name.

URL of the homepage of your application: Displayed as a link on the list of trusted organizations within the users ORCID trusted parties page. This should be a link back to your organization or the main page of your application.

Short description of your client application: This text will be displayed on the authorization screen with the question mark icon to your integration users. A short description of your integration is required

Redirect URIs: Once the user has authorized your application, they will be returned to a URI that you specify. You must provide these URIs in advance or your integration users will experience an error. 

• Only HTTPS URIs are accepted.
• Domains registered must exactly match the domains used, including subdomains.   
• Register all redirect URIs fully where possible. 
• More than 5 redirect URIs required? Please indicate this in the Notes for ORCID staff.

Notes for ORCID staff: Use this field to let ORCID staff know anything additional about your request or your integration

Search & Link Wizards are integrations that can be used to import items (mainly works) into the ORCID Registry. They must undergo testing between the integrator and ORCID before they can be released to the production registry environment.

Depending on your answers to the questions below, your integration may be a suitable candidate for search and link — please contact us to discuss this further before starting to develop a search and link wizard:

• What is the target audience for the wizard? For example, authors, reviewers, or grant applicants at the national, disciplinary, or global level
• Roughly how large is the expected audience?
• Will it serve a population currently underserved by existing wizards? For example, research contributions in a specific language or discipline, or that are of a novel type
• How will you ensure that the wizard provides a good user experience?
• What user support will you be providing?
• Is there — or will there be — an ORCID point person at your organization, such as a product manager, for the wizard?
• How will you ensure that ORCID iDs are authenticated?
• Do you — or will you — ingest and display ORCID iDs on your platform?
• Is your platform search enabled by iDs?

Please see our Search & Link Workflow for more details.

Member organizations request ORCID Member API credentials on the production (live) server by completing the Production Member API client application form. Before issuing production Member API credentials, the ORCID Engagement team/Consortia Lead will review a demo of your integration in the ORCID sandbox. This gives us a chance to see the great integrations you have built and offer workflow improvements, as well as check that all integrations meet our best practices and minimal requirements for launch.

To provide a demo of your system you’ll need to set up a working integration with the ORCID sandbox that the ORCID team can preview. There are a few ways to share your working sandbox integration:

1. Recommended: Live demo: Contact us to schedule a live demonstration. We’ll provide meeting software that allows you to share your screen for you to demo your integration. 
2. Test site: If your development site is public, send us the URL along with test credentials (if needed) to access your system and instructions describing how to use your system’s ORCID features. Provide additional documentation to verify what we would not be able to see from the user end, e.g. API version used, what data is stored by your system, etc.
3. Screencast or screenshots :Send a recording or a set of screenshots with descriptions clearly explaining and demonstrating how your integration works at each step, including what happens if a user denies access or disconnects their iD. Be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored

Webhooks allow premium members to ‘watch’ ORCID records and be notified of any changes.

Using the API and premium member client credentials, premium members can register a callback URL for each authenticated ORCID iD that they wish to track. The ORCID record holder does not have to grant the organisation specific permission to register the URL but the actual data exchange is based on privacy levels set by the ORCID iD holder. 

With this in place ORCID will notify that specified URL by sending a request when there are changes to the ORCID record.

All affiliation sections use the same set of metadata in the API:

• Organization name:* The name of the organization at the highest level (e.g. “Boston University” rather than “Boston University School of Medicine”).
• Organization city:* City of where the organisation is based.
• Organization region: Region of where the organisation is based.
• Organization country* the country of the organisation. This should be populated with the two letter ISO 3166 Alpha-2 country code.
• Organization ID (ROR, GRID, Ringgold** or LEI):* A unique identifier for the organization and its source. We recommend that the parent organization ID is used within the affiliation and not the division or department.
• Role/Title: The position held, or the degree awarded or to be awarded.
• Department: Any subdivision of the parent organization.
• URL: A URL to a resource about the affiliation
• 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)
• An external persistent identifier describing the affiliation: A unique identifier for the actual affiliation assertion

*Indicates a required field.

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

There are a number of sections under the biography part of an ORCID record:

Also known as: This can include an abbreviated first name, variants including initials for one or more first names, middle name(s), former or alternate name(s), or name(s) in a different character set. Each name should be added as a single item. This is a free text field up to 255 characters.

Websites: This section includes a description (optional) and a website URL (required)

Country: The Country section of an ORCID record allows researchers and member organizations to add one or more countries where they conduct research, or that are the topic of their research. The items in the country list are sourced from ISO 3166, the international standard for country and region codes.

External identifiers (Other IDs): This section can only be added by member organizations. Please note that, although many organizations collect other external identifiers for their researchers, e.g. Scopus Author IDs, only the issuer of those identifiers can assert them authoritatively. We therefore strongly recommend that your organization only adds identifiers which your system(s) created and uses to identify researchers. This section includes four components (* indicates a required field):

• ID type*
• ID value*
• ID relationship*
• ID URL

• Title:* The title of the work
• Subtitle: A subtitle to the work
• Translated-title: The title the work appears under in another language, the language of the translated title is recorded as an attribute
• Journal-title: The name of a larger collection the work belongs to, such as a journal for journal articles or a book for book chapters. Even though this is labelled journal title it can be used for other works
• Short-description: A brief description or abstract of the work
• Citation-type: The format the citation is provided in. This field is selected from a list containing the following values: APA, BIBTEX, CHICAGO, HARVARD, IEEE, MLA, RIS, UNSPECIFIED, VANCOUVER
• Citation-value:  The contents of the citation
• Work-type:  The type of object the work is. This field must be selected from the supported work types
• Publication date: The date the work was published. We recommend the earliest publication date is used
• External-id-type:* The type of identifier. This field must be selected from the supported work identifiers
  • External-id-value:* The identifier itself
  • External-id-url: A url the identifier resolves to
  • External-id-relationship:* Identifiers that apply only to the work being added would be marked as Self. Identifiers that apply to a larger collection this work belongs to would be set to Part-of. Identifiers that apply to alternate versions of the work would be set to version-of. Identifiers that apply to the funding for the work would be set to funded by.
• Work-url:  A url linking to the work
• Work-contributors:  Information about the individuals who created the work
• Language-code: The language used to describe the work in the previous fields
• Country: A country the work was published in or otherwise associated with

* Indicates required field

There are many types of research resources, from single-use reagents to international collaboratives with dedicated facilities.  ORCID supports a high-level model that can link to other places for domain specific detail.  

There are four high-level resource types:

Resource Type	Definition	Examples
Infrastructure	A facility, building, or other physical space used to perform research	Neutron spallation source, animal facility, data enclave, archaeological site, telescope array. ships, planes, farms, laboratories
Collection	An object or group of objects used for research purposes; can be tangible or digital	Ocean mission, field campaign, collaborative data sets or resources, rare book collection; museum collection, biological specimen collection
Equipment	Hardware used for research purposes	Microscope, computers, glassware, samples, materials
Service	Services used for research purposes	Proteomics analysis, computing services, data analysis, logistical support, legal services, copyediting, expert or staff advisement

In addition to resource type, a research resource item within an ORCID record contains the following information. * indicates required items

• Proposal/Registration Title:* This is the main display field for research resources e.g., “Neutron Beam Award” or “Beam time and computing resources”
• Proposal/Registration ID:* This is the public identifier (DOI, PURL, etc.) for the proposal or request to use the resource.  Ideally, this identifier should be persistent and resolve to a public landing page with information about the proposal or request, such as an awards database or resource user log. 
• Proposal Host(s):* This is the organization that receives and processes resource proposals or requests. Proposal Host may be the same as Resource Host
• Proposal Host Organization iD*  This is the public identifier (one of ROR, GRID, Open Funder ID, LEI) for the organization managing the proposal or request process
• Resource(s):* (up to 100)
• Resource Name:* – e.g., “Neutron Spallation Source”
• Resource ID(s):* – from an extensible list of acceptable PID types (e.g. RRID, DOI, URI)
• Resource Type:* – one of ‘Infrastructures’, ‘Collections’, ‘Equipment’, or ‘Services’
• Resource Host(s):* This is the organization that administers or operates the Resource, such as a national laboratory, government agency, or research university 
• Resource Host Organization ID:* This is the public identifier (one of ROR, GRID, Ringgold**, Open Funder ID, LEI) for the organization that hosts the resource
• Proposal URL:  A link to the proposal
• Proposal Start Date:  The date the access started
• Proposal End Date:  The date the access ended or will end

* Indicates required field

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

• Role:* The individual’s role in the review process, which can be selected from: chair, editor, member, organizer, reviewer
• Group identifier:* The group ID that is used for aggregation purposes — for journal articles, the default identifier is the eISSN, which is automatically populated via an integration with the ISSN database. Please note, if you need to assign an identifier other than an ISSN you will need to create it before.
• Convening organization*: The organization which organized the review – a journal publisher, conference organizer, funding agency, faculty, etc
  • Organization identifier: The persistent identifier for the convening organization. We currently support ROR, Ringgold**, GRID, LEI or Crossref Funder Registry identifier. Please note: this is not a mandatory field but we would recommend you post this data if you have it available.
• Review data:* This data refers to the review activity and not what was reviewed
  • Type: The type of review activity: review or evaluation
  • Date: The date the review was completed. This can be broad (2008) or specific (2010-12-10) 
  • Review identifier: A unique, preferably resolvable identifier provided by the source of the review itself. Unless the review is openly available, we recommend that this does not contain identifiable data that can be traced back to the subject of the review 
• Review URL: A link to a representation of the review or review record online 
• Information about the review subject: Whatever the reviewer reviewed
  • Subject type: The type of item that was reviewed, e.g. journal article, conference paper
    • This includes the list of work types AND the list of grant types (“grant”, “contract”,”award”,”salary-award”) AND research-“resource-proposal” AND “undefined” 
  • Subject name: The name of the reviewed item
  • Subject external identifier: The unique identifier of the subject of the review, e.g. an article DOI 
  • Subject container name: The name of the object of which the review subject is part, e.g. the conference for which the paper was reviewed 
  • Subject URL: The URL of the subject that was reviewed 

* Indicates required field

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

• Funding type:* The type of funding awarded, This field is selected from a list containing the following values: Award, Contract, Grant, Salary-award
• Funding title:* The title of the funding item
• Subtitle: A subtitle to the funding item
• Translated-title: The title the funding appears under in another language, the language of the translated title is recorded as an attribute
• Description: A description or short abstract of the funded project.
• Amount: The value of the award
• Unique funding identifier: * Add as many of these as your system is aware, as it aids in grouping on ORCID records.
  • Funding identifier type: Use grant-number, DOI, URI or proposal-id
  • Value of the identifier
  • Identifier URL (optional)
  • 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):*  Information about the organization that awarded the funding
  • Name of the agency
  • Address (city and country)
  • Organization identifier: Supported identifiers are ROR, Fundref and Ringgold** identifiers.
• Start date: The date the funding began
• End date: The date the funding ended
• Contributors information:  Information about the individuals who received the funding
  • ORCID iD: The ORCID iD of each collaborator to the funding project; this should only include authenticated ORCID iDs
  • Role: The nature of the contribution by the researcher

* Indicates required field

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

All affiliation sections use the same set of metadata in the API:

• Organization name:* The name of the organization at the highest level (e.g. “Boston University”, rather than “Boston University School of Medicine”).
• Organization city:* City of where the organisation is based. 
• Organization region: Region of where the organisation is based. 
• Organization country* the country of the organisation. This should be populated with the two letter ISO 3166 Alpha-2 country code.
• Organization ID (ROR, GRID, Ringgold** or LEI):* A unique identifier for the organization and its source. We recommend that the parent organization ID is used within the affiliation and not the division or department.
• Role/Title: The position held, or the degree awarded or to be awarded.
• Department: Any subdivision of the parent organization.
• URL: A URL to a resource about the affiliation
• 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)
• An external persistent identifier describing the affiliation: A unique identifier for the actual affiliation assertion

*Indicates a required field.

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

All affiliation sections use the same set of metadata in the API:

• Organization name:* The name of the organization at the highest level (e.g. “Boston University”, rather than “Boston University School of Medicine”).
• Organization city:* City of where the organisation is based. 
• Organization region: Region of where the organisation is based. 
• Organization country* the country of the organisation. This should be populated with the two letter ISO 3166 Alpha-2 country code.
• Organization ID (ROR, GRID, RInggold** or LEI):* A unique identifier for the organization and its source. We recommend that the parent organization ID is used within the affiliation and not the division or department.
• Role/Title: The position held, or the degree awarded or to be awarded.
• Department: Any subdivision of the parent organization.
• URL: A URL to a resource about the affiliation
• 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)
• An external persistent identifier describing the affiliation: A unique identifier for the actual affiliation assertion

*Indicates a required field.

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

All affiliation sections use the same set of metadata in the API:

• Organization name:* The name of the organization at the highest level (e.g. “Boston University”, rather than “Boston University School of Medicine”).
• Organization city:* City of where the organisation is based. 
• Organization region: Region of where the organisation is based. 
• Organization country* the country of the organisation. This should be populated with the two letter ISO 3166 Alpha-2 country code.
• Organization ID (ROR, Ringgold**, GRID, or LEI):* A unique identifier for the organization and its source. We recommend that the parent organization ID is used within the affiliation and not the division or department.
• Role/Title: The position held, or the degree awarded or to be awarded.
• Department: Any subdivision of the parent organization.
• URL: A URL to a resource about the affiliation
• 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)
• An external persistent identifier describing the affiliation: A unique identifier for the actual affiliation assertion

*Indicates a required field.

**Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info.

An ORCID record may contain information about a researcher’s work, affiliations, funding, peer review, and more.

Items on ORCID records can be broken down into assertions that connect the ORCID iD-holder with an activity or affiliation. These assertions can be added to an ORCID record by the researcher who owns the record, or by systems the researcher has granted permission to do so.  We call the entity that added an assertion to an ORCID record the source.

Examples

Following our principles of transparency and openness, we believe it is important to be able to see the source of the assertion — who is adding that information to the record.  Here is how we do that:

1. When a researcher (or their delegated trusted individual) adds an assertion to their record, ORCID automatically records that person as the source
2. When a system approved by the researcher adds an assertion to a record, ORCID automatically records the system owner (an ORCID member) as the source.

We display the source name in the user interface and make it available (with its unique identifier) in the API:

However, research information workflows can be more complicated than this, and the real source of an assertion can be unintentionally obscured by one system adding an item on behalf of a person or another system. To ensure transparency, we need to distinguish between who made the connection between the person and the item, and who added the item to the record.  As above, whoever adds the item to the ORCID record is the source; whoever creates the connection between the ORCID iD and the item is the assertion origin.

For example:

1. A researcher imports data into their ORCID record from a system, such as a Search and Link wizard. The researcher is making the assertion connecting their iD with the item, so they are the assertion origin; while the system is the entity adding the assertion to the ORCID record — the source
2. A researcher interacts with System A (the assertion origi), which uses services provided by System B to update ORCID records, making System B the source

We encourage our community to engage in taking steps to preserve and share information on assertion origin, so that everyone can benefit from seeing the source.

For more information, please see:

• Assertion Assurance Pathways: What Are They and Why Do They Matter?
• Plans for Enabling Multiple Assertions in the ORCID Registry

Works in ORCID are grouped together based on both their identifiers and those identifiers‚ relationship to the work. There are four types of relationships:

• Self: the identifier refers solely to that work and can be grouped with other works that have the same identifier
• Part of: the work is part of this identifier and cannot be grouped with other works
• Version of: these identifiers apply to alternate versions of the work and can be grouped with self and version of identifiers
• Funded by: these identifiers apply to the funding for the work. These identifiers are not used for grouping works.

Our API provides support for this in the XSD. Each item has a display index attribute which indicates its rank within its group. The highest display index is the preferred item selected by the researcher. Items added via the API which have not been ranked by the researcher have a display index of 1 and are used as the default preferred source within the group until changed by the researcher. The display index also determines the work order when reading the ORCID record with the API.

For more information regarding grouping on ORCID records, please see our support article.

ORCID allows for the addition of several types of works. Below is a list of the work types that are currently supported, which is largely consistent with the CASRAI Output Standard.

Publications

Work type	Use
book	Books written by a single author or collaboratively based on research or scholarly findings generally derived from peer reviewed funding.
book-chapter	Texts written by a single author or collaboratively based on research or scholarly findings and expertise in a field.
book-review	Critical review of works of fiction or non-fiction highlighting the contributions to an art, field or discipline.
dictionary-entry	Entries of new words, new meanings of existing words, changes in spelling and hyphenation over a longer period of time, and grammatical changes.
dissertation	Treatise advancing an original point of view resulting from research: a requirement for a doctoral degree. This is only available with API v2.x
dissertation-thesis	A paper that is typically based on original research and that gives evidence of the candidate‚s mastery both of their own subject and of scholarly method. This is only available with API v3.0+
encyclopedia-entry	Authored entries in a reference work or a compendium focusing on a particular domain or on all branches of knowledge.
edited-book	Books edited by a single author or collaboratively for the dissemination of research or scholarly findings that generally result from peer reviewed funding.
journal-article	Articles in peer-reviewed publications that disseminate the results of original research and scholarship.
journal-issue	Periodical publications aimed at fostering intellectual debate and inquiry.
magazine-article	Articles in thematic publications published at fixed intervals.
manual	Course and assignment materials produced for teaching purposes.
online-resource	Information accessible only on the web via traditional technical methods
newsletter-article	Articles in publications aimed at researchers, decision-makers, professionals and the public that report on a research project or on the activities of a research chair or a research center.
newspaper-article	Articles in a daily, weekly or monthly publication reporting on news and social issues aimed at the public.
preprint	Version of a paper made publicly available before formal peer review and publication. This is only available with API v3.0+
report	Reports disseminating the outcomes and deliverables of a research contract.
review	A formal assessment of another’s work. This is only available with API v3.0+
research-tool	Series of observations, measurements or facts identified from the research.
supervised-student-publication	Articles on research findings published jointly with or supervised by the thesis adviser.
test	Assessments that include tests designed for general university selection, selection into specific courses or other evaluation purposes.
translation	Translations of books and articles that identify modifications to the original edition, such as a new or revised preface.
website	Stand-alone locations on the web where multiple types of information on a specific theme are available.
working-paper	Preliminary versions of articles that have not undergone review but that may be shared for comment.

Conference

Work type	Use
conference-abstract	Texts of a specified length that states the issue to be discussed in a proposed conference paper.
conference-paper	Papers written alone or collaboratively, presented at an academic conference, and published in the proceedings (not in scholarly journals).
conference-poster	Posters displayed in a conference setting and conveying research highlights in an efficient manner by compelling graphics.

Intellectual Property

Work type	Use
disclosure	Publications that establish inventions as prior art thereby preventing others from patenting the same invention or concept.
license	Signed agreements to exploit a piece of IP such as a process, product, data, or software.
patent	A form of IP protection that defines the exclusive right by law for inventors and assignees to make use of and exploit their inventions, products or processes, for a limited period of time.
registered-copyright	Registered ownership of rights under a system of laws for promoting both the creation of and access to artistic, literary, musical, dramatic and other creative works.
trademark	Marks such as a name, word, phrase, logo, symbol, design, image of a product or service that indicates the source and provides the right to control the use of the identifier.

Other

Work type	Use
annotation	Annotations contain comments or descriptions about another resource. This is only available with API v3.0+
artistic-performance	Collection of information records that, in combination, represent a full and up-to-date history of artistic or performance outputs resulting from, or related to, the person’s research or scholarly activities.
data-management-plan	A formal statement describing how research data will be managed and documented throughout a research project and the terms regarding the subsequent deposit of the data with a data repository for long-term management and preservation. This is only available with API v3.0+
data-set	A series of structured observations, measurements or facts identified from the research which can be stored in a database medium.
invention	Practical and original outputs arising from research.
lecture-speech	An informative talk related to research delivered to an audience.
physical-object	A specimen, sample, or other physical object used for research purposes; an inanimate three-dimensional object or substance. This is only available with API v3.0+
research-technique	A practical methods or skills applied to particular tasks identified as part of the research.
software	A program used to operate a computer or other technical device.
spin-off-company	A company set up by a Research Organization to make commercial use of the results and findings of the Research project.
standards-and-policy	The development of a rule or principle that is used as a basis for judgement.
technical-standard	Technical Standards (industrial or otherwise) that have originated from the research projects in which new protocols, methods or materials may be developed.
other	Any other type of work.

Please see our list of supported identifiers for the V3.0 API. We occasionally add new types at the request of ORCID members who would like to use them when adding items to the registry.

ORCID supports the use of  ROR identifiers, GRID identifiers and Crossref Funder Registry identifiers to disambiguate organizations in ORCID records. 

For more information, see Working with Organization Identifiers

Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info

We’ve introduced a new system-generated field, which expresses external identifiers (DOIs, PMCID, PMID, ArXiv, Bibcode, ISSNs, and ISBNs) in a normalized format for the purposes of matching and grouping. Normalization is done based on the rules of the identifier type, and may include setting all alpha characters to lowercase, or transforming spaces, dashes, periods and other characters that can be treated as equivalent. It also adds standard prefixes and suffixes as appropriate. For example, https://doi.org/10.1/123, 10.1/123, and https://dx.doi.org/10.1/123 will all appear in this field as https://doi.org/10.1/123.  The existing identifier value is unmodified.

The contributor field in works and funding allows member integrations to list the researchers who have collaborated on a work or are party to a funded project. For both funding and works, it is possible to include the contributor’s ORCID iD alongside the role. We suggest you add contributor’s ORCID iDs only if you have authenticated the ORCID iD, or have collected the ORCID iD from a source which has authenticated it. Multiple roles can be added. The contributor sequence is used to indicate where in the contributor list the collaborator or other contributor’s names should appear. The 2 options that we support are:

• First
• Additional

Roles for works API 2.0

The below is the list of supported contributor roles using API 2.0.

• author
• assignee
• editor
• chair-or-translator
• co-investigator
• co-inventor
• graduate-student
• other-inventor
• principal-investigator
• postdoctoral-researcher
• support-staff

Roles for works API 3.0

With API 3.0, you can add the roles above plus additional CRedIT roles. The CRediT taxonomy consists of 14 contribution types to scholarly work, along with guidelines on how these roles may be assigned. Below is the complete list with the UI value and the metadata value. The metadata value is the URL as per the NISO implementation recommendations ‘CRediT should be coded in JATS xml v1.2, described via this link: https://jats4r.org/credit-taxonomy.’ Only the URL will be accepted when adding roles via the API.

TERM (UI Value)	URL (API Value)
Conceptualization	https://credit.niso.org/contributor-roles/conceptualization/
Data curation	https://credit.niso.org/contributor-roles/data-curation/
Formal analysis	https://credit.niso.org/contributor-roles/formal-analysis/
Funding acquisition	https://credit.niso.org/contributor-roles/funding-acquisition/
Investigation	https://credit.niso.org/contributor-roles/investigation/
Methodology	https://credit.niso.org/contributor-roles/methodology/
Project administration	https://credit.niso.org/contributor-roles/project-administration/
Resources	https://credit.niso.org/contributor-roles/resources/
Software	https://credit.niso.org/contributor-roles/software/
Supervision	https://credit.niso.org/contributor-roles/supervision/
Validation	https://credit.niso.org/contributor-roles/validation/
Visualization	https://credit.niso.org/contributor-roles/visualization/
Writing – original draft	https://credit.niso.org/contributor-roles/writing-original-draft/
Writing- review & editing	https://credit.niso.org/contributor-roles/writing-review-editing/

Example work contributor metadata:

  https://orcid.org/0000-0001-5109-3700 0000-0001-5109-3700 orcid.org  Laure L. Haak  first author  

Roles for funding

• lead
• co-lead
• supported-by
• other-contribution

ORCID provides a free text citation field so that information can easily be entered in text format by researchers. However, we strongly encourage all API users to add citations in BibTeX, which is machine readable. The venerable format, despite pre-dating the internet, can be transformed into the desired format by integrations and authors. It is supported by most reference managers and publishing platforms

For more about BibTeX, see https://www.bibtex.org.

Any author where their publisher uses Crossref for their DOI registration can benefit from the Crossref auto update integration.

Publishers need to include the authenticated ORCID iDs for their authors within the metadata sent to Crossref at DOI registration.

Crossref will then request permission from the author via a notification to their ORCID inbox to update their ORCID record with this publication and any new publications from any publisher.

For more information please see: https://www.crossref.org/community/orcid/

Each item in the ORCID iD is assigned a put code which uniquely identifies it. When reading an entire record or section, the put code can be found as an attribute of the item. When calling a specific item on a record, the put code is used to identify the item. Put codes are unique within the type of item they refer to. Using this example, only one work in the ORCID Registry will have the put code 733535, though 733535 may also used as a put code for a funding item or a keyword

As a benefit of ORCID membership, organizations can ask ORCID to support additional PID types in the ORCID Registry.  For example, a member could request that we add support for the PIDs they use for identifying samples or datasets in their geology database.  This enables links between the samples and the people who collected them. And, because all new PID types that we add must be at least resolvable, and preferably FAIR, those links are unambiguous, persistent over time, and actionable – benefitting the researcher, the member organization, and the wider community.

Adding Your PID!

As a community organization, we want to ensure that ORCID supports the PIDs used by our members. We maintain a complete list of existing identifiers supported in the Registry and invite ORCID members to use this form to request additional PIDs. We aim to respond to your request as soon as possible.

ORCID has a separate section in the ORCID record to record information about qualifications, accreditation, certificates and badges.

Each qualification item will always contain:

• The qualification title
• The provider’s Organisation ID (e.g. ROR ID)
• The date it was added to the ORCID record
• Who added the qualification (the source)

They may contain:

• The validity date, including an end date if the qualification expires
• The qualification persistent ID, identifying the type of qualification gained.
• The qualification URL, which contains human readable description of the type of qualification earned.
• The qualification persistent ID. This should link to an online version of the qualification certificate. This could be an existing unique ID or simply a URI.

Anyone with public or member API credentials can receive a /read-public access token. To obtain a token, you make a call to the ORCID API token endpoint.

This process is often referred to as the client-credentials OAuth flow, or 2-step OAuth.

An example call to obtain an access token to read public data on the sandbox — replace the placeholders with your credentials (be sure to remove the brackets.

URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  METHOD: POST
  DATA: 
    client_id=[Your public API client ID]
    client_secret=[Your public API secret]
    grant_type=client_credentials
    scope=/read-public

You will then be returned an access token similar to the following. The token returned is long-lived (not expiring for approximately 20 years) and can be used multiple times to retrieve public data from ORCID records. 

{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}

Note: All tokens with the /authenticate scope now also have /read-public scope included. If you use only the /authenticate scope, you can use the stored access tokens to read public data without needing to again obtain an access token. 

Integrators using the member API can use the /read-public scope to read ORCID record summaries.

To obtain /read-limited access, you must ask the researcher for permission. You do this using OAuth. Specifically, “3 legged OAuth“.

For more information please see our API Tutorial: Read data on an ORCID record

ORCID integrations use “3 legged OAuth” to authenticate users and request permission to interact with their records. Any integration can ask for read permissions using the Public API. ORCID members can use the Member API to ask for update permissions. It works like this:

• You create a special link
• When clicked, the user is sent to ORCID
  • ORCID asks the user to sign in
  • ORCID asks the user to grant permission to your application
  • ORCID sends the user back to your system with an authorization code
• Your system exchanges that code for an access token

The customized authorization URL includes your client information, as well as the ‘scopes’ that specify the specific areas of their record that you wish to access. After signing in, the user authorizes the connection with your system and is returned to your landing page along with an authorization code. This code is then used to get their ORCID iD along with an access token valid for the requested scopes.

Build the authorization link and get and authorization code

You build your authorization link by specifying your API credentials’ client ID and associated landing page (redirect URI). You choose which permissions to ask for by setting the scope parameter.

The below example requests permission to read limited-access data on the ORCID sandbox testing server. In the real world you display this link on your website, or include it in an email when asking the user to authenticate and authorize. However, for testing purposes you can simply paste it into your web browser. Replace the bracketed data with your client information and be sure to remove the square brackets!

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

One the user has clicked the link, signed in at ORCID and granted permissions they are redirected back to your site, like this:

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

Exchange the authorization code for an ORCID iD and access token

You should immediately exchange the authorization code for the ORCID iD and access token. The authorization code expires upon use. The request looks like this and cannot be made in a web browser, it must be made by your server.

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

ORCID will then return the researcher’s authenticated ORCID iD and an access token in JSON format:

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

Access tokens are long lived by default and expire 20 years after issue. The token can be used multiple times before it expires.

Use the access token

3-legged access tokens are linked to specific ORCID record. To use them, you include them in API requests you make to read or update that record.

When requesting permission to interact with an ORCID user’s record, you specify one or more ‘scopes’. Each scope allows you to do certain things, such as read the record, or update a particular section.

3-legged (authorization code) scopes

3 legged refers to the three actors involved in obtaining permission from a user; ORCID, your system and the user themselves.

/authenticate

This scope is used to collect the ORCID iD and read public information on the record only. All other 3-legged scopes include the authenticate permission, so this scope can be omitted if asking for any other access. This scope is available on the Member or Public API.

/read-limited (Member API only)

This scope is used to get access to read public and limited visibility items on an ORCID record. This scope is only available on the Member API.

/activities/update (Member API only)

This scope is used to write, update and delete items in the affiliation, funding, works, professional activities, research resources and peer-review sections of an ORCID record. This scope is only available on the Member API.

/person/update (Member API only)

This scope is used to write, update and delete items in the other-names, keywords, countries, researcher-urls, websites, and personal external identifiers sections of the record. This scope is only available on the Member API.

openid

This scope is used by OpenID integrators when an id_token is required. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user. This scope is available on the public and member API.

Please note that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification. Please see our OpenID documentation for more information.

Multiple scopes

Multiple scopes can be requested in a single interaction by listing the scopes in the authenticate URL with an encoded space between each, such as scope=/read-limited%20/activities/update%20/person/update

Complete access

If you want full access to read and edit a record include three scopes in your authenticate URL: /read-limited, /activities/update and /person/update. In the URL they would appear as scope=/read-limited%20/activities/update%20/person/update

2-legged (client credential) scopes

For some activities you do not have to ask the user for permission. Two legged OAuth scopes are requested directly from the ORCID API and do not require the researcher to grant permission. Tokens with these scopes are valid for 20 years and can be reused

/read-public

This scope is used to read public information on a single ORCID iD,search for ORCID records or to read summary information (member API only). This scope is available on the Member or Public API.

/webhook

This scope allows a client application to register a webhook on an ORCID record, in order to receive notifications when a record is updated. This scope is available to premium ORCID members only.

If you are concerned with multiple users being on the same machine and not signing out between sessions, you can force them to re-authenticate during the OAuth process. Simply include prompt=login in the OAuth request. You can also set a max_age in seconds to force users to re-authenticate if their session is over a certain length. See our OpenID Connect documentation for more details.

Users can change their display language on their own at any point. The following language settings are available:

Language	Code
عربى (Arabic)	ar
čeština (Czeck)	cs
English	en
Español (Spanish)	es
Français (French)	fr
Deutsch (German)	de
Italiano (Italian)	it
日本語 (Japanese)	ja
한국어 (Korean)	ko
Polski (Polish)	pl
Português (Portuguese)	pt
Русский (Russian)	ru
Türkçe (Turkish)	tr
简体中文 (simplified Chinese)	zh_CN
繁體中文 (traditional Chinese)	zh_TW

Any or all of the parameters can be used:

Parameter	Field	Notes
given_names	Given name	The first name field will be filled in on the registration form if a specified email address or ORCID iD does not match that of an active ORCID record.
family_names	Family name	The last name field will be filled in on the registration form if the specified email address or ORCID iD does not match that of an active ORCID record.
email	Email	The email/ORCID iD field will be filled in on the sign-in form if the specified email address is found in our system and no valid ORCID iD is specified.The email field will be filled in on the registration form if the specified email address is found in our system and no valid ORCID iD is specified.The email address should be URL encoded, including changing “@” to “%40”.If you know the user’s ORCID iD and email address, we suggest only providing the ORCID iD in the orcid parameter.
orcid	ORCID iD	The email/ORCID iD field will be filled in on the sign-in form if the specified ORCID iD is found in our system.The registration form will otherwise be displayed if the specified ORCID iD is not found in our system.The ORCID iD must be in the 16-digit format of the iD URI.

An example URL with these parameters is

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYIn&response_type=coden&scope=/authenticaten&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplaygroundn&family_names=Finn&given_names=Huckleberry&email=huckle%40mailinator.com

If an active access token already exists with the same scopes that your OAuth authorization URL requests, and the user is signed into their ORCID record, they will not be prompted to grant authorization again. Instead they will be taken directly to the redirect URI. If you want to require a user to grant authorization every time they connect, use the force sign-out method

Implicit OAuth is a lighter weight version of OAuth designed to be used by systems that do not have, or do not want to use server side components. Implicit OAuth can be implemented entirely in the browser using javascript alone. It is available for members and non-members and works like this:

• You create a special link
• When clicked, the user is sent to ORCID
  • ORCID asks the user to sign i
  • ORCID asks the user to grant permission to your application
  • ORCID sends the user back to your system with their ORCID iD, an access token and an id token.
• Your system extracts and stores the authenticated ORCID iD from the response.

For security reasons, when using implicit OAuth, ORCID will not return access tokens with update permissions.

Implicit flow

The implicit flow is designed so that clients do not need to use their secret key to initiate ORCID sign in. Security is enforced by restricting clients to their registered redirect_urls. This lower level of security means that ORCID only supports the /authenticate and openid scopes when using the implicit flow. Tokens are also short lived, with a 10 minute lifespan. This flow is recommended for client side applications which do not have access to a back end server, for example phone applications or single page javascript web-apps.

https://localhost/#access_token=24c11342-f5da-4cf9-94a4-f8a72a30da00&token_type=bearer&expires_in=599&tokenVersion=1&persistent=false&id_token=eyJraWQiOiJxYS1vcmNpZC1vcmctcjlhZmw3cWY2aG2c5bmdzenU1bnQ3Z3pmMGVhNmkiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiMW52bXZBbVdwaVd0Z3ZKZW1DQmVYUSIsImF1ZCI6IkFQUC02TEtJSjNJNUIxQzRZSVFQIiwic3ViIjoiMDAwMC0wMDAyLTUwNjItMjIwOSIsImF1dGhfdGltZSI6MTUwNTk4Nzg2MiwiaXNzIjoiaHR0cHM6XC9cL29yY2lkLm9yZyIsIm5hbWUiOiJNciBDcmVkaXQgTmFtZSIsImV4cCI6MTUwNTk4ODQ2MywiZ2l2ZW5fbmFtZSI6IlRvbSIsImlhdCI6MTUwNTk4Nzg2Mywibm9uY2UiOiJ3aGF0ZXZlciIsImZhbWlseV9uYW1lIjoiRGVtIiwianRpIjoiY2U0YzlmNWUtNTBkNC00ZjhiLTliYzItMmViMTI0ZDVkNmNhIn0.hhhts2-4-ibjXPW6wEsFRaNqV_A-vTz2JFloYn7mS1jzQt3xuHiSaSIiXg3rpnt1RojF_yhcvE9Xe4SOtYimxxVycpjcm8yT_-7lUSrc46UCt9qW6gV7L7KQyKDjNl23wVwIifpRD2JSnx6WbuC0GhAxB5-2ynj6EbeEEcYjAy2tNwG-wcVlnfJLyddYDe8AI_RFhq7HrY4OByA91hiYvHzZ8VzoRW1s4CTCFurA7DoyQfCbeSxdfBuDQbjAzXuZB5-jD1k3WnjqVHrof1LHEPTFV4GQV-pDRmkUwspsPYxsJyKpKWSG_ONk57E_Ba--RqEcE1ZNNDUYHXAtiRnM3w

See our technical documentation for more information.

What are redirect URIs and how are they used?
Redirect URIs are used by our OAuth authentication service as a security measure.  ORCID will only send authenticating users to URIs registered by the client requesting authentication.  This prevents services from impersonating each other.

Please note that only HTTPS URIs are accepted in production. You can test using HTTP URIs but you will need to register HTTPS URIs when you apply for production member API credentials.

How do we match redirect URIs?

• You MUST register subdomains as separate URIs. https://anythingelse.thirdparty.com will not work.  
• Registering all redirect URIs fully, including path is encouraged, is what most third parties do and is the most secure option.
• If the client app is registered with a redirect uri that is just the host name, then any redirect uri at that host can be used. So, for example if the following redirect uri is registered: https://thirdparty.com then all of the following redirect_uris will work:
  • https://thirdparty.com/oauth/callback1
  • https://thirdparty.com/callback2
  • https://thirdparty.com/anything-else-as-long-as-the-host-is-the-same

However, https://anythingelse.thirdparty.com will not work.  You MUST register subdomains as separate URIs.

What happens if my redirect URI is incorrect?

Users sent to authenticate at ORCID with incorrect redirect URIs will see an error message similar to this:

Managing redirect URIs for members

If you are using the member API and require any changes to your redirect URIs then please contact our Engagement Team

Managing redirect URIs for public clients

If you are using the public API then you will need to follow the steps below to update your list of redirect URIs that are associated with your ORCID public API client ID. You can do this by following the steps below:

• Sign in to your ORCID record
• Click your name in the right hand corner
• Select developer tools
• Click the edit pencil next to the client name
• Edit an existing redirect URI or click ‘Add another redirect URI’ edit an existing one
• Once you have made your changes you need to click the save icon

Only HTTPS URIs are accepted in production. You can test using http URIs but you will need to register HTTPS URIs when you apply for production member API credentials.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It supplements existing OAuth authentication flows and provides information about users to clients in a well described manner.

OpenID connect is a standardised way of implementing OAuth and sharing information about authenticated users. It will now be possible to configure services to use ORCID “out of the box” alongside other standards compliant OpenID connect providers. OpenID connect also provides sharable ID tokens, which are signed objects that can prove a user authenticated using ORCID at a specific time. These tokens can be used by user interface elements to maintain user sessions.

ORCID supports the Basic OpenID Provider conformance profile, which is an extension of the OAuth authorization code flow. ORCID also supports the implicit token flow for the “/authenticate” and “openid” scopes.

This means that ORCID:

• Embeds signed id tokens within token responses for authorization codes generated with the ‘openid’ scope
• Supports the implicit flow when using ‘token’ or ‘token id_token’ response_types and the ‘openid’ scope.
• Supports the ‘prompt’, ‘nonce’ and ‘max_age’ parameters for authorisation requests that include the ‘openid’ scope.
• Supports Openid Connect discovery and userinfo endpoints
• Supports the ‘amr’ field for integrators using the member API for authorisation requests that include the ‘openid’ scope. This can be used to discover if a user authenticated using two factor authentication.

Initiating an OpenID Connect authentication works the same way as a regular OAuth authentication. All that is required is that the client request the ‘openid’ scope If you are using the /authenticate scope replace it with openid, as authenticate and openid have the same authorization only one or the other should be used. If you are using any other scopes, add openid to the list of scopes requested. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user.

ote that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification.

See our technical documentation for more information.

ORCID allows users to enable Two-factor authentication (2FA) on their ORCID account. 2FA is a secondary security check made during the sign-in process. It provides additional confirmation that the user is indeed the person signing into an ORCID account. For more information relating to how this can be configured for users please see our KB article.

OpenID connect integrators using the member API can check to see if the user had signed into their ORCID account with 2FA enabled as part of the OAuth process. This can allow member integrators to grant access to their researchers to higher security systems.

In keeping with our commitment to researcher control of their ORCID record, the record holder can choose to revoke any access token at any time by deleting it from permissions in the Trusted Organization list under their Trusted parties page.

As of 2018, researchers can only grant long-lived access tokens which last for 20 years unless the user revokes permission.

ORCID provides a simple Java Script widget that can be used to obtain authenticated ORCID iDs using OAuth with OpenID Connect.

Please note that the widget uses implicit OAuth, so does not collect any write permissions. This means it is not suitable for member integrations that wish to update records. Please see our tutorial for Adding and Updating data on ORCID records.

Public Client credentials are granted to individuals and not organizations. Credentials cannot be transferred from one individual to another but they can be converted to member API credentials if agreement is received from all parties and the organization is an active member of ORCID.

Moving the Client ID to the Member API won’t alter the Client ID, only the Client Secret, and you will keep the number of connected iDs with your read only permission.

When converting the Public API client into a Member API client the Public Client Terms of Service no longer apply, and they are substituted by the terms of the Member Agreement. 

For the transfer, we would need:

1. Confirmation of the Public API client ID to be converted.
    
2. That the organisation’s main contact and the record holder of the current Public API client ID agree with the change in the Terms of Service. (The record holder needs to be an employee, contractor or officer of the member organization) We will keep a record of both parties’ consent.

3. A date/time for the migration to happen. As part of this migration, we will update the client ID and send you a new client secret in an encrypted e-mail. Please note that once we update the client, your integration will not work until you update the client secret. This is why we need to fix a date and time for this to be done and to prevent inconveniences for users.

For the conversion to be completed, you will need to update: 

• The old client secret to the new client secret. 
• The API host from pub.orcid.org to api.orcid.org. 

With your converted Member API client ID, you can update the scopes to add member API scopes. This will require authorization from users, and new access tokens will be generated to include the new scopes/permissions.

Please note that we are not able to convert Member API clients credentials to Public API credentials.

This example call retrieves a summary of the full ORCID record in XML format using the member API on the sandbox server. You need an access token to make an API requests to the Public or Member API.

Method: GET
Accept: application/vnd.orcid+xml 
Authorization type and Access token: Bearer [Stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/record

The API will return a 200 OK message, indicating that the request was received successfully, and the full summary of the ORCID record, including summaries of individual items

<?xml version="1.0" encoding-"UTF-8" standalone="yes"?>
<record:record path="/0000-0001-2345-6789"
xmlns:internal="https://www.orcid.org/ns/internal" [...]>
<funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">
 [...]
</record:record>

Each item (work, funding, employment etc) has a put code. This can be used to obtain full details of the item if needed.

The ORCID record is divided into individual sections to make reading the record faster and more consistent. You can first call a section to receive its summary, and then call using an individual item’s put code to receive robust information on that item.

A table of the summary sections that you can use the API to read are set out below.

Endpoint	Description
/record	Summary view of the full ORCID record
/person	Biographical section of the ORCID record, including through /researcher-urls below
/summary	Summary view of validated and self asserted items on the ORCID record (only available with the member API)
/address	The researcher’s countries or regions
/email	The email address(es) associated with the record
/external-identifiers	Linked external identifiers in other systems
/keywords	Keywords related to the researcher and their work
/other-names	Other names by which the researcher is know
/personal-details	Personal details: the researcher‚s name, credit (published) name, and biography
/researcher-urls	Links to the researcher‚s personal or profile pages
/activities	Summary of the activities section of the ORCID record, including through /works below.
/educations	Education affiliations
/employments	Employment affiliations
/fundings	Summary of funding activities
/peer-reviews	Summary of peer review activities
/works	Summary of research works
/research-resources	Summary of research resources
/services	Summary of services
/qualifications	Summary of qualifications
/memberships	Summary of memberships
/distinctions	Summary of distinctions
/invited-positions	Summary of invited positions

Items (works, employment, funding, peer review etc) can be added to an ORCID record either manually or using the ORCID member API. If you are an individual looking to update your record check out our help section on this here. If you are a member looking to add items to an ORCID record, you will need the following:

• The researchers permission
• Member API credentials
• And either:
  • A vendor system that integrates with the ORCID Member API
  • Your own system that integrates with the ORCID Member API

For a complete guide for members using the API to items to a record check out our API tutorial link below:

API Tutorial: Add and Update data on an ORCID record

This example call retrieves a summary of the full ORCID record in XML format using the member API on the sandbox server. You need an access token to make an API requests to the Public or Member API.

Method: GET Accept: application/vnd.orcid+xml
Authorization type and Access token: 
Bearer [Stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/record

The API will return a 200 OK message, indicating that the request was received successfully, and the full summary of the ORCID record, including summaries of individual items.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>
     <funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">
  [...] 
  </record:record>

Each item (work, funding, employment etc) has a put code. This can be used to obtain full details of the item if needed.

To support the social component we offer a toolkit of Outreach Resources to help you develop a campaign to support your integration, and communicate to your researchers:

• What ORCID is.
• Why your system collects iDs and how your system will perform tasks, such as updating their records.
• Why your researchers will benefit by creating an ORCID iD and connecting their iDs to your system.
• How ORCID benefits the wider, global research community.

We will be continually building out this “library” of resources based on feedback from the community. If you have an idea for something you might like to see, please feel free to contact us.

Before you can add an item to the ORCID record you will need to format your data into the ORCID schema. Format your data in the ORCID message schema in XML or JSON.

Our GitHub repository contains resources that will help with formatting when creating new items on the ORCID record, and when reading existing items on the ORCID record:

• Example XML files
• The XSD for all sections of the ORCID record

ote that different versions of the API have different message formats. Version 2.0 and 2.1 schemas and examples are also available.

More examples can be easily found by reading the metadata of a well populated record.

Earlier version of the ORCID API had additional scopes. These scopes were phased out with the 2.0 API. We encourage all integrations to only use the recommended scopes. For reference the earlier scopes are listed below with the current scope that should be used instead

• /orcid-profile/read-limited use instead /read-limited
• /orcid-works/read-limited use instead /read-limited
• /orcid-bio/read-limited use instead /read-limited
• /orcid-works/create use instead /activities/update
• /orcid-works/update use instead /activities/update
• /affiliations/create use instead /activities/update
• /affiliations/update use instead /activities/update
• /funding/create use instead /activities/update
• /funding/update use instead /activities/update
• /orcid-bio/update use instead /person/update
• /orcid-bio/external-identifiers/create use instead /person/update

Refresh tokens are used to generate additional access tokens. A refresh token is returned with the access token when exchanging an authorization code as part of the three-legged OAuth processes, and it can be used as long as the access token remains active.

The new access tokens can have the same expiration and scopes as the original access token, or can be specified to have a shorter lifespan as well as a smaller subset of scopes from the original access token. New access tokens can be generated in order to replace the original token or generated to serve as an additional token. You can also use refresh token calls to fully expire the original access and refresh tokens and any permissions granted by the user. 

We suggest using refresh tokens in the following conditions:

• Replacing access tokens that may have been compromised (be sure to revoke the original access token after)
• Giving a third party that is also a part of your ORCID integration more limited access and/or access for a limited time.

Please refer to our technical documentation on how to create new access tokens from refresh tokens.

There are two different update scopes – one for biographical details, the other for activities.

Scope	Description	API endpoints
/person/update	Biographical data-the left column of the ORCID record user interface.	/address /external-identifiers /keywords /other-names /researcher-urls
/activities/update	Research activity data-the right column of the ORCID record user interface.	/distinction /distinctions /education /educations /employment /employments /funding /fundings /invited-position /invited-positions /membership /memberships /peer-review /peer-reviews /qualification /qualifications /research-resource /research-resources /service /services /work /works

Use your client ID, secret, and either the active token or its associated refresh token to revoke the token pair. You can revoke token pairs created in both the two-legged and three-legged OAuth processes.  If you have multiple sets of tokens, e.g. for different scopes, only the specified access token and corresponding refresh token will be revoked.

We suggest revoking tokens in the following conditions:

• To revoke tokens issued to a third-party supplier after the termination of a relationship;
• To revoke tokens when users disconnect their ORCID iD from your system;
• To allow users to revoke tokens from within your system.

We recommend using the refresh tokens to limit the scope or duration of an existing access token or update a token if it has been compromised.

The revoke API call

https://sandbox.orcid.org/oauth/revoke (or https://orcid.org/oauth/revoke)
  METHOD: POST
  HEADER: accept:application/json
  CONTENT-TYPE: application/x-www-form-urlencoded 
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    token=[access token or refresh token for token pair to be revoked]

All items (apart from the biography text) on an ORCID record have a put code:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>   
<record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>      
<funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">   [...] 
</record:record>

This put code can be used to make a call to the API to retrieve the full data for an item. The following items can be queried using a put code:

Endpoint	Description
/address/[put code]	An individual country or region
/biography	The biography field: a free text area that only the researcher can edit
/education/[put code]	An individual education affiliation item
/email/[put code]	An individual email address associated with the record
/employment/[put code]	An individual employment affiliation item
/external-identifier/[put code]	An individual linked external identifier in another system
/funding/[put code]	An individual funding activity
/keywords/[put code]	An individual keyword related to the researcher and their work
/other-names/[put code]	An individual additional name by which the researcher is know
/peer-review/[put code]	An individual peer review activity
/researcher-urls/[put code]	An individual external link to the researcher‚s personal or profile page
/work/[put code]	An individual research work
/works/[put code1],[put code2],[put code3]	Bulk individual research works (up to 100)

Using the section endpoint and put code, you can call the API using your same access token to get that specific item in full. This example call retrieves the full funding item 4413 in XML format using the member API on the sandbox server.

Method: GET Accept: application/vnd.orcid+xml Authorization type and Access token: Bearer [stored access token]URI: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/funding/4413

Example call: GitHub

The API will return a 200 OK message to indicate that the message was received successfully and return the full XML of the funding item:

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
    <funding:funding put-code="4413" path="/0000-0002-9227-8514/funding/4413" visibility="public"  [...] >
    [...] 
    </funding:funding>

You can check the source of an item when reading it if you want to know who added it.

A list of common API error codes, their possible meanings and tips on how to troubleshoot them is available within our technical documentation.

If you are not able to resolve the issue that you are experiencing the please do let us know.

ORCID members can update information they’ve previously added to an ORCID record. Only one item can be updated at a time, and it can only be updated using the client credentials that created it in the first place.

To facilitate updating, make sure you store the put code and access token when creating items.

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="739288" [...]>     [...]            </employment:employment>

Call the API:

Method: PUT Content-type: application/vnd.orcid+xml or application/vnd.orcid+jsonnAuthorization type and Access token: Bearer [stored access token]Data: link to file or text of affiliation to update URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288

Example calls: 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.

Visibility indicates the privacy setting of the item, based on the user’s set visibility preference. If a visibility tag is included when information is posted via the API, it will be ignored. Rather, the information will be posted per the user’s default visibility preference as set in their account preferences.

Public items can be read by anyone via the API and are shown on the researcher’s public record, Trusted party items are only returned via the API to clients who have read-limited access; they are not on the researcher’s public record. Private items are visible only to the researcher and the source of the item – the only private items returned via the API are those which were added to the record via your integration More about visibility settings in the ORCID Registry.

Items (works, employment, funding, peer review etc) can be added to an ORCID record using the ORCID member API. To do this, you must first obtain permission from the researcher using OAuth and format the item metadata using the ORCID message schema.

Once you have formatted the data and collected the ORCID iD and access token, you make an API request using HTTP POST, specifying the relevant endpoint.

Method: POST 
Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]data: link to file or text of single employment item to add 
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment

The call below adds a new employment affiliation to a record on the sandbox testing server:

<?xml version="1.0" encoding="UTF-8"?>      
<employment:employment [...]>     
[...]            
</employment:employment>

Example call: Github

The API will return a 201 message to indicate that the item posted correctly, along with the item put code. Your client will be listed as the source of the item.

Check our troubleshooting page if a different message is returned. You will need to save the  store the put code and access token to make any updates or remove the item.

The ORCID search API uses the SOLR syntax. All query syntaxes available in SOLR 3.6 are supported, including Lucene with Solr extensions (default), DisMax, and Extended Dismax.

You need a “/read-public” access token to use it. Once you have obtained your search token, build your base search URL:

Credentials type:	Public API	Member API
Resource URL:	Sandbox: https://pub.sandbox.orcid.org Production: https://pub.orcid.org	Sandbox: https://api.sandbox.orcid.org Production: https://api.orcid.org
API version:	v3.0
Search endpoint	/search/?=[query]

An example call to search for “orcid” with the token on the sandbox public API with the results returned in XML format is:

Method:  GET Content-type: application/vnd.orcid+xmlnAuthorization type and Access token: Bearer [stored access token]URL: https://pub.sandbox.orcid.org/v3.0/search/?q=orcid

The results will specify the number of results found (num-found) and display the first 1000 results by default:

 <?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
  <search:search num-found="385" xmlns:search="https://www.orcid.org/ns/search"  xmlns:common="https://www.orcid.org/ns/common">
  <search:result>
  <common:orcid-identifier>
    <common:uri>https://sandbox.orcid.org/0000-0001-2345-6789</common:uri>
    <common:path>/0000-0001-2345-6789</common:path>
    <common:host>sandbox.orcid.org</common:host>
  </common:orcid-identifier>
  </search:result>
  [...]
  </search:search> 

An example basic search on the sandbox public API with results returned in json format:

Method: GET
Content-type: application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]
URL:  https://pub.sandbox.orcid.org/v3.0/search/?q=newman

The search returns only the individual ORCID iDs of records holding public data matching the search. To obtain more information about the result, make a call to read the ORCID record directly.

For more information, see our Search API tutorial.

If you have added data that needs to be deleted, for example, if it has been associated with the wrong ORCID iD, then you can make an HTTP DELETE request specifying the relevant endpoint, along with the ORCID iD, stored access token, and stored put code. Only one item can be deleted at a time, and you can only delete items added by your client. You can delete items even when the user has revoked permission.

This example call deletes the employment item with the put code “739288” from a record”

Method: DELETE 
Content-type:  application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288

Example call: GitHub

The ORCID search API uses the SOLR syntax. All query syntaxes available in SOLR 3.6 are supported, including Lucene with Solr extensions (default), DisMax, and Extended Dismax.

You can use a fielded search when you need to search a specific section of the ORCID record. The current list of fields recognized in the API search, along with their corresponding record structure elements, are as follows:

Search field	Description
Biographical data
given-names	The given (first) name(s) of the user.
family-name	The family (sur)name of the user.
credit-name	The “published name” on the ORCID user interface, the name that normally appears on publications by the user
other-names	Alternative names that may have appeared on publications by the user.
email	The email address of the user.
keyword	Any keywords associated with the user.
external-id-reference	Identifiers from other systems added to the user‚s ORCID record using the API.
Affiliations data
affiliation-org-name	The name of any organization in an education or employment item in the user’s record.
grid-org-id	The GRID ID of any organization in the activities section of the user’s record. Generally this will be associated with an education or employment item.
ror-org-id	The ROR ID of any organization in the activities section of the user’s record. Generally this will be associated with an education or employment item.
ringgold-org-id	The Ringgold ID* of any organization in the activities section of the user’s record. Generally this will be associated with an education or employment item.
Funding data
funding-titles	The title of any funding item in the user‚s record.
fundref-org-id	The Crossref Funder Registry ID of any organization in the activities section of a user‚s record. Generally this will be associated with a funding item, but it may also be associated with an affiliation.
grant-numbers	Grant number (identifier) of any funding item in the user’s record.
Research activities data
work-titles	The titles of any work in the user’s record.
digital-object-ids	A work external identifier with type doi
doi-self	A work external identifier with type doi and the external identifier relationship set to self
[external identifier type]*	A work external identifier with the given type
[external identifier type]*-self	A work external identifier with the given type and the external identifier relationship set to self
[external identifier type]*-part-of	A work external identifier with the given type and the external identifier relationship set to part-of
[external identifier type]*-version-of	A work external identifier with the given type and the external identifier relationship set to version-of * For a full list of external identifier see the identifiers list. Some identifiers may require “-self” “-part-of”  or “-version-of” to return results
ORCID record data
orcid	The 16-digit ORCID identifier of the user, in 0000-0001-2345-6789 format.
profile-submission-date	The date and time the record was created.
profile-last-modified-date	The date and time the record was last modified.
All data
text	All the above fields. This is also the default field for Lucene syntax queries.

See our Search API Tutorial for more information.

*Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info

In real-world situations, API interactions are completed by your system using a programming language such as PHP, Java, or Ruby on Rails. For practice and testing, you can interact with the ORCID APIs using a range of tools capable of making and receiving HTTP requests. Most desktop HTTP tools are run in the command line; for those who prefer a graphical interface, web-based tools are a useful alternative.

XML/XSD VERIFICATION

There are many tools that will verify your XML for you; it is a good idea to adopt one. For many of the API calls you will be working with XML-formatted information. Particularly when working with the ORCID API Message, it will be important that the XML that you use is valid against the XSD. (See our documentation on GitHub for the ORCID message schema XSD.)

ORCID SANDBOX TESTING SERVER

The sandbox testing server is a copy of the ORCID Registry software, and only contains testing data. It was designed to provide a place to try things out without affecting any real ORCID iDs, particularly if you are working with the ORCID API and need a place to test your work. You can create user accounts and test out API calls on the sandbox without needing to worry about affecting production data or accidentally spamming researchers.

You do not even need to be an ORCID member to try out the member API in the sandbox. All are welcome to request sandbox member API credentials and try out the full features available to the member API.

The site and APIs will not be as reliable as they are for the production servers. We make no guarantees about data on the sandbox; they are not backed up and may be deleted. The sandbox may also contain some experimental functionality that is not yet on the production servers so you can try things out before they exist in the Registry. Learn more about the sandbox testing server or request client credentials.

HTTP TOOLS

There are many tools available to run HTTP requests. Some we use:

• cURL
• Postma
• wget
• hurl.it
• Google OAuth 2.0 Playground
• Swagger: member API (sandbox), public API (sandbox)

Webhooks can be registered by premium members against any ORCID record in the registry. The steps are:

Encode the URL

URL-encode the URL that you want ORCID to call when the user‚s record is updated. For example the following URL:

https://nowhere2.com/0000-0002-7465-2162/updated

becomes

https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated

Build the URL

Build the full URL for the ORCID API call starting with the URL of the ORCID record then adding ‚√∫/webhook‚√π and the URL you want called. So it should look like https://api.sandbox.orcid.org/{ORCID}/webhook/{URL-ENCODED-WEBHOOK-URL}

For example, using the webhook URL above and the ORCID iD 0000-0002-7465-2162, the full URL is:

https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated

Register the webhook

Use your webhooks‚ access token to register your webhook against the user‚s ORCID record. You need to use an HTTP PUT request, but you should not include anything in the body of the request.

URL= https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdatedn   HEADER: Accept: application/json   HEADER: Authorization: Bearer [Your access token]n   HEADER: Content-Length: 0n   METHOD: PUT

The response should be a 201, but if the callback already existed, then the response will be 204.

HTTP/1.1 201nServer: nginx/1.1.19nConnection: keep-alive Location: https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Frequestb.in%2Fz57lzcz5

The URL for unregistering a webhook is the same as for registering. However, you need to use the HTTP DELETE method.

URL= https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated
   HEADER: Authorization: Bearer [Your access token]
   HEADER: Content-Length: 0
   METHOD: DELETE

The response should be 204 No Content.

HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
Date: Fri, 05 Apr 2013 12:49:17 GMT

The ORCID Registry will do the following HTTP call when a record is updated. The request uses the HTTP POST method, but the body of the request is empty.

curl -v -X POST https://nowhere2.com/0000-0002-7253-3645/updated

Your server should respond with standard HTTP response codes. So, if the call was successful you should return 204 No Content.

HTTP/1.1 204 No Content

Any 2xx response code means that the call was successful. If you return a code that is not a 2xx, then we will retry the call five minutes later.

In real-world situations, API interactions are completed by your system using a programming language such as PHP, Java, or Ruby on Rails. For practice and testing, however, you can interact with the ORCID API using a range of tools capable of making and receiving HTTP requests. Most desktop HTTP tools (such as cURL) are run in the command line; for those who prefer a graphical interface, web-based tools are a useful alternative.

One popular tool is Google’s OAuth 2.0 Playground, a free, web-based tool developed and maintained by Google.

Please see our hands on API tutorial at: https://info.orcid.org/hands-on-with-the-orcid-api/

Note: ORCID does not maintain the OAuth 2.0 Playground – this tool was created by Google, who exclusively maintains its code. While we update this documentation periodically, there may be some inaccuracies from time to time, as we may not be immediately aware of changes to the OAuth 2.0 Playground.

For our API version 2.0 and above the limits are:

• Request a second – 24
• Burst – 40

Request a second – Number of request that can be made a second.

Burst – Number of request we will allow to be queued before rejecting. Requests in the queue are slowed down to the rate of requests a second. If you exceed the burst, you’ll get a 503 response.

If you experience problems with the limits then please do reach out to your Engagement Team Lead for support.

Researcher control is a core ORCID principle so email addresses registered and added to the ORCID record are, by default, set as only visible to the record holder. Unverified emails do not display in the public view of the record and only email addresses that have been verified will appear in API results.

Once researchers have verified their email address, they must choose to make it visible to everyone (i.e. public) or to trusted parties (i.e. limited access) in order for the email address to be read by third parties organisations.

If the researcher has set their email address to Trusted Parties, it will be returned with the record if the researcher has granted you read-limited access. For more information, see ORCID visibility settings.

API 3.0 is the default API version and we recommend that when building new integrations that you use this version. We will continue to support API 2.0 and 2.1 for the foreseeable future, and will provide at least 12 months notice before switching off those versions.

We learned a lot during the transition from API 1.2 to API 2. This time we’ve made the upgrade much easier to manage.  API 3.0 adds new functionality while only modifying existing functionality when absolutely necessary. This means integrators should be able to switch to the new API with a minimum of fuss. It also means that, although we recommend you start to plan your upgrade as soon as possible so that your organization and researchers can benefit from the new features, you have a lot of flexibility in deciding when to update to 3.0.  

The small list of potentially breaking changes are in our API release notes here and here. There are a few changes around optional/mandatory fields, JSON enumerations have been modified slightly, and we also have a small refactoring of our XML schemas, adding some new fields to contain the metadata required for the new functionality.

Please see the ORCID vendor-enabled systems page for publishers for the most up-to-date information

Anyone premium member can obtain a ‘/webhook’ access token. A single token can be used to register webhooks for multiple records. To obtain a token, you make a call to the ORCID API token endpoint. 

This process is often referred to as the client-credentials OAuth flow, or 2-step OAuth.

Below is an example call to obtain the access token — replace the placeholders with your credentials (be sure to remove the brackets.)

curl -i -L -H "Accept: application/json"
  -d "client_id=(your client ID)"
  -d "client_secret=(your client secret)"
  -d "scope=/webhook"
  -d "grant_type=client_credentials"
  "https://sandbox.orcid.org/oauth/token"

You will then be returned an access token similar to the following.

{"access_token":"5eb23750-1e19-47a3-b6f6-26635c34e8ee",
  "token_type":"bearer",
  "refresh_token":"c7d3d5fd-e4c0-4825-89f2-7cfb4a1cf01e",
  "expires_in":631138518,
  "scope":"/webhook"}

Yes we do! You can read more about our API versioning, the rationale behind it and more, here at our API Version Policy.

As we continue to develop our products, there are a number of features that are only available with API 3.0 which is our latest and default API version.

The table below provides a short description of each feature. If you have any questions regarding any of the features or upgrading to 3.0 then please reach out to your Engagement Lead or your Consortia Lead.

Ability to read and write all affiliation types (membership, service, invited positions, distinctions, and qualifications are not available with previous versions of the API)

Ability to read and write Research Resources.

Ability to read and write work identifiers with relationship type ‘Funded By’. This is used to link Grant or Proposal IDs to work metadata.

Ability to read and write work identifiers with relationship type ‘Version of’. This is used to link other versions of the work together. An example use case would be linking the preprint and the published article.

Ability to read and write CRediT roles within works metadata.

Ability to read the additional source fields common:assertion-origin-client-id and common:assertion-origin-name for affiliations added by the ORCID member portal and works added by search and link wizards.

Ability to read and write works with work type of: annotation data-management-plans dissertation-thesis preprint physical-object review

Ability to read and write external IDs for affiliations.

Organization IDs are mandatory for adding affiliations and funding to ORCID records.

Formalizing Identifiers – We introduced a new system-generated field, which expresses external identifiers (DOIs, PMCID, PMID, ArXiv, Bibcode, ISSNs, and ISBNs) in a normalized  format for the purposes of matching and grouping. Normalization is done based on the rules of the identifier type, and may include setting all alpha characters to lowercase, or transforming spaces, dashes, periods and other characters that can be treated as equivalent. It also adds standard prefixes and suffixes as appropriate. For example, https://doi.org/10.1/123, 10.1/123, and https://dx.doi.org/10.1/123 will all appear in this field as https://doi.org/10.1/123.  The existing identifier value is unmodified.

More detailed information can be found here.

They receive a notification in their ORCID inbox. Whenever there is a change in data on an ORCID record, the user receives a notification with basic information about the change, including the name of the client performing the update, date of change, and the item in the ORCID record that was updated. See our user Knowledge Base for more about notifications.  

ORCID records on the sandbox also have functioning inboxes. We recommend regularly looking through the inboxes of your testing ORCID records when planning how your systems will schedule data updates. 

Updates and other announcements for API users are shared via the ORCID API Users Group. You can also subscribe to general messages and updates via the ORCID Blog.

ORCID members also receive the ORCID Member Newsletter where this information is included. Finally, the technical contact for any ORCID member with an active, custom-built integration will also receive email messages about any critical updates to the ORCID Registry. If you want to be listed as a technical contact for your organization, please contact us.

ORCID is committed to being open and transparent. This means our product roadmap is available for anyone to view, as is the work currently in development.

The Product Roadmap is central to the ORCID product development process. Requirements travel from team-managed trello boards, through the Product Roadmap trello board and onwards to the Current Development trello board, where they are implemented and moved to our production systems.

This board contains well-defined requirements that are scheduled for implementation at some point, and a list of prioritised requirements scheduled for implementation in the near term.

Where do requirements come from?

Requirements are gathered from many sources by ORCID staff. They may originate from member requests, consortium feedback, user testing, strategic projects and bug reports amongst others. In addition, all ORCID teams generate their own internal requirements, such as website changes, infrastructure upgrades and operational systems updates. Each card is tagged with the team that produced the requirement – comms, strategy, tech, engagement or operations.

How do things on the roadmap?

ORCID aims for a balanced product development cycle and has regular cross-team meetings to discuss near and long term priorities. We try our best to address bugs, new features, technical debt, website updates and strategic items equally.

How can I contribute to the roadmap?

We welcome suggestions on how to improve the ORCID registry. Please send any feedback to our team.

In addition, ORCID is an open-source project and we welcome contributions to our source code as well as all our repositories.

A preprint is a complete scientific manuscript that is uploaded by the authors to a public server.  The preprint contains complete data and methodologies; it is often the same manuscript being submitted to a journal.  After a brief quality-control inspection to ensure that the work is scientific in nature, the author‚s manuscript is posted within a day or so on the Web without peer review and can be viewed without charge by anyone in the world. Based upon feedback and/or new data, new versions of your preprint can be submitted; however, prior preprint versions are also retained.  Preprint servers allow scientists to directly control the dissemination of their work to the world-wide scientific community. In most cases, the same work posted as preprint also is submitted for peer review at a journal.  Thus, preprints (rapid, but not validated through peer-review) and journal publication (slow, but providing validation using peer-review) work in parallel as a communication system for scientific research.

Watch the video on YouTube

Note: This content and video originally appeared on the ASAPBio website Thanks to ASAPBio for making it available under a CC-BY Licence!

The member newsletter sent monthly from ORCID previously contained a link to a Google Drive folder where all of your member reports were stored. This has now been replaced with new reports available to all members in the member portal.

Previous reports:

• Premium members with active integrations receive a unique link to a folder containing separate, customized reports with data for each integration in the prior month.
• Premium members who don’t have an active integration yet receive a unique link to a folder containing customized reports with email statistics for their institution, as well as a link to a folder which contains general reports with aggregated data for all active member integrations.
• Basic members receive a link to a folder containing general reports issued twice annually with aggregated data for all active member integrations in the prior half year; the first half of the year report is issued in July (January-June data), the second half of the year report issued in January (July-December of the following year).

If you are an ORCID member and do not currently receive the monthly member newsletter, please contact [email protected]

Premium members with active integrations

The Google Drive folder contains a member report for each of the production client iDs issued to you. The file names include the display name of the client iD and the date of the report; please sort by date modified to find the most recent report. There is also a raw_data folder containing the data used to generate the report, which is available for additional analysis if required.

Premium members who don’t have an active integration yet

The Google Drive folder contains a member report with email statistics data only, as well as a link to a Google Drive folder of general monthly reports with aggregated data for all active member integrations, for the current and previous years. Raw data is not available for these reports.

Email domain counts

This section provides counts of ORCID iDs currently registered your institution’s email domains(s) across all time periods. To generate these counts, we search for domains that match the website URL we have on file for your organization (ex: if your website URL is www.universitycollege.edu, we search for emails ending in @universitycollege). If we don‚t have a website URL on file, you‚ll see ‚√∫No email domains provided‚√π in this section. If we didn‚t get your email domain quite right, or if you‚d like to add additional domains, please contact us.

• Records registered to your email domains¬¨‚Count of unique ORCID iDs that include an address within your institution‚s email domain(s)
• Records registered to your email domains AND associated with your client ID¬¨‚Count of unique ORCID iDs that include an address within your institution‚s email domain(s) AND that include your institution as a Trusted Party (ie: records that your institution has a valid access token for)

Created and claimed records

(Note: most clients will not have this section in their reports)

If you have an institutional client that was used to create records on behalf of researchers via the API, you will receive a section called Registry Statistics. This includes information about the number of records you created and how many have been claimed (the raw_data file contains more information about the specific records used to generate these numbers).

Users

This section of the report contains a total count of the number of researchers who used your integration to connect their ORCID iD to your system over the month of reporting. In addition, it gives the total number of those researchers who signed up for a new ORCID iD as a part of the iD connection process. 

The graph labelled Total Integration Events shows the number of researchers who used your integration over the last month, by day

Events

The report also contains events information, the actions that the researcher completed when connecting their ORCID record with your system in the month of reporting. Each event represents any access the user granted or action they did on the ORCID site (such as signing in or giving read-limited access). Most researchers will have more than one event associated with them.

If an event has a ‚√∫√π appended to it, this signifies that the researcher granted a long-lived (Ppersistent) token, as compared to a short-lived token which expires in one hour. Since March 2018, only long-lived tokens are supported on the ORCID Registry; your integrated system or the user can choose to revoke the token at any time. 

Users by country

The final section of the reports contains information about the researchers who used your integration broken down by the country from which they accessed your integration. This data is derived from a researcher‚s IP address or their Geographical ID (itself determined by Google from the researcher‚s IP address).

Sampling

Because so many researchers use the ORCID Registry, it‚s not feasible to run reports on the entire set of researcher data. Instead the numbers provided here are produced using trends from a sampled and non sampled set. The sections of the report derived from sampled data are signalized with an asterisk, and the sampled size and space are specified  on the  Analytics data tab. The numbers in the Google Analytics section of the report may not entirely match any local statistics you keep, and there may be small discrepancies in the count between sections of the report.

The sampling parameters listed beneath Integration Analytics apply to all all sections marked with an asterisk. The percentage of sessions captured by the analytics data is (sample size)/(sample space) * 100%. Further information on sampling can be found at Google Developers.

Empty reports

The Users and Events sections of the report only include data from the past month. If no researchers have used your integration in the past month, then no data will be returned.

Questions

If you have any questions about your member reports, please contact us.

The ORCID Registry is designed to have users provide their iDs to organizations using OAuth, which ensures that the correct iD is collected for each researcher. We discourage organizations from adding ORCID iDs to their systems based on a search for researchers by name. However, it can be helpful to find out how many researchers at your organization have ORCID iDs, which can be done via the API. Suggestions for searching by organization are given below.

For an introduction to searching, how to get an access token, how to understand your search results, and details of other fields that can be searched, please see our Searching the registry API Tutorial

Search by name and DOI

When checking to see if an individual has an ORCID record, we recommend searching by both their name and the DOI of one or more of their recent works. This should result in just the record of the researcher you are looking for, and not records of anyone else who shares the same name.

An example call to search for all records with the name “Laurel Haak” and either the DOI 10.1087/20120404 or the DOI 10.6084/M9.FIGSHARE.1115124: 

Method: GET
Content-type: application/vnd.orcid+xml
Authorization type and Access token: Bearer [stored access token]
URL:  https://pub.orcid.org/v3.0/search?q=family-name:Haak+AND+given-names:Laurel+AND+digital-object-ids:%2210.1087/20120404%22+OR+digital-object-ids:%2210.6084/M9.FIGSHARE.1115124’%22

Search by affiliation

The affiliation fields can be searched using either the name of the affiliation or the organization’s unique ROR ID or GRID ID.  (You can find your organization’s GRID ID in GRID or your ROR ID in the ROR registry)

Search by organization name

Method: GET Content-type: application/vnd.orcid+xml
Authorization type and Access token: Bearer [stored access token] 
URL: https://pub.orcid.org/v3.0/search/?q=affiliation-org-name:"University+of+Johannesburg" 

Or for an exact match

Method: GET
Content-type: application/vnd.orcid+xml
Authorization type and Access token: Bearer [stored access token]
URL: https://pub.orcid.org/v3.0/search/?q=affiliation-org-name:(%22Boston%20University%22)

Search by GRID ID

An example call to search for all records with the GRID ID grid.5509.9 (University of Tampere):

Method: GET
Content-type: application/vnd.orcid+xml
Authorization type and Access token: Bearer [stored access token]
URL: https://pub.orcid.org/v3.0/search/?q=grid-org-id:grid.5509.9

Search by ROR ID

An example call to search for all records with the ROR ID 04fa4r544 (ORCID):

Method: GET
Content-type: application/vnd.orcid+xml
Authorization type and Access token: Bearer [stored access token]
URL: https://pub.orcid.org/v3.0/search/?q=ror-org-id:"https://ror.org/04fa4r544"

Search by email domain

You can use the API to search for researchers by email domain. Keep in mind that around 97% of email addresses in ORCID are private and any records with a private or trusted-access email address will not be returned in this search.

An example call to search for all records with an @orcid.org email address:

Method: GET
Content-type: application/vnd.orcid+xml
Authorization type and Access token: Bearer [stored access token]
URL:  https://pub.orcid.org/v3.0/search/?q=email:*@orcid.org

Search results returned in CSV format

Search results can also be returned in CSV format. As part of the call you can specify the output columns from a list of available fields below:

orcid
email
given-name
family-name
given-and-family-names
credit-name
other-name
current-institution-affiliation-name
past-institution-affiliation-name 

Using your credentials you need to specify the header to be ‘text/csv’. As part of the search call, you need to add the fields that you require on the output to the query too.  

Searching using just your browser

You can also complete the search using your browser. The URL is constructed the same way but you do not need to use any API credentials. Please note that this can only be completed using the public API. 

Below is an example call using the public API searching by organisation name with the ORCID, given names, family names, current institution affiliation name and past institution affiliation name as the desired output. 

https://pub.orcid.org/v3.0/csv-search/?q=affiliation-org-name:ORCID&fl=orcid,given-names,family-name,current-institution-affiliation-name,past-institution-affiliation-name

Below is another example call using the public API searching by different variations of the organizations name.

https://pub.orcid.org/v3.0/csv-search/?q=affiliation-org-name:("University of Plymouth" OR "Plymouth University")

The eduPerson schema added the eduPersonOrcid attribute in its February 2016 update.

As per the eduPerson specification:

  RFC4512  definition
  ( 1.3.6.1.4.1.5923.1.1.1.16
  NAME 'eduPersonOrcid'
  DESC 'ORCID researcher identifiers belonging to the principal'
  EQUALITY caseIgnoreMatch
  SYNTAX  '1.3.6.1.4.1.1466.115.121.1.15' )

Note that the format for this field is the ORCID-preferred URI representation of the iD, i.e. https://orcid.org/0000-0001-5727-2427.

Further information about the format of the ORCID iD can be found in Structure of the ORCID identifier.

ORCID was founded on the principle that researchers should have control over their information.  To honor this principle we have a strong privacy policy, which was designed to take account of local variations in privacy regulations, and we focus on the perspective of the researcher when developing policies and functionality.

In keeping with our core principle of researcher control, ORCID records can only be created by researchers themselves, on the ORCID website.

As part of your integration workflow your researchers will be able to register for a new ORCID iD or sign in to their existing record enabling you to collect their authenticated ORCID iD. Please see our API tutorials for more information.

If you believe that the data showing on your report is inaccurate then please contact us with as much detail as possible and our Engagement Team will investigate.

If you organization is an ORCID member then you need to reach out to the ORCID contact at your organization who will be able to provide you access to the ORCID Member Portal. If you are unable to identify your organizations ORCID contact then please contact your Consortium Lead or your Engagement Team rep.

We love feedback from our community so please let us know if you have any feedback on the member reports by contacting us at https://support.orcid.org/hc/en-us/requests/new

We have compiled a guide to walk you through each section of the reports. The guide can be found here.

The data which is used to produce the member and integration reports is updated daily.