Repository Systems

Browse our API User Group topics for more information about setting up an integration with the Public API. However, to maximize the benefits of ORCID, we recommend you join ORCID as an organizational member, which offers access to additional functionality, personal assistance of our integration team, and of course helps support our work.

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.

Consortium Members – A list of your consortium members with an affiliation count. From this list you can drill through to the individual members affiliation report to see the affiliation data in more detail.

Consortia Member Organization IDs – A list of your consortium members registered organization IDs including the identifier type, value and name.

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.

We recommend that you read our written documentation. If you still have questions and are an ORCID member, please contact support; non-members can join the ORCID API Users Group.

You can check the status of both our production server and sandbox server by calling the following:

Sandbox

• https://pub.sandbox.orcid.org/{{version}}/pubStatus
• https://api.sandbox.orcid.org/{{version}}/apiStatus

Production

• https://pub.orcid.org/{{version}}/pubStatus
• https://api.orcid.org/{{version}}/apiStatus

You can also check a daily overview at http://status.orcid.org/

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

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.

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.

Items (works, employment, funding, peer review etc) can be added to an ORCID record using the ORCID member API. 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

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.

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.

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

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.

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.

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.

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

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)

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

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

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

The ORCID registry supports “content negotiation”. This means machines and other systems can ask ORCID registry for person metadata in different formats.

One of these formats is JSON-LD, which uses the schema.org vocabulary, specifically the Person type, which we connect with works, organisations and other identifiers. We also support XML, JSON, RDF XML and turtle, and have implemented Cross-origin resource sharing (CORS) to make it our data easy to access.

• See this blog post for an overview of ORCID and schema.org
• See our technical documentation on content negotiatio

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.

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.

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.

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

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.

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

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"}

This section shows how many authentications your integrations are processing

Monthly unique OAuth Users

Number of users overtime that connected to your integration(s) via OAuth. Note that this data is sampled‚ meaning the numbers given are estimated by extrapolating from a subset of user activity..

This section shows how many ORCID records are connected to your email domain(s)

iDs with email domain(s):

A metric counting the total number of iDs that have an email address ending in one of the registered domains. If you would like additional domains added then please let us know. 

Emails with domain(s) over time:

A graph showing the use of registered domains over time.  Researchers may have registered more than one email address, and this graph counts all of the researcher’s addresses.

Domain distribution:

A chart showing the breakdown of email domains matching the registered domains.  E.g if example.com is registered, this will show the split between “apple.example.com” and “banana.example.com”

Please note that email domains are not a reliable source of data to be used for the number of researchers at your organisation. Many researchers use generic webmail services. 

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.

Monthly unique OAuth Users: Number of users overtime that connected to your integration(s) via OAuth.  Note that this data is “sampled” meaning the numbers given are estimated by extrapolating from a subset of user activity.

Monthly Integration Sign-In Events (June 2023 Onwards): Number of sign-ins overtime that have connected to your integration via OAuth.

API reads: Number of API GET calls overtime that your integration has made.

Searching for a user using cURL like so:

curl -iL https://orcid.org/0000-0000-0000-0000

Will return a 200 even if the user does not exist. To avoid this, use content negotiation in your call like so:

curl -iL -H 'Accept: application/xml' https://orcid.org/0000-0000-0000-0000

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

You collect authenticated IDs when you ask a researcher to sign in with their ORCID iD. This process uses a technology called “OAuth” or “SSO” and should be built into your workflow.

See the API Tutorial ‘Get an Authenticated ORCID iD‘ for more details.

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.

Collecting validated ORCID iDs for individuals through the OAUTH process is important. Individuals sign into their ORCID accounts using their registered email address and password or they can create a new account and then authorize your system to obtain their ORCID iD. This ensures you get the correct ORCID iD for the researcher and that the information on that record reflects their research activities (see What’s So Special About Signing I).¬¨‚

As well as having access to the member API, you also benefit from:

• Technical and communications support from ORCID staff, who are based in 14 countries around the world and who collectively speak 13 languages
•  Being listed as the source of information you add to ORCID records
•  Receiving regular reports on the use of your ORCID integration (monthly for premium members, twice yearly for basic members)
• Getting advance warning of ORCID news, updates, and events via our monthly member newsletter
• Being able to nominate someone from your organization to stand for the ORCID Board and voting in our annual Board elections

