Developer Guide: Implementing ORCID Trust Markers

⚠️ WARNING: This documentation has been summarized by Claude (an AI language model) and is pending human review. Some information may be incomplete or require verification against official ORCID documentation.

Table of Contents

• Introduction
• API Overview
• Authentication and Authorization
• Accessing Record Summaries
• Reading Trust Markers Data
• Adding Trust Markers to ORCID Records
• Integration Examples
• Best Practices
• Troubleshooting
• Resources

Introduction

This developer guide provides technical instructions for implementing ORCID Trust Markers and Record Summaries in your applications. Whether you're developing a journal submission system, institutional repository, funding management system, or any other scholarly application, this guide will help you leverage ORCID's infrastructure to enhance research integrity.

ORCID Trust Markers are validated pieces of information in ORCID records that have been added by trusted member organizations. Record Summaries provide an easy way to access and display this validated information in a user-friendly format.

API Overview

ORCID provides two API levels:

Feature
Public API
Member API
Read public data
✓
✓
Search registry
✓
✓
Collect authenticated iDs
✓
✓
Read limited-access data
✓
Add/update records
✓
Get record summaries
✓

Base URLs:

• Production: https://orcid.org (API: https://api.orcid.org and https://pub.orcid.org)
• Sandbox: https://sandbox.orcid.org (API: https://api.sandbox.orcid.org and https://pub.sandbox.orcid.org)

API Versions:

• Current version: 3.0
• Endpoint format: /v3.0/[ORCID-iD]/[endpoint]

Authentication and Authorization

Registering for API Credentials

1. Sign in to your ORCID account
2. Go to Developer Tools
3. Click "Register for Public API Credentials" (or request Member API credentials if you're an ORCID member)
4. Complete the application details:
   • Name: Your application name (displayed to users)
   • Website URL: Your application URL
   • Description: Brief description of your application
   • Redirect URIs: Where users will be sent after authorizing your application

OAuth 2.0 Flow

ORCID uses OAuth 2.0 for authentication and authorization:

1. Create an authorization URL

https://[environment]/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=[requested scopes]&redirect_uri=[Your registered redirect URI]

Available scopes:

• /authenticate: Basic access to get authenticated ORCID iDs
• /read-public: Read public data and summaries (Member API)
• /read-limited: Read trusted-parties-only data
• /activities/update: Update activities sections (works, funding, etc.)
• /person/update: Update person sections (other names, keywords, etc.)

2. Exchange authorization code for access token

POST https://[environment]/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=[Authorization code from step 1]
&client_id=[Your client ID]
&client_secret=[Your client secret]
&redirect_uri=[Your registered redirect URI]

3. Use access token for API requests

GET https://api.[environment]/v3.0/[ORCID iD]/[endpoint]
Accept: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization: Bearer [Access token]

Accessing Record Summaries

Record Summaries provide a concise view of an ORCID record's Trust Markers. There are two methods for accessing them:

Method 1: Record Endpoint (Public and Member API)

This returns the complete record with all public data:

GET https://api.[environment]/v3.0/[ORCID iD]/record
Accept: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization: Bearer [Access token]

Method 2: Summary Endpoint (Member API Only)

For Member API users, the /summary endpoint specifically returns record summary data:

GET https://api.[environment]/v3.0/[ORCID iD]/summary
Accept: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization: Bearer [Access token]

Reading Trust Markers Data

When reading record data through the API, you'll need to parse the response to identify Trust Markers. Trust Markers are identified by their source - if the source is an organization rather than the individual, it's a Trust Marker.

XML Example

<activities:activities>
  <activities:employment-summary put-code="1234" visibility="public" display-index="0" path="/0000-0001-2345-6789/employment/1234">
    <common:created-date>2020-01-01T00:00:00</common:created-date>
    <common:source>
      <common:source-client-id>
        <common:uri>https://orcid.org/client/APP-ABCDEFG</common:uri>
        <common:path>APP-ABCDEFG</common:path>
      </common:source-client-id>
      <common:source-name>University of Example</common:source-name>
    </common:source>
    <!-- Employment details -->
  </activities:employment-summary>
</activities:activities>

The presence of <common:source-client-id> in the source indicates this is a Trust Marker added by an organization.

JSON Example

{
  "employment-summary": [
    {
      "put-code": 1234,
      "visibility": "public",
      "source": {
        "source-client-id": {
          "uri": "https://orcid.org/client/APP-ABCDEFG",
          "path": "APP-ABCDEFG"
        },
        "source-name": "University of Example"
      },
      "organization": {
        "name": "University of Example",
        "address": {
          "city": "Exampleville",
          "country": "US"
        }
      }
    }
  ]
}

Look for the presence of source-client-id to identify organizational Trust Markers.

Adding Trust Markers to ORCID Records

ORCID member organizations can add Trust Markers to ORCID records. This requires:

1. Member API credentials
2. Obtaining permission from the record holder via OAuth with appropriate scopes
3. Formatting data according to the ORCID message schema
4. Sending a POST request to the appropriate endpoint

Example: Adding Employment (Affiliation)

POST https://api.[environment]/v3.0/[ORCID iD]/employment
Content-Type: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization: Bearer [Access token with /activities/update scope]

XML Payload:

<employment:employment>
  <organization>
    <name>University of Example</name>
    <address>
      <city>Exampleville</city>
      <country>US</country>
    </address>
  </organization>
  <department-name>Department of Example Studies</department-name>
  <role-title>Professor</role-title>
  <start-date>
    <year>2020</year>
    <month>01</month>
    <day>01</day>
  </start-date>
</employment:employment>

JSON Payload:

{
  "organization": {
    "name": "University of Example",
    "address": {
      "city": "Exampleville",
      "country": "US"
    }
  },
  "department-name": "Department of Example Studies",
  "role-title": "Professor",
  "start-date": {
    "year": {
      "value": "2020"
    },
    "month": {
      "value": "01"
    },
    "day": {
      "value": "01"
    }
  }
}

Upon successful addition, you'll receive a response with the new put-code for the item. Store this code to allow for updates later.

Integration Examples

Journal Submission System Integration

Here's an example workflow for integrating ORCID Trust Markers in a manuscript submission system:

1. Collect ORCID iDs during submission
   javascript

   // Create authorization URL
   const authUrl = 'https://orcid.org/oauth/authorize' +
     '?client_id=YOUR_CLIENT_ID' +
     '&response_type=code' +
     '&scope=/authenticate' +
     '&redirect_uri=https://your-journal.com/orcid-callback';
   
   // Redirect user to ORCID for authentication
   window.location.href = authUrl;

2. Process the callback
   javascript

   // Exchange authorization code for access token
   async function getToken(authCode) {
     const response = await fetch('https://orcid.org/oauth/token', {
       method: 'POST',
       headers: {
         'Content-Type': 'application/x-www-form-urlencoded'
       },
       body: new URLSearchParams({
         'grant_type': 'authorization_code',
         'code': authCode,
         'client_id': 'YOUR_CLIENT_ID',
         'client_secret': 'YOUR_CLIENT_SECRET',
         'redirect_uri': 'https://your-journal.com/orcid-callback'
       })
     });
     
     return await response.json();
   }

3. Fetch the Record Summary
   javascript

   async function getRecordSummary(orcidId, accessToken) {
     const response = await fetch(`https://api.orcid.org/v3.0/${orcidId}/record`, {
       headers: {
         'Accept': 'application/vnd.orcid+json',
         'Authorization': `Bearer ${accessToken}`
       }
     });
     
     return await response.json();
   }

4. Display Record Summary to Editors
   javascript

   function displayTrustMarkers(recordData) {
     // Count validated vs. self-asserted works
     const works = recordData.activities['works'];
     const validatedWorks = works.filter(work => work.source['source-client-id']);
     const selfAssertedWorks = works.filter(work => !work.source['source-client-id']);
     
     // Display counts
     document.getElementById('validated-works').textContent = validatedWorks.length;
     document.getElementById('self-asserted-works').textContent = selfAssertedWorks.length;
     
     // Similar processing for other sections...
   }

5. Add Publication to ORCID Record (post-acceptance)
   javascript

   async function addPublication(orcidId, accessToken, metadata) {
     const response = await fetch(`https://api.orcid.org/v3.0/${orcidId}/work`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/vnd.orcid+json',
         'Authorization': `Bearer ${accessToken}`
       },
       body: JSON.stringify({
         // Format work metadata according to ORCID schema
       })
     });
     
     return await response.json();
   }

