The document provides an introduction to the ORCID API, including what an API is, how the ORCID API works, and how to access the ORCID API. It discusses the ORCID registry, the sandbox and production APIs, application credentials, search queries, OAuth authentication, and examples of searching through the public API using cURL commands.

1. ORCID API introduction
With a focus on search

2. What is an API?
Insert footer2
API (Application Programming Interface) – interface that lets
one software program “talk” with another, exchanging data
behind the scenes.
ORCID-specific calls
Providing
information to &
receiving
information from the
registry (data
exchange)
OAuth calls
The API is
permissions-based:
requires a
permission protocol
– how you “execute
the contract”

3. ORCID Registry
Insert footer3
ORCID ‘mints’ IDs for researchers
The registry is a ‘store’ for links between those IDs and other info
Other information can be
- bibliographic info e.g. employment
- works e.g. publications

4. ORCID registry API
Insert footer4
Provides a way for programs, and
humans, to interact with that store of
links
Examples
Get information linked to this ORCID
ID
Get ORCID IDs linked to this employer
ORCID provides the web interface for
humans
• Mediated by
underlying
program
• e.g. browser
Humans
• Custom built
• Ready made
• e.g. CRISPrograms

5. ORCID
Production
Registry
ORCID
Sandbox
Registry
Member API
Public API
Member API
Public API
Sandbox – for testing
Functions are similar (same requests can be sent)
Content is different
Sandbox – for testing
Content is different – dummy data or close copies
Open to anyone (both member and public)
Sandbox – for testing
Preserves integrity of the data in the production
registry
Production – the real thing
Access is very controlled
Member API only for members
Member API / Public API
Public API limited set of interactions e.g. search
Member API allows privileged actions e.g. updates
Credentials – Client ID and secret
Different for Sandbox and Production
Member-level credentials needed to access member

6. ORCID
Production
Registry
ORCID
Sandbox
Registry
Member API
Public API
Member API
Public API
ID +
Secret
ID +
Secret
ID +
Secret
ID +
Secret
The ‘secret’ is
like a password
– it needs to be
kept safe!

7. Controlling access: Application Credentials
Jisc - UK ORCID support workshop7
ORCID offers different levels of access based on the API
(member/public)
Access to any of the ORCID APIs requires a set of credentials consisting of a Client ID and a Client
Secret
Example:
Client ID APP-674MCQQR985VZZQ2
Client secret d08b711e-9411-488d-a474-46efd3958842
01/04/

8. ORCID Sandbox ORCID Production
Member and Public API Member and Public API
Everyone can access both Member-only access to the Member API
Client ID and Secret Client ID and secret
Credentials for Sandbox do not work on Production (and vice versa)
Content is for testing only
Only sends emails to @mailinator address
Service levels not guaranteed
Form to apply for credentials
https://orcid.org/content/register-client-application-
sandbox
https://orcid.org/content/register-client-application-
production-trusted-party
Web interface for browsing, registering
Sandbox.orcid.org Orcid.org

9. Recap
ORCID Registry Store of links between ORCID ID and other info
Registry API Defines interactions with the store of links
Sandbox API Allows testing while preserving integrity of content
Credentials Client ID and Secret – specific to Production or Sandbox
Public API Basic interactions with the store of ORCID ID and links
Member API Privileged interactions e.g. writing updates or adding information
Obtain credentials Different process for Production and Sandbox
Access the registry Hosted at different URLs (programmatic and web interface access)
Further details:
Production: https://ukorcidsupport.jisc.ac.uk/2017/02/members-setting-up-vendor-systems-with-the-orcid-api/
Sandbox: https://ukorcidsupport.jisc.ac.uk/2018/08/the-orcid-sandbox/

10. Controlling access: User privacy levels
Information in an ORCID Record has a privacy setting,
which only the account owner can set – API cannot
override.
Account information (settings, permissions) accessible by
the account owner.
Public view Account ownerAccount owner, Trusted orgs &
individuals
Accessible by :

11. orcid.org
PHOTO: Privacy
Source unknown
Can be viewed by anyone
Controlling access: User privacy levels
Can be seen by any trusted
parties that you have authorized
to connect
Can only be seen by you