ORCID membership allows you to do more than just collect ORCID iDs. It entitles you to access the ORCID member API, which means you can connect information to your authors‚ and reviewers‚ ORCID records, and you can read information in their records that they have tagged as Trusted Parties (ORCID members), as well as their publicly available information.

Any journal or organization can collect iDs without joining ORCID, using our public API. ORCID membership requires your journal to pay an annual membership fee.

Please complete this form or contact us at membership@orcid.org

You can check our list of members¬¨‚

Your journal won’t be a member in the sense that you can get direct technical support or stand for the ORCID Board/vote in Board elections. But, depending on the type of membership that your publisher or institution has, you may have access to other member benefits, such as using the member API.

Yes – our fees are available on our membership page

Please see our Brand Guidelines for displaying ORCID in journal articles.

Yes (see question 10)

• The public API is available for everyone to use. It must be linked to an individual user’s ORCID iD and, if that individual leaves your organization, you will need to set up a new set of credentials. You can use the public API to collect authenticated ORCID iDs and to read publicly available information in ORCID records

• The member API is only available to members. In addition to collection authenticated iDs and reading publicly available information, you can also read information marked Trusted Parties, and connect information to ORCID records, for example, about your authors‚ publications. Basic membership entitles you to one set of credentials (one integration), while premium membership provides you with up to five sets of credentials (five integrations)

ORCID auto-update enables authors to have their ORCID records automatically updated. It works like this:

• The publisher collects the author‚s ORCID iD during the publishing process (usually during manuscript submission)

• The publisher includes the iD in the metadata when registering a DOI for the publication

• The author receives an email from the DOI registry (currently Crossref) asking permission to update their record OR the author creates a DataCite profile and links it to their ORCID record

• The author grants Crossref or DataCite permission to update their ORCID record (they only have to do this once)

• Every time Crossref or DataCite register a DOI that includes the author‚s ORCID iD they automatically update their record

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

Yes. For more information, please read our documentation

ORCID iDs are for individuals only. Publishers interact with ORCID by integrating with our APIs to collect iDs, and to import and export data from and to ORCID records. Learn more in our publishing workflows documentation

DOIs are persistent identifiers for objects, most commonly for publications of all sorts (journal articles, books, book chapters, datasets, etc). ORCID iDs are persistent identifiers for people, and specifically for people involved in the research community – whether directly as researchers, authors, or reviewers, for example – or in supporting roles such as librarians, publishers, funders, etc.

ORCID relies on two mechanisms to transfer personal data under the GDPR. First, ORCID obtains the consent of its users at the time of registration to the transfer of personal data from the EU to the US. Second, ORCID enters into the Standard Contractual Clauses (SCCs) with member organizations as needed.

Yes, ORCID does transfer personal data from the EU to the US as part of its network infrastructure. The live registry software is hosted on servers located within the US.

Yes, in addition to the safeguards discussed above, ORCID incorporates the following supplementary measures to address data protection. 

Data Subject Control. Users are provided with a high amount of transparency and control related to the information shared with ORCID and other users or member organizations. ORCID has taken actions to minimize the amount of personal data needed to establish an ORCID record, requiring only a first name and email address. In addition, ORCID makes it clear that its tools and services provide users with control over registration, what is connected to an iD, and who can access user information. 

Third-Party Processor Agreements. ORCID enters into agreements with its processors that incorporate data privacy and security provisions. Prior to entering into agreements with processors, ORCID conducts due diligence that addresses privacy and security components. To conduct this due diligence, ORCID first determines whether or not the third-party provider will have access to and/or receive copies of any Personal Data. If the answer is yes, then ORCID moves forward with negotiating a data processing agreement that aligns with the requirements of the GDPR and any other applicable data protection requirements. 

Data Encryption. ORCID implements reasonable encryption measures for all data at rest and in transit. Further, all back-ups are encrypted.¬¨‚

