ORCID API Integration Guide

This guide explains how to integrate with the ORCID data API to retrieve researcher activities from the University of Waterloo's ORCID service.

Table of Contents

Available Endpoints

All endpoints require either a username or orcid query parameter to identify the researcher.

Endpoint Description
/api/works Research works (publications, datasets, etc.)
/api/educations Education history
/api/employments Employment history
/api/fundings Funding and grants
/api/peer-reviews Peer review activities
/api/bio Person profile data (name, bio, etc.) plus username and ORCID
/api/full Person data and all activity types in one response

Query Parameters

  • username - The researcher's username (e.g., ?username=jsmith)
  • orcid - The researcher's ORCID iD (e.g., ?orcid=0000-0002-1234-5678)
  • refresh=true - Force a cache refresh from ORCID (optional)

Quick Start

Fetching Works 

// Fetch a researcher's public works by username
const response = await fetch('/api/works?username=jsmith');
const works = await response.json();

console.log(works);
// Returns array of work objects with full details

Fetching Education History 

const response = await fetch('/api/educations?username=jsmith');
const educations = await response.json();

// Each education includes institution, degree, dates, etc.
for (const edu of educations) {
    console.log(edu.data);
}

Response Format

Activity endpoints (for example /api/works, /api/educations) return an array of activity objects with the following structure:

[
    {
        "put_code": 12345,
        "activity_type": "work",
        "data": {
            // Full ORCID activity data
            "title": { "title": { "value": "My Research Paper" } },
            "type": "journal-article",
            "publication-date": { "year": { "value": "2024" } },
            // ... additional fields
        },
        "last_modified_date": 1702742400000,
        "updated_at": "2024-12-16T12:00:00.000Z"
    }
]

Bio Endpoint Response

The /api/bio endpoint returns person profile data (visibility-filtered), plus identity fields for easier integration:

{
    "person": {
        "name": {
            "given-names": { "value": "Jane" },
            "family-name": { "value": "Smith" },
            "credit-name": { "value": "Jane Q. Smith" },
            "visibility": "public"
        },
        "biography": {
            "content": "Associate Professor of Biology.",
            "visibility": "public"
        },
        "keywords": {
            "keyword": [
                { "content": "genomics", "visibility": "public" }
            ]
        }
    },
    "watiamUsername": "jsmith",
    "orcid": "0000-0002-1234-5678",
    "lastUpdate": "2026-06-26T16:05:00.000Z",
    "dataSource": "cache",
    "cacheAgeMs": 45210,
    "trusted": false
}

If no public biography exists, person.biography may be missing for non-trusted requests.

Work Types

Works can be of various types including:

  • journal-article - Peer-reviewed journal articles
  • conference-paper - Conference proceedings
  • book - Books
  • book-chapter - Book chapters
  • dataset - Research datasets
  • preprint - Preprints
  • dissertation-thesis - Dissertations and theses

Example: Building a Publications List 

<div id="publications"></div>

<script>
async function loadPublications(username) {
    const response = await fetch(`/api/works?username=${username}`);
    
    if (!response.ok) {
        console.error('Failed to fetch publications');
        return;
    }
    
    const works = await response.json();
    const container = document.getElementById('publications');
    
    for (const work of works) {
        const data = work.data;
        const title = data.title?.title?.value || 'Untitled';
        const year = data['publication-date']?.year?.value || '';
        const type = data.type || 'unknown';
        
        const div = document.createElement('div');
        div.className = 'publication';
        div.innerHTML = `
            <h3>${title}</h3>
            <p class="meta">${type} - ${year}</p>
        `;
        container.appendChild(div);
    }
}

loadPublications('jsmith');
</script>

Example: Displaying Employment History 

async function getEmploymentHistory(orcid) {
    const response = await fetch(`/api/employments?orcid=${orcid}`);
    const employments = await response.json();
    
    return employments.map(emp => ({
        organization: emp.data.organization?.name,
        role: emp.data['role-title'],
        department: emp.data['department-name'],
        startDate: emp.data['start-date'],
        endDate: emp.data['end-date']
    }));
}

Example: Simple CV Viewer (Live)

This project includes a complete front-end example that renders public ORCID CV content using /api/full:

  • Viewer page: /static/cv-viewer.html
  • API call: /api/full?username=<username>
Live preview: Simple CV Viewer example

Open directly: CV Viewer Example

Printing and "Save as PDF" in this example use the browser's native print dialog, so print styles are preserved whether opened directly or from this iframe.

Caching and Rate Limits

  • Data is cached for 14 days to minimize load on ORCID's API
  • Forced refreshes (?refresh=true) are rate-limited to once per minute
  • If ORCID's API is unavailable, cached data will be returned as a fallback

Cache Response Headers

The response includes metadata about data freshness:

  • dataSource: fresh, cache, cache_fallback, or cache_rate_limited
  • lastUpdate: ISO timestamp of when data was last fetched
  • cacheAgeMs: Age of cached data in milliseconds

Visibility and Privacy

By default, only public ORCID data is returned. If a valid trusted API token is supplied, data with other visibility levels can be included.

Visibility is checked against the current ORCID data, not the cached data, ensuring privacy settings are always respected.

Error Handling 

async function fetchWithErrorHandling(endpoint) {
    const response = await fetch(endpoint);
    const data = await response.json();
    
    if (!response.ok) {
        // Handle errors
        if (response.status === 404) {
            console.error('User not found:', data.error);
        } else if (response.status === 500) {
            console.error('Server error:', data.error);
        }
        return null;
    }
    
    return data;
}

Common Error Responses

Status Meaning
400 Missing username or orcid parameter
404 User not found in database
500 Failed to fetch from ORCID API

Need Help?

For questions about this API or to register your ORCID with the University of Waterloo, please contact the Library's Research Data Services team.

Back to integration information