12. Privacy levels and the Public and Member API
Jisc - UK ORCID support workshop12
User Privacy Level Public API Member API
Everyone (Public)
 
Trusted Party (Limited Access)
x 
Me Only (Private – default for email address)
x x
01/04/
Results returned depend on
• the user privacy level
• the API (public or member)
• the permissions granted to the application
making the request (for limited access)

13. Building search queries
Jisc - UK ORCID support workshop13
Basic keyword search
• ?q=Newman
• Free-form
• Unrestricted search
• Searches all indexed fields
• E.g. Newman in published name Newman, given name Newman, or associated with a work with
"newman" in the title
01/04/

14. Building search queries
Jisc - UK ORCID support workshop14
Boolean searching
• AND OR in upper case (lower case treated as part of search term)
• Brackets can also be used
• e.g. johnson+AND+(caltech+OR+"California+Institute+of+Technology")
• Query syntax as available in SOLR 3.6
01/04/

15. Building search queries
Jisc - UK ORCID support workshop15
Searching by field
• List of fields that can be searched
• https://members.orcid.org/api/tutorial/search-orcid-registry
• Basic syntax for fielded search is field:value
• query string family-name:james
• will find record with the family name “James”, such as “Roland James”, but not those with the
first name “James”, such as “James Johnson”.
01/04/

16. Building search queries
Jisc - UK ORCID support workshop16
searching by field
• Affiliations data
• affiliation-org-name The name of any organization in an education or employment item in the
user’s record.
• ringgold-org-id The Ringgold ID of any organization in the activities section of the user’s record.
Generally this will be associated with an education or employment item.
• Biographical data
• Email The email address of the user.
n.b. As of February 2017, fewer than 2% of the 3+
million email addresses on ORCID records are public.
01/04/

17. Result Pagination
Jisc - UK ORCID support workshop17
• 100 results returned by default
• Maximum returned in one go is 200
• Paginate by specifying starting point
• /v2.0/search/?q=Newman&start=201&rows=200
01/04/

18. Search result in XML
Jisc - UK ORCID support workshop18
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<search:search num-found="3884"
xmlns:search="http://www.orcid.org/ns/search"
xmlns:common="http://www.orcid.org/ns/common">
<search:result>
<common:orcid-identifier>
<common:uri>http://orcid.org/0000-0003-4701-7523</common:uri>
<common:path>0000-0003-4701-7523</common:path>
<common:host>orcid.org</common:host>
</common:orcid-identifier>
</search:result>
01/04/
Displays first 100 entries

19. OAuth
Jisc - UK ORCID support workshop19
3-legged oAuth: Involves the user
https://members.orcid.org/api/oauth/3legged-oauth
• When an organization wants to get a researcher's verified ORCID iD
• When an organization wants to read trusted (limited-access) data on a researcher's ORCID
record
• When an organization wants to update a researcher's ORCID record
01/04/

20. Results are affected by privacy level
Jisc - UK ORCID support workshop20
…..and other factors
Sample University: Ringgold ID 4464 (March 2017)
Public affiliations using Ringgold ID: 31
Public email: 3
All emails: 425
01/04/

21. Search through the user interface
Jisc - UK ORCID support workshop21
Advanced search option
• Allows affiliation search to the UI
• https://orcid.org/orcid-search/search.
• very basic and needs further work (under review with the development team).
• Find ORCID records with an affiliation to their organisation by using name or a Ringgold or GRID
identifier.
• Recommend that the list is copied and then review each iD
• once you click on a search result the search is lost and you need to complete the search again
(one of the things that is being reviewed)
01/04/

22. Searches using the public API with just a URL
Jisc - UK ORCID support workshop22
•Health Warnings
•Undetermined how long functionality will be available
•Not something ORCID document and recommend
•Search by email domain =
https://pub.orcid.org/v2.1/search/?q=email:*@xxxxx
Search by organisation name =
https://pub.orcid.org/v2.1/search/?q=affiliation-org-
name:"University+of+Johannesburg” ( replace example included )
Search by Organisation ID =
https://pub.orcid.org/v2.1/search/?q=ringgold-org-id:xxxx
https://pub.orcid.org/v2.1/search/?q=grid-org-id:xxxxx (replace id)
01/04/