Technical and Organizational Measures. ORCID implements a variety of security controls to support the secure management of its databases and infrastructure. These security controls include security patch management; system access monitoring; audit logging; access control; and change control mechanisms. Additionally, ORCID maintains an incident response plan as well as a disaster and data recovery process.

Yes, ORCID maintains a number of documents on its website related to its privacy and security practices. Those documents include:

• Privacy Policy – ORCID
• ORCID Trust – ORCID
• ORCID, GDPR, and your rights as a user ‚√¨ ORCID

TRUSTe Letter of Attestation (Microsoft Word – Certification Letter of Attestation_ORCID20191220.docx)

ORCID is happy to enter into the Standard Contractual Clauses with any member located in the EU, EEA or UK that is transferring personal data to ORCID using the member API. Please reach out to your ORCID engagement team contact to discuss the addition of the Standard Contractual Clauses to your membership agreement.

It is not likely that ORCID would be subject to US surveillance law requests highlighted in the Schrems II decision. Since ORCID is not an “electronic communication service provider” as defined under Section 50 USC § 1881(b)(4), it is not subject to the Foreign Intelligence Services Act (“FISA”). ORCID provides an online registry that is used to identify researchers from member organizations; as such, Section 702 under FISA would not apply to ORCID and its data.

Yes, ORCID makes clear to users that in the event it receives any government data request, it will provide “only such data as we deem necessary in the situation.” See Privacy Policy, Sec. 6.4.  Further ORCID makes clear that if allowed, it will “promptly provide information about any government data requests received and accounts affected to the relevant Record Holders.” Id. 

Yes, ORCID does not distinguish between users located in the EU or outside of the EU.¬¨‚ While certain regions may maintain different privacy laws, ORCID strives to provide privacy protections to all users in accordance with its Privacy Policy, located at https://info.orcid.org/privacy-policy/.

Yes. Anyone who participates in research, scholarship, or innovation can register an ORCID iD for themselves free of charge, and you can use the same iD throughout your whole career‚ even if your name changes or you move to a different organization, discipline, or country.

Go to our Forgot password page, select the Password option, enter your registered email address in the email field, and select the Recover Account Details button. We will send you an email with steps to reset your password.*

*If there is no ORCID iD associated with the email address you entered, the email you receive from us will let you know. At that point, you can try resetting your password using another one of email addresses (try both personal and professional). Please see our article on forgotten passwords for more information.

ORCID identifiers that end in X are valid and correct. 

ORCID identifiers are all randomly assigned and cannot be changed. The last character in an ORCID identifier is a checksum. It ranges in values from “0” – “10,” with X representing the value “10.” The checksum ensures the other 15 digits of your identifier form a coherent iD.

You can learn more by reading about the structure of an ORCID identifier.

Go to our Forgot password page, select the ORCID iD option, enter your registered email address in the email field, and select the Recover Account Details button.

We will send you an email from reset@notify.orcid.org, letting you know your 16-digit ORCID identifier. Please see I forgot my ORCID iD, how do I recover it? for more information.

If you remember your password, try logging in at https://orcid.org/signin using your 16-digit ORCID iD or your previous email address as your username. 

If you’ve forgotten your password AND have lost access to previously registered email, please contact us and include: 

• Your name
• ORCID iD(s) you think may belong to you
• Any former email addresses you may have registered with
• A current institutional or work email address (if possible)

This information will make it easier for us to identify potential ORCID records that may belong to you and provide you with a quicker turnaround.

Please see How can I access my ORCID record if I no longer have the email associated with it for more information. Note: To prevent this from happening in the future, we recommend adding multiple email addresses to your ORCID account.

If you do not receive any email within 10 minutes, it can mean one of three things:

1. Our email was directed into your spam or junk folder. Please check your spam or junk folder for messages from ORCID. 
2. The email address entered contains a typo. Please try again.
3. Your mail administrator may have our messages blocked. Please contact us if you believe this to be the case.

The most common issue we hear from users is the loss of access to their former email addresses registered to their accounts.

We strongly recommend adding at least one backup email address, so you can recover access to your ORCID record in case you lose access to another email.

If you have forgotten which email address you registered your ORCID account with, please go to our Forgot password page. Select the ORCID iD option, and then enter in any email addresses you may have registered with.

