The document discusses how to integrate with the ORCID API. It describes the features of the public, member, and premium member APIs. It provides examples of connecting systems like manuscript submission systems and CRIS systems to ORCID to collect and display researcher IDs. The document outlines the OAuth workflow to authenticate users and connect data to their ORCID records using the API, and resources for learning more about synchronization and custom integrations.

1. INTEGRATING WITH THE ORCID API
19 APRIL 2017
community@orcid.org | orcid.org/0000-0002-6036-0903
ALAINNA THERESE WRIGLEY
Senior ORCID Community Team Specialist (APAC)

2. THE ORCID API
API Features
Public API
Freely available to anyone with
ORCID iD
• One (1) set of public API credentials (integration)
• Authenticate: Get a user’s authenticated ORCID iD
• Read (Public): Search/retrieve public data
Member API
ORCID member organizations
(Sandbox test environment
freely available to anyone)
• One (1) set of API credentials (integration)
• Read (Limited): Search/retrieve limited-access data
• Add: Post new data to a record
• Update: Edit or delete data you previously added
Premium Member API
Premium ORCID member
organizations
• Five (5) sets of API credentials (integrations)
• Webhooks: Receive notifications of updates
• Customised monthly reports (including email stats)
• Access to monthly public data file

3. ORCID REGISTRY CONNECTIONS
Two models:
1. Connect via a vendor system
• Manuscript submission/publication
• Document/data repositories
• Profile systems
• CRIS systems
2. Develop a custom connection

4. VENDOR CONNECTIONS
Publishing
• eJournal Press
• Editorial Manager
• Open Journal Systems
• ScholarOne
Document / data
repositories
• ePrints
• Hydra/Fedora
CRIS Systems
• Converis
• DSpace-CRIS
• Elements
• IRMA
• Pivot
• PlumX
• Pure
• Vivo
Find more:
https://members.orcid.org/orcid-
enabled-systems

5. CUSTOM INTEGRATIONS
Via the ORCID API
• Fine-tuned control & permissions
• Customized buttons, user flows, feedback
• Test & troubleshoot with ORCID team
Case examples: https://members.orcid.org/resources
Code examples:
https://members.orcid.org/api/resources/code-examples

6. COLLECT & CONNECT

7. COLLECT
COLLECT researcher’s validated iDs using
OAuth &
ORCID API
Learn more:
• ORCID workflows: https://members.orcid.org/api/workflow
• ORCID integration points: https://members.orcid.org/api/integrate
Look for natural fits:
• Email to researcher
• Registration/sign in
• Account settings/profile
• Submission
Email invitation
ORCID as a
sign in option

8. INVOLVING THE USER
Key benefits:
• You know the user controls the iD
• User knows what’s going on/user choice
• Privacy/ data control trends
• Position/ strengthen your system as a
service
How?
• Just a customized URL
• Prior iD not needed

9. STEP 1: AUTHORIZATION URL
https://sandbox.orcid.org/oauth/authorize?
client_id=APP-E422WM33OPZWKKMQ&
response_type=code&
scope=/read-limited%20/activities/update&
redirect_uri=https://my.URL.org&
family_names=Researcher&given_names=Bob&
email=bobresearcher@mailinator.com&
state=UNI-ID
the base URL, displays ORCID sign in screen
who’s asking?
what permissions?
where the user goes next
personalize the
experience with data
from your system
The OAuth call: part I
extra info to identify
user to your system

10. WHAT THE USER SEES
already signed in
sign in form
(already registered)
registration form

11. STEP 2: AUTH CODE & USER
FEEDBACK
ORCID sends the user to your redirect, with an
auth code appended to the end
https://my.URL.org?htA3yE&state=UNI-ID
• Save the code – you need it for the next step
• Display useful messages to the user
deny message
authorize message

12. STEP 3A: TRANSFORM THE
CODE INTO A TOKEN
Use the code to gain access using the ORCID API
https://sandbox.orcid.org/oauth/token
HEADER: accept:application/json
DATA:
client_id=APP-XT8FBKJRO3MR8WDR
client_secret=e285575c-4794-464b-a807-6f1c06b63
grant_type=authorization_code
code=htA3yE
redirect_uri=https%3A%2F%2Fmy.URL.org
our API calls always look
like URLs (RESTful)
what format?
the auth code
confirms that you are
the right one to get this
information

13. STEP 3B: STORE THE RESULT
The result of the call
"access_token" :"6710dfee-6aab-445b-a266-205dd9085273",
"token_type" :"bearer",
“refresh_token“ :"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2",
"expires_in" :631138518,
"scope" :"/read-limited /activities/update",
"orcid" :"0000-0002-0491-7882",
"name" :"Bob Researcher"
store the access token,
refresh token and iD with
user’s info in your system
when permission expires (in seconds)
your permission – executed contract
iD & name for the person
who gave permission
what you can do
✔ iD Collected!

14. DISPLAY
DISPLAY iDs on your website & systems
Learn more:
• iD display guidelines: https://orcid.org/trademark-and-id-display-guidelines
iDs in profiles:
Tokyo Institute of Technology
iDs in journals: eLife

15. DISPLAY: IDS IN METADATA
<person_name>
<given_name>Tomoko</given_name>
<surname>Kato</surname>
<ORCID authenticated=“true”>
http://orcid.org/0000-0002-1469-0685
</ORCID>
</person_name>
DOI metadata
iDs in search

16. CONNECT
CONNECT your data to ORCID records
• Request permission to write to records
• Store long-lived tokens & put codes
• Add data that you uniquely can assert
• Explain the connection to your users
Enable researchers to provide validated data to other systems they use
Learn more:
• ORCID workflows: https://members.orcid.org/api/workflow
• Auto-update: https://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

17. CONNECT VIA API TO SEND
DATA
Verb: POST
BASE URL: https://api.sandbox.orcid.org/v2.0/0000-0002-0491-7882/employment
HEADERS: Content-type:application/vnd.orcid+xml
Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273
DATA (if adding or updating):
the file location=@employment.xml
endpoint:
/education
/work
/funding
/peer-review
etc.
data format
access token from before
type of action, also: GET; PUT; DELETE
1. Your client sends data 2. Researcher’s record updated
researcher’s iD
your client’s name

18. Saved time, better reporting, improved information flow
SYNCHRONIZE with your systems
• Continuously update researchers’ records with
new or corrected activity
• Know when record is updated – register
ORCID update notifications (webhooks)
• Search & Link wizard
SYNCHRONIZE
Learn more:
• Webhooks: https://members.orcid.org/api/tutorial/webhooks
• Auto-update: https://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

19. API DEMO: CREATE ON DEMAND
https://orcid-createondemand.herokuapp.com

20. RESOURCES
Membership / API comparison chart
https://orcid.org/about/membership/comparison
Member Support Centre
https://members.orcid.org
ORCID API documentation
https://members.orcid.org/api
ORCID API documentation
https://members.orcid.org/api/workflow
ORCID API users listserv
https://groups.google.com/group/orcid-api-users
ORCID message (XSD) (Github)
https://git.io/vXw5w
Questions?
support@orcid.org