Institutional Repository Integration

For institutions wanting to assert affiliations to their researchers' ORCID records:

1. Create an ORCID connection portal
   • Display ORCID sign-in button
   • Request appropriate scopes (/activities/update for affiliations)
   • Store access tokens securely
2. Batch affiliate researchers
   • For larger institutions, consider using the Affiliation Manager tool
   • Otherwise, use the Member API to add affiliations in bulk
3. Display Trust Markers in institutional CRIS or repository
   • Fetch and display ORCID record data
   • Highlight Trust Markers for additional verification

Best Practices

Security

• Use HTTPS for all API calls
• Store access tokens securely
• Implement token refresh procedures
• Don't store unnecessary ORCID data

Performance

• Cache record data where appropriate
• Use batch processing for multiple records
• Implement rate limiting to avoid API throttling

User Experience

• Make ORCID authentication seamless
• Clearly explain permissions requested
• Provide feedback on successful connections
• Display Trust Markers in an understandable way

Data Quality

• Format data according to ORCID schemas
• Include as much metadata as possible
• Validate data before submission
• Implement regular updates for added items

Troubleshooting

Common Issues

1. Authentication Errors
   • Check client ID and secret
   • Verify redirect URI exactly matches registered URI
   • Ensure HTTPS is used in production
2. Missing Trust Markers
   • Verify item visibility settings (must be public)
   • Check if source is properly formatted
   • Ensure organization is an ORCID member
3. API Rate Limiting
   • Implement exponential backoff
   • Batch requests where possible
   • Cache results to reduce API calls
4. Data Not Showing in Record Summaries
   • Check data visibility settings
   • Verify data was successfully added
   • Allow time for updates to propagate

Resources

• ORCID API Documentation
• ORCID GitHub Repositories
• ORCID API Tutorial
• ORCID Message Schema
• ORCID API Users Group