We will send you an email letting you know your 16-digit ORCID identifier.

If the email says we could not find an ORCID iD associated with the email address, then retry the process above with your other current email addresses (both personal and professional) to recover the ORCID iD.

When you have exhausted all other options, please contact us with your full name, your 16-digit ORCID identifier, and any email addresses you may have registered for an account with. Note: To prevent this from happening in the future, we recommend adding multiple email addresses to your ORCID account.

You can quickly and easily remove your duplicate record by going to your Account Settings and selecting Remove duplicate record. You will then be prompted to enter in the email address or ORCID iD of the duplicate record, as well as the password.

When the duplicate record is removed, the email address attached to it will be added to your primary ORCID record, and all other information on the record will be deleted.

For more information, please see removing your additional or duplicate ORCID iD.

If you no longer have access to that email account and do not recall the password, please contact us with your full name, your 16-digit ORCID identifier, and any email addresses you may have registered for an account with.

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. 

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.

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.

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 support@orcid.org

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.

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

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")

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.

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.

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

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.

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

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

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.

**Ringgold is no longer supported although Ringgold identifiers still exist within the ORCID registry

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

• 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

**Ringgold is no longer supported although Ringgold identifiers still exist within the ORCID registry

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

****Ringgold is no longer supported although Ringgold identifiers still exist within the ORCID registry

• 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

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.

**Ringgold is no longer supported although Ringgold identifiers still exist within the ORCID registry

• 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: 
• 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

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.

**Ringgold is no longer supported although Ringgold identifiers still exist within the ORCID registry

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.

****Ringgold is no longer supported although Ringgold identifiers still exist within 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 0. The display index also determines the work order when reading the ORCID record.

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

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

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+
encyclopaedia-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-pla	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.
inventio	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.

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

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.

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

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.

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/

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.

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.

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

Total unique iDs: The number of researchers that have granted permission to an integration belonging to your organization.  This includes read-only and update permissions.  Each researcher is only counted once, no matter how many integrations they have connected with.

Your integrations: A list of integrations for your organization using the member API with accompanying counts of Connected iDs and records updated. Also included the name of the third party system being used ti integrate with ORCID where applicable.

New users per year: A chart showing users connecting to each of your integrations over time.

The older reports that we supported before 2022 are no longer available for you to view. If you have any questions about the previous reports then please contact membership@orcid.org

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.

Records updated with affiliations: A metric counting how many iDs have been updated by your integrations with a particular item type, e.g. works, affiliations

Types of affiliations added: A percentage of how many of each affiliation type has been added, e.g. Employment, Education

Total affiliations added: A metric counting how many of a particular item have been added

Org identifiers added: A table listing the affiliation types and the organization IDs used by your integration when adding affiliations to records, along with a count of records updated with that organization ID.

Total records updated: The number of researchers that have benefitted from automatic updates to their records made by your integrations

Unique iDs connected per year: A graph showing Connected iDs broken down by year.

Records updated per year by integration: The number of researchers that have benefitted from automatic updates to their records made by your integrations

Total items added per year by integration: A graph showing the number of items added by your integrations every year

Records updated with works: The number of records that have had at least one work added by an integration

Total works added: The total number of works added by your integrations

Types of works added: A percentage of how many of each work type has been added, e.g. Journal Article, Preprint

Records updated with peer review: The number of records that have had at least one peer review added by an integration

Total peer review added: The total number of peer reviews added by your integrations

Records updated with websites & social links: The number of records that have at least one website & social link added by an integration

Records updated with personal identifiers: The number of records that have at least one personal identifier added by an integration

Records updated with funding: The number of records that have at least one funding added by an integration

Total funding added: The total number of funding added by your integrations

Records updated with research resources: The number of records that have at least one research resource added by an integration

Affiliation countries: A chart showing the country codes within the affiliation metadata of Connected IDs. 

Current affiliations: A table listing affiliations found on all iDs with country code, broken down by organization ID and type.  Only includes current affiliations, i.e. those without an end date.

Country code: A chart showing the country codes constrained within the biographical metadata of Connected IDs.

User location over the last year: A chart showing where your user was based when granting permission to your organisation via OAuth

