ORCID API presentation by Alainna Wrigley for Japanese society consortium discussion, April 18, 2017

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

2. ORCID ENABLES
Organizations use
the ORCID API to
authenticate, collect,
display, and connect
persistent identifiers
for people, places,
and things in
research workflows

3. THE ORCID API
API Features
Public API
Freely available to anyone with
ORCID iD
• 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)
• 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
• Webhooks: Receive notifications of updates
• Customised monthly reports (including email stats)
• Access to monthly public data file

4. ORCID REGISTRY CONNECTIONS
Two models:
1. Connect via a vendor system
• eJournal Press
• Editorial Manager
• Open Journal Systems
• ScholarOne
2. Develop a custom connection

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

6. COLLECT & CONNECT

7. C&C: PEER REVIEW
New feature – reviews only added by ORCID API
Standard citation elements:
• PERSON: person who performed review & being recognized for
review activity.
• REVIEW: review itself. Can be blank for blind or unshared reviews.
• SUBJECT: review subject - paper, grant, etc. Can be blank for blind or
unshared reviews.
• ORGANIZATION: organization recognizing the person for review
activity, such as a publisher, association or funder.

8. COLLECT
COLLECT and store users’ validated iDs
Look for natural fits
• Registration/sign in
• Account settings/user profile
• Submission
• Post-submission thank you
email
TO: reviewer@email.com
FROM: Grateful Journal
Thank you for reviewing this article. Would
you like to be recognized on your ORCID
record?
What is ORCID?
Clicking this button will open a permission screen.
Post-submission
email
ORCID as a
sign in option
Learn more:
• Peer review workflow: https://members.orcid.org/api/workflow/peer-review
• Publishing systems workflow: https://members.orcid.org/api/workflow/publishing-systems

9. INVOLVING THE USER
Key benefits:
• You know the user controls the iD
• User consent
• Privacy/ data control trends
• Positions your system as a service
How?
• Just a customized URL
• No need to know whether the user has
an iD – you’ll get it directly from the ORCID
API!

10. 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=Reviewer&given_names=Peer&email=peerrevi
ewer@institute.edu
the base URL, displays ORCID sign in screen
who’s asking?
what permissions?
where the user goes next
personalize the
experience
The OAuth call: part I

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

12. STEP 2: AUTH CODE & USER
FEEDBACK
ORCID sends the user to your redirect, with a code
appended to end
https://my.URL.org?htA3yE
• Save the code – you need it for the next step
• Display something useful to the user
• Authorize: thanks, here’s your iD!
• Deny: are you sure you don’t want to give
permission?
the auth code
deny message
authorize message

13. 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
so we know you are
the right system to get
this information

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

15. DISPLAY
Learn more:
• iD Display guidelines https://orcid.org/trademark-and-id-display-guidelines

16. CONNECT
CONNECT reviews to ORCID records
• Use existing permissions (token) or get
permission to update ORCID record
• Use as much or little detail as is relevant
• Each review has own unique reference ID
• Add new group if doesn’t exist

17. CONNECT VIA API TO SEND
DATA
Verb: POST
BASE URL: https://api.sandbox.orcid.org/v2.0/0000-0002-0491-7882/peer-review
HEADERS: Content-type:application/vnd.orcid+xml
Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273
DATA (if adding or updating):
the file location=@peer-review.xml
endpoint:
/employment
/education
/work
/funding
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
• orcid.org
unique ref id
group

18. SYNCHRONIZE your systems and ORCID
• Continuously update reviewers’ records for new
or corrected review activity
• Register webhooks to learn of new activities on
reviewers’ records
• Update other data: Affiliations, works
SYNCHRONIZE
Learn more:
• Webhooks: https://members.orcid.org/api/tutorial/webhooks

19. API DEMO: JOURNAL ID CONNECT
https://orcid-journalconnect.herokuapp.com

20. RESOURCES
ORCID and Publishers
https://members.orcid.org/publishers
Workflow: ORCID in publishing systems
https://members.orcid.org/api/workflow/publishing-systems
Workflow: ORCID in peer review
https://members.orcid.org/api/workflow/peer-review
ORCID peer review examples and case studies
https://vimeo.com/album/4159316
ORCID-enabled publishing tools
https://members.orcid.org/api/vendors/publisher-tools
ORCID API documentation
https://members.orcid.org/api
Questions?
support@orcid.org