23. SWAGGER Interface
Jisc - UK ORCID support workshop23
https://pub.orcid.org/v2.0/
•Swagger public api interface
•Member api: https://api.orcid.org/v2.1/
(requires credentials)
01/04/

24. OAuth
Jisc - UK ORCID support workshop24
Present the credentials to gain access
The API returns a token
“2-legged oAuth”
https://members.orcid.org/api/oauth/2legged-oauth
The token returned is
• long-lived (not expiring for approximately 20 years)
• can be used to perform multiple searches or read multiple ORCID records.
01/04/

25. OAuth
Jisc - UK ORCID support workshop25
01/04/
ORCID Record
Yes!
Do you have
permission to do what
you want to do?
Get the
permission; store
iD and “token”
Read the record
or update the
record
No
OAuth

26. Access to the public API for searching
Jisc - UK ORCID support workshop26
To gain access to the public API we will get credentials through developer tools (requires an
ORCID account).
http://support.orcid.org/knowledgebase/articles/343182
01/04/

27. Obtain a search token using your credentials
Jisc - UK ORCID support workshop27
https://orcid.org/oauth/token
HEADER: accept:application/json
DATA:
client_id=[Your client ID]
client_secret=[Your client secret] grant_type=client_credentials
scope=/read-public
01/04/
This address used for Oauth
call (token endpoint)

28. Search request using cURL
Jisc - UK ORCID support workshop28
:Usersmonica.dukeDocumentssoftwarecurl -i -L -H "Accept:
application/json" --data "client_id=YOURID&client_secret=YOUR
SECRET &grant_type=client_credentials&scope=/read-public"
"https://orcid.org/oauth/token"
01/04/

29. Access token for searching
Jisc - UK ORCID support workshop29
{"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}
01/04/

30. Building the search call
Jisc - UK ORCID support workshop30
https://pub.orcid.org
• Method: GET
• Content-type: application/vnd.orcid+xml
• Authorization type: Bearer
• Access token: [Your access token]
• API version
• Endpoint /search/?=[query]
01/04/
This address used for the search
call (and other API calls)

31. As a cURL command
Jisc - UK ORCID support workshop31
C:Usersmonica.duke>curl --insecure -H "Content-Type:
application/orcid+xml“ "Accept: application/orcid+json" -H
"Authorization: Bearer 4ee242fc-eac3-41e5854-ae3de2ded205"
"https://pub.orcid.org/v2.0/search/?q=email:*@leedsmet.ac.uk
01/04/

32. Building search queries: Ringgold example
Jisc - UK ORCID support workshop32
https://pub.orcid.org/v2.0/search/?q=ringgold-org-id:1438
• C:Usersmonica.duke>curl --insecure -H "Content-Type: application/orcid+xml"
"Accept: application/orcid+json" -H "Authorization: Bearer 4ee242fc-eac3-41e5
• 854-ae3de2ded205" "https://pub.orcid.org/v2.0/search/?q=email:*@leedsmet.ac.uk
01/04/

33. Installing cURL
Jisc - UK ORCID support workshop33
• Which Windows version? System -> control panel
• https://www.lifewire.com/how-to-open-control-panel-2625782
• cURL download wizard
• https://curl.haxx.se/download.html
• Extract and copy to ‘software’ folder
• Test using this path on the command line (&copy)
• Update the system path environment variable; re-test
01/04/

34. Different ways of installing cURL
Jisc - UK ORCID support workshop34
http://stackoverflow.com/questions/9507353/how-do-i-install-set-
up-and-use-curl-on-a-windows
01/04/

35. Jisc UK ORCID Consortium
Jisc - UK ORCID support workshop35
Questions?
UK helpdesk:
help@jisc.ac.uk
01/04/

36. help@jisc.ac.uk
Ukorcidsupport.jisc.ac.uk
Monica Duke
JISC UK ORCID technical and community
support co-ordinator
Skype: monicabonett
monica.duke@jisc.ac.uk