Total records with domains: A metric counting the total number of iDs that have an email address ending in one of the registered domains. If the record has an email address with more than one of the registered domains they will be included in the count more than once. If you would like additional domains added then please let us know.

Records with registered domains: A list of your registered email domains along with the number of records using that domain.

Records by subdomain: A list of your registered email sub domains along with the number of records using that sub domain

Records adding email domains per year: A graph showing the use of registered domains over time.¬¨‚ Researchers may have registered more than one email address, and this graph counts all of the researcher‚s addresses.

This section shows the number of records your integrations have updated

Records updated with affiliations: A metric counting how many iDs have been updated by your integrations with affiliations.

Total affiliations added: A metric counting how many affiliations have been added

Types of affiliation added: A percentage of how many of each affiliation type has been added, e.g. Employment, Education

Org identifiers added: A table listing the affiliation types and the organization IDs used by your integration when adding affiliations to records, along with a count of records updated with that organization ID.

Records updated with works: A metric counting how many iDs have been updated by your integrations with works

Total works added: A metric counting how many works have been added

Types of work added: A percentage of how many of each work type has been added, e.g. Journal Article, Preprint

Records updated with peer reviews: A metric counting how many records have been updated by your integrations with a peer review

Total peer reviews added: A metric counting how many peer reviews have been added

Records updated with funding: A metric counting how many records have been updated by your integrations with a funding

Total funding added: A metric counting how many funding have been added

Records updated with a personal identifier: A metric counting how many records have been updated by your integrations with a personal identifier

Records updated with research resources: A metric counting how many records have been updated by your integrations with a research resources

Records updated with websites & social links: A metric counting how many records have been updated by your integrations with a website or social link

This section shows the number of researchers interacting with your integrations. 

Connected iDs: The number of researchers that have granted permission to an integration belonging to your organization. This includes read-only and update permissions. Each researcher is only counted once, no matter how many integrations they have connected with.

Records Updated with this integration: The number of researchers that have benefitted from automatic updates to their records made by your integrations

Records updated with this integration: The number of researchers that have benefitted from automatic updates to their records made by your integrations

iDs first connected: A graph showing Connected iDs over time.

Records first updated: A graph showing Records Updated over time. Each iD is counted once, according to the year they were first updated

Unique iDs connected per year: A graph showing Connected iDs broken down by year.¬¨‚¬¨‚

Unique iDs updated per year: A graph showing Records Updated broken down by year.¬¨‚

This section shows how many researchers are connected to the consortia country.  This will be most relevant to national consortia.  Note that information shown may or may not have been added by consortia members.

Consortia Country: Country code of your consortium

Total iDs affiliated with country: A metric showing the total number of iDs in the registry that have the consortia country code within the affiliation section of their record. Includes all affiliations, past and present

iDs with country code: A metric showing the total number of iDs in the registry that have the consortia country code within the biography section of their record.

Total iDs affiliated with country (current): A metric showing the total number of iDs in the registry that have the consortia country code within the affiliation section of their record.  Only includes current affiliations, i.e. those without an end date.

Current affiliations (for all iDs with country):A table listing affiliations found on all iDs with country code, broken down by organization ID and type.  Only includes current affiliations, i.e. those without an end date.

Active iDs with country code: Number of active records (signed in or record updated within the last 365 days) with consortia country code

This section shows the number of researcher records consortia member integrations have updated.  It can be used to understand how well consortia members are helping their researchers keep their records up to date.

Unique records updated per year: A graph showing Records Updated broken down by year. Researchers are counted for all years in which they were updated by a consortia member.

Unique iDs connected per year: A graph showing Connected iDs broken down by year.  Researchers are counted for all years in which they granted permission.

Records updated per year by integration: A graph showing records updated broken down by year and integration within your consortia

This section shows the number of researchers interacting with consortia member integrations.

Total consortia members: The total number of members in your consortium

Total Integrations: The total of integrations in your consortium

Active integrations: The number of integrations in your consortia which have updated at least one record

Total connected iDs: The number of researchers that have granted permission to a member integration belonging to the consortia.  This includes read-only and update permissions.  Each researcher is only counted once, no matter how many integrations they have connected with

