Content is user-generated and unverified.

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.

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

Sign in to your ORCID account
Go to Developer Tools
Click "Register for Public API Credentials" (or request Member API credentials if you're an ORCID member)
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:

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.)

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]

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

xml

<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

json

{
  "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:

Member API credentials
Obtaining permission from the record holder via OAuth with appropriate scopes
Formatting data according to the ORCID message schema
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:

xml

<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:

json

{
  "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:

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;

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();
   }

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();
   }

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...
   }

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:

Create an ORCID connection portal
- Display ORCID sign-in button
- Request appropriate scopes (/activities/update for affiliations)
- Store access tokens securely
Batch affiliate researchers
- For larger institutions, consider using the Affiliation Manager tool
- Otherwise, use the Member API to add affiliations in bulk
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

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

Resources

Content is user-generated and unverified.

Developer Guide: Implementing ORCID Trust Markers

Table of Contents

Introduction

API Overview

Authentication and Authorization

Registering for API Credentials

OAuth 2.0 Flow

Accessing Record Summaries

Method 1: Record Endpoint (Public and Member API)

Method 2: Summary Endpoint (Member API Only)

Reading Trust Markers Data

XML Example

JSON Example

Adding Trust Markers to ORCID Records

Example: Adding Employment (Affiliation)

Integration Examples

Journal Submission System Integration

Institutional Repository Integration

Best Practices

Security

Performance

User Experience

Data Quality

Troubleshooting

Common Issues

Resources