Presentation at ORCID Vancouver Workshop (7 October 2016)

1. orcid.org
The ORCID API
AlainnaTherese
ORCID Community Engagement & Support
support@orcid.org | orcid.org/0000-0002-6036-0903
a: 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA
Sharing information between systems

2. Connecting info by names is complicated
orcid.org
Of the more than 6 million authors in a major journal citations and
abstracts database,+2/3 share last name and single initial with
another author.An ambiguous name in the same database refers on
average to 8 people.
http://ands.org.au/newsletters/share_issue18.pdf
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

3. ORCID provides
orcid.orgPHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu
Persistent digital identifiers to distinguish researchers from
each other
Member-built integrations that connect researchers and their
activities/affiliations
A hub for synchronizing machine-readable connections
between identifiers for people, organizations, and research
activities
✔ Plumbing for research information
✔ Tools to build trust in digital information

4. Registration is simple
orcid.org
Register
Directly via the ORCID website
https://orcid.org/register
Or referred by an integration
from another site
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

5. Registration is simple
orcid.org
Welcome to the ORCID Registry!
• Unique and persistent
identifier
• 16-digit number
• Expressed as HTTP URI
• Compatible with ISO standard
• Verify your email address
• Here’s your ORCID iD:
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

6. The ORCID record
orcid.org
Biographical
data è
ç Education data
ç Employment data
ç Works data
ç Funding data
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

7. The ORCID record
orcid.org
Education & employment data
Organization
list from è
Ringgold
(an ISNI Registrar)
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

8. The ORCID record
orcid.org
Funding data
Funding agency
ç list consistent
with FundRef
Search & link
wizard ê
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

9. The ORCID record
orcid.org
Works data
Structured citations
in BibTeX
Classifications & metadata
fields consistent w/
CASRAI
Translated titles &
language support
Search & Link Wizards:
• Crossref Metadata Search
• Scopus
• Europe PubMed Central
• ResearcherID
• Modern Language
Association
• DataCite Metadata Store
• Redalyc
• Ariti
• ANDS Registry
BibTeX importPHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

10. The ORCID record
Works data
When the same work is added by
multiple sources, the different
versions are grouped together
based on work identifier
Source information is captured
for all items added to the record
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

11. The ORCID record
Peer review data
Only posted via API by clients
approved for peer review
Live: F1000, AGU/eJournalpress, Publons
In progress: Aries Systems, eLIFE, Hindawi,
Politics & Religion Journal, Peerage of Science
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

12. Information in an ORCID Record has a privacy setting,
which only the account owner can set – API cannot override.
Account information (settings, permissions) is accessible by
the account owner.
User privacy
Public view Account ownerAccount owner, Trusted
orgs & individuals
Accessible by :
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

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

14. 7 October 2016 orcid.org 14
API Features
Member API
ORCID member organizations
(Sandbox test environment freely
available to anyone)
• Authenticate: Get a user’s authenticated ORCID iD
• Read: Search/retrieve public and limited access data
• Add/Update: Post new items to a record or edit/delete items you
previously added
• Create: Facilitate creation of new ORCID records (via on-demand
process)
Premium Member API
Premium ORCID member
organizations
• Webhooks: Receive notifications of updates
• Customised monthly reports
• Access to monthly public data file
ORCID API

15. Connecting to the ORCID registry
orcid.org
Two models:
1. Connect via a vendor system
• Manuscript submission/publication
• Document/data repositories
• Profile systems
• CRIS systems
2. Develop a custom connection
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

16. Custom integrations
orcid.org
Via the ORCID API
• Fine-tuned control and permissions
• Customized buttons, user flows, & user feedback
Current integration list:
http://members.orcid.org/current-integrations
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

17. Selected vendor system connections
orcid.org
Publishing
• eJournal Press
• Editorial Manager
• ScholarOne
Document / data repositories
• DSpace
• ePrints
• Hydra/Fedora
CRIS Systems
• Converis
• Elements
• IRMA
• Pivot
• PlumX
• Pure
• Vivo
http://members.orcid.org/orcid-enabled-systems
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu

18. 7 October 2016 orcid.org 18
DISPLAY
• In metadata
• On sites
• In publications
CONNECT
• Affiliations (employers)
• Works (publishers)
• Awards (funders)

19. Collect
COLLECT validated ORCID iDs for
individuals
• Explain what ORCID is
• Explain why you’re collecting iDs
• Consistent user experience
• Authenticated connections
orcid.org
Ensure individuals are correctly connected with your institution
Many vendor systems use the OAuth process

20. orcid.org
Get permission, use permission
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

21. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Get permission
orcid.org
ORCID registry depends on user-based permissions:
Can I...
• have your iD (/authenticate)
• read limited-access data on your record
(/read-limited)
• interact with the activities on your record
(/activities/update)
• interact with your biographical information
(/orcid-bio/update)

22. PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
Involving the user
orcid.org
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 “fancy” URL
• Prior iD not needed
• Hard things: promotion, finding touch points

23. PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
Get permission: touch points
orcid.org
Look for natural fits:
• Your sign in – why not link your iD?
• Your account settings/user profile
• Submission (of any type)
• Form fills: pre-fill from your Record!
• Registration: for conference or meeting
• Reporting: Link your iD to get started

24. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Step 1: fancy URL
orcid.org
https://sandbox.orcid.org/oauth/authorize?
client_id=APP-XT8FBKJRO3MR8WDR&
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
&orcid=0000-0001-6356-0580
The base URL, displays ORCID sign in
who’s
asking?
what
permissions?
where the user goes next
Personalise the
experience
The OAuth call: part I

25. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
What the user sees
orcid.org
already signed in sign in form
(already registered)
registration form
knownemail@here.edu

26. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Step 2:Auth code & user feedback
orcid.org
ORCID sends the user to your redirect, with a code
https://my.URL.org?htA3yE
• Save the code – you need it for the next step
• Display something useful to the user
• Authorize: thanks for your permission!
• Deny: are you sure you don’t want to give
permission?
The auth code

27. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Step 3a:Transform the code into a token
orcid.org
Use the code to gain access using the ORCID API
https://sandbox.api.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
looks like URLs
(RESTful)what format?
The auth code
confirming that you are
the right one to get this
information

28. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Step 3b: Store the result
orcid.org
the result of the call
"access_token” :"6710dfee-6aab-445b-a266-205dd9085273",
"token_type" : "bearer",
"expires_in" : 631138518,
"scope" : "/read-limited /activities/update",
"orcid" : "0000-0001-6356-0580",
"name" : "Bob Researcher"
store the access token and iD
when permission expires (in
seconds)
your permission – executed contract
iD & name for the person
who gave permission
What you can do
✔ iD Collected!

29. Display
orcid.org
DISPLAY iDs on your website, platform, systems
• iDs shown as a link
• iDs in metadata
• Use the ORCID Member logo
• Explain why iDs are collected
Signal to your researchers and the wider community that your
systems are plumbed to support ORCID iDs
http://orcid.org/trademark-and-id-display-guidelines

30. You have the iD, now display it!
iDs in print
Royal Society, Biology Letters
iDs electronically
Nature, Genetics
orcid.orgPHOTO: Job Meeting

31. Display: iDs in profiles
orcid.org

32. You have the iD, now display it!
ORCID iD in DOI metadata:
<person_name>
<given_name>Karl</given_name>
<surname>Ward</surname>
<ORCID authenticated=“true”>
http://orcid.org/0000-0002-4121-9960
</ORCID>
</person_name>
• iD available in search
orcid.orgPHOTO: Job Meeting

33. Connect
orcid.org
CONNECT your data to ORCID records
• Request permission to write to records
• Store long-lived tokens
• Add data that you uniquely can (authoritative)
• Explain the connection
Enable researchers to provide validated data to other systems they use
https://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

34. Verb: POST
BASE URL: https://sandbox.api.orcid.org/v1.2/0000-0001-6356-0580/affiliations
HEADERS: Content-type:application/json
Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273
DATA (if adding or updating):
the file location=@employment.xml
Relevant
area:
/orcid-bio
/funding
/orcid-works
/peer-review
data format
Access token from
before
Type of action, also: READ; PUT
1.Your client sends data 2. Researcher’s record updated
Connect via API to send data

35. Read & update through a “message”
orcid.org

36. Synchronize
orcid.org
SYNCHRONIZE with your systems
• Update information when it changes
• Auto-add new information
• Search & link wizards
• Sync data from others
Saved time, better reporting, improved information flow
https://members.orcid.org/api/tutorial-webhooks
https://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

37. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Enabling synchronization
orcid.org
ORCID API features & tips:
• Update notifications (webhooks)
• Your system registers iDs you’re watching
• ORCID notifies when changes happen
• Internal triggers
• Employment status change
• Publication acceptance
• Publication correction
• Funding award

38. API in action: Create on demand
http://orcid-create-on-demand.herokuapp.com

39. Resources
PHOTO: Stairway to somewhere
© Jonathan Fenton https://flic.kr/p/7Guxgu
Bootcamp: ORCID API (Searches, OAuth, Create on Demand)
http://is.gd/VALA2016ORCID
ORCID Create on Demand Demo
http://orcid-createondemand.herokuapp.com
Collect & Connect @ Member Support Centre
https://members.orcid.org
API documentation
https://members.orcid.org/api
ORCID API User Listserv
http://groups.google.com/group/orcid-api-users
ORCID API Source (Github)
https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/README.md
•
•
•
•
•
•