Records Updated
The number of researchers that have benefitted from automatic updates to their records made by members of consortia.

Consortia member integrations:
A list of integrations registered by members of the consortia, with accompanying counts of Connected iDs, records updated, what service provider system is used if applicable and if the integration is for the member portal (Affiliation Manager)

New users per year by integration: A chart showing users connecting to each of your integrations over time.

This section shows where the connected iD‚s originate

Current affiliation countries: A chart showing the country codes within the affiliation metadata of Connected IDs.

Current affiliations: A table listing affiliations found on all iDs with country code, broken down by organization ID and type. Only includes current affiliations, i.e. those without an end date.

User location: A chart showing where your user was based when granting permission to your organisation via OAuth

Country code: A chart showing the country codes constrained within the biographical metadata of Connected IDs.

Records updated with affiliations: A metric counting how many iDs have been updated by consortia member integrations with an affiliation

Types of affiliation added: A percentage of how many of each affiliation type has been added.

Total affiliations added: A metric counting how many affiliations have been added by consortia member integrations

Consortia members adding affiliations: A list of how many affiliations have been added by consortia member integrations

Org identifiers added:A list of how many organisation identifiers have been added by consortia member integrations.

This section shows how many researchers have registered using email domain(s) the consortia has registered with ORCID.  A maximum of five email addresses may be registered.

National Email Domain: What ORCID has for your countries national email domain

Records with national domain: A count of records that have an email address with your national email domain

Email domains registered by members: A list of email domains that are registered by your consortium members

Records by member subdomain: A list of subdomains that are connected to your consortia and how many ORCID records are associated with them. Please note that this number of records may not match the total number of records with your email domain. This could be due to not all email domains registered against your consortia members will end in your national domain

Active records with national domain: Number of active records (signed in or record updated within the last 365 days) with national email domain

Records adding email domain per year: A graph showing the number of records added by per per email domain.

Items added per year by integration:A chart showing how many items have been added broken down by year and member in your consortia.

Records updated with works: The number of records that have had at least one work added by an integration

Total works added: The total number of works added by your integrations

Types of work added: A percentage of how many of each work type has been added, e.g. Journal Article, Preprint

Records updated with peer reviews: The number of records that have had at least one peer review added by an integration

Total peer reviews added: The total number of peer reviews added by your integrations

Records updated with funding: The number of records that have at least one funding added by an integration

Total funding added: The total number of funding added by your integrations

Records updated with research resources: The number of records that have at least one research resource added by an integration

Records updated with websites & social links:The number of records that have at least one website & social link added by an integration

Records updated with personal identifiers: The number of records that have at least one personal identifier added by an integration

You can request sandbox Member API credentials to build and test your application. These credentials allow you to make calls to the sandbox 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 a third-party system that already supports ORCID, you may not need to register for sandbox API credentials. 

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 sends notification emails only 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 update. Store it together with the researcher’s information. 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. Persistent tokens are valid for approximately 20 years or until the user revokes them. Refresh tokens can be used to create new access tokens with the same or limited scopes. Store the tokens together with the researcher’s information. We also recommend you store the token scope, and the‚token expiry.
• Accept and store put codes (if updating ORCID records): Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API. Save this put code along with the item in your system‚ it’s how you‚ll identify which item needs to be read or updated.
• Log interactions: Your system should record both calls made to the ORCID API and responses received. This is necessary so ORCID can help if a problem develops later.
• Provide error messages and a support contact when an interaction does not go as expected.

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

Notes for ORCID staff: Use this field to let ORCID know if you’re using a vendor system, integrations been reviewed etc.

Contact email address: We will send the credentials to this address. This should be the contact that we have been working with on the integration or the technical contact that we hold for your organisation.

Contact for receiving PIN to access credentials: We send the full credentials to you in a secure way. We will send a passcode to access your API credentials to this contact. This needs to be a different contact to the previous contact listed.

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

URL of the home page 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.

OAuth2 redirect URIs or callback URLs for the client: Permitted URL(s) in your web application where users will be returned to after they authorize access to their ORCID record data. All redirect URIs must be HTTPS for production (live) server clients. 

Once you have made your request, a manual process happens to issue you credentials and you will get an email with your client iD and client secret. Typically these requests are process in less than 48 hours.

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.)
• Include an ORCID branded button or link on your site to initiate authentication of the iD.
• Present the OAuth authorization screen according to our guidelines
• 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.

Best practices

Make sure your integration follows best practices

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

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

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. This also gives us an opportunity to learn more about how your system works, and how you‚re explaining the benefits of your ORCID integration, so we can provide better support for you and your users.
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 (recommended for ORCID-enabled systems which require a demonstration): 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.¬¨‚

If you are using one of the ORCID-enabled systems that does not require a demonstration, you can directly request production Member API credentials. Be sure to specify which system (and, if applicable, version) you’re using in the notes.

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.

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.

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

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. 

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 and 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 or search for ORCID records. 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 not a premium member, but wish to test this function in the Developer’s Sandbox, please contact ORCID Community.

• In the past ORCID supported other scopes, that have now been phased out.
• You can find out which scopes are required to add or update a particular sections here.

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.

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

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.

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.

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

Any or all of the parameters can be used:

Parameter	Field	Notes
given_names	First 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	Last 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

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.

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.

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.

To ensure that you build the best possible integration for your institution, your researchers, and the wider community, we recommend that you consider the following best practices:

• Customize the user experience: Use data your system has stored to pre-fill the OAuth sign in/registration screen. You can also include state parameters to identify the user in your system or change the display language on ORCID.
• Provide a workflow for users if they deny your system permission: Provide a message to users which clearly explains what ORCID is, why your system is requesting permission to their ORCID record, and what you will do with that permission, and offer the option to again grant permission.
• Provide an option for users to remove their ORCID iD and data from your system: In rare cases, a user may wish to remove their iD from your system, or they may have connected the wrong ORCID iD Ensure that any active access tokens are also revoked by your system at the same time.
• Update added items when corrections are needed using the item‚s unique put code.
• Provide descriptive error messages and a support contact to your users when an interaction does not go as expected.
• Display the ORCID member logo (contact us to receive it)
• Create a consistent user experience by associating the iD icon with a trusted assertion process. Our ORCID Brand Guidelines for Members and Partners will take you through the process for setting up the display of the iD icon in your system, as well as outline do‚s and don’ts of displaying the ORCID brand.
• Use the access token to check for existing permissions: Once you have received permissions from the user once, you should not need to request them again.

Registered Organization IDs – This section shows the organization IDs that have been used for generating the data on the report. These are the IDs that we have registered against your ORCID membership.

Number of Affiliated Records – The total number of ORCID records that have an affiliation (employment, education, qualifications, membership, services, invited positions and distinctions) within the registry for your organization. Please note, there may be more that are within the registry that do not have an organization ID attached

Number of records with a current affiliation – The total number of ORCID records that have a current affiliation within the registry for your organization. A current affiliation is an affiliation that does not have an end date populated. Please note, there may be more that are within the registry that do not have an organization ID attached

Total Affiliations – The total number of affiliations within the registry for your organization. This includes current and past affiliations. Please note, there may be more that are within the registry that do not have an organization ID attached

Affiliations Created Over Time – A graph that shows the number of affiliations that have been added to the registry over time. The graph is split by affiliations that your organization has added and the affiliations that have been added by your researchers  manually

Affiliations Created Over Time by Type – A graph that shows the types of affiliations that have been added over time.

Affiliations created Over Time by ORG ID – A graph that shows the number of affiliations added by ORG ID over time.

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.

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.

Publicly affiliated ORCID Records – A list of ORCID records that have a public affiliation to your organization. Public affiliations are those which visibility is set to “everyone” in the registry. The list contains the ORCID iD, given name, family name and credit name

Publicly currently employed ORCID Records – A list of ORCID records that have a public employment affiliation to your organization. Public affiliations are those which visibility is set to “everyone” in the registry. The list contains the ORCID iD, given name, family name and affiliation start date

Public Affiliations with affiliation data– A list of the public affiliations to your organization. The list includes ORCID iD, given name, family name, type, title, department, start and end dates, date added to ORCID, last modified date for the affiliation, source. org ID type and org ID value.

• 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