# Transcript API

# Introduction

The Transcript API is a bundle of new and improved APIs providing access to a user's transcript. These APIs will support the most common operations while following the same business logic, security, rules, and events from the portal’s configuration.

# Release Plan

The various components of the Transcript API will be released in phases (milestones). The latest schedule can be found in the Client Success Center. Please note that the standard SLAs do not apply for APIs Early Adopter. Cornerstone reserves the right to change the Transcript APIs as needed before releasing the APIs as generally available (GA). All forward-looking statements are subject to change.

# User Centric

The Transcript API’s are 'user centric' web services, providing access to a single user's transcript. If you need bulk support, please review the APIs supporting bulk operations (for example: Learning Assignment API, Express Class API, Bulk API's, Reporting API's, Data Exporter API's)

# Transactional

The Transcript APIs are providing real-time read access (GET) to Cornerstone data and real-time write operations (POST/PATCH). A Throttling limit is required to prevent overuse of resources, which is needed to maintain optimal performance and reliability.

# Security

# Permissions and Constraints

Transcript API’s respect the permissions and constraints configured in the portal.

# Additional Claims

All Transcript (PATCH/POST) API’s are respecting additional claims. Requesting additional claims typically involves including the desired claims when making an authorization request to the authorization server.

Example 1 (return single scope - e.g. Complete API only):

curl -X POST \
  https://[corpname].csod.com/services/api/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "clientId": "dbq2kjiql2c4",
    "clientSecret": "l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==",
    "grantType": "client_credentials",
    "scope": "transcript:update transcript:update:complete"
}'

Example 2 (return all available scopes):

curl -X POST \
  https://[corpname].csod.com/services/api/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "clientId": "dbq2kjiql2c4",
    "clientSecret": "l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==",
    "grantType": "client_credentials",
    "scope": "all"
}'

# Throttling

Transcript APIs are available with the following throttling limits:

API	per Minute	per Hour	per Day	Comment
All (GET) Transcript APIs	50	3.000	72.000	Individual limit for each Transcript GET - API
All (POST) Transcript APIs	30	1.800	43.200	Combined (shared) limit for all Transcript POST - APIs
All (PATCH) Transcript APIs	50	3.000	72.000	Combined (shared) limit for all Transcript PATCH - APIs

# Paging

The (GET) endpoints segment large results of data into pages, the default page size is 20.

# Learning Objects

The following Learning objects are supported by the Transcript API:

Curriculum
Event
Session
Material (excluding OJT)
Online Class
Online Content
Video
Test

# Inactive Learning Objects and Users

The following operations are supported for inactive records:

User Active: Support for all HTTP operations (GET/POST/PATCH).
User Inactive: Support for GET operations only.
LO Active: Support for all HTTP operations (GET/POST/PATCH).
LO Inactive: Support for GET operations only.

# Email Events

Certain POST/PATCH operations do support email as configured in the portal.

# Localization

The Transcript API supports multi-language requests for GET operations. If the value included in the query parameter does not match a localized value defined in your Cornerstone portal, the API will fall back on the default language of the portal.

# Identifier

# User

The Transcript APIs supports flexible user identifier:

externalId: String, Externally provided user identifier. This is the 'User Id' visible on the user record.
userId: Integer, Cornerstone-generated internal Id.
userName: String, Employee username, used primarily for system login. This is the 'User Name' visible on the user record.
userGuid: Unique identifier, Cornerstone-generated global unique global identifier (GUID).

# Transcript

Transcript records consist of a history of records, e.g. after each transcript status change, a history is kept, and multiple records are created in the backend. Technically, the following combination of records makes a transcript record uniquely identifiable:

User Identifier
Learning Object Id (GUID)
Registration Number

Some GET-endpoints support querying a specific registration number. If the registration number is not provided (as an input parameter), the API will deliver the latest transcript record automatically.

# Online Content (OLCO)

Online content completion can only be done via the Progress API, which is available to Cornerstone content partners.

# Transcript Lockdown (21 CFR Part 11)

The Transcript API will respect the Transcript Lockdown features (21 CFR Part 11 compliance).

# Examples

# Data (GET)

Description	Url
Return the transcript overview	/services/api/v1/transcripts/overview?externalId=paul.abbot
Return all completed trainings	/services/api/v1/transcripts/overview?externalId=paul.abbot&statusGroups=Completed
Return all trainings which are "not started" or "in progress"	/services/api/v1/transcripts/overview?externalId=paul.abbot&statusGroups=NotStarted,InProgress
Return the transcript overview including archived trainings	/services/api/v1/transcripts/overview?externalId=paul.abbot&includeArchived=true
Return the transcript overview for "Online Class"	/services/api/v1/transcripts/overview?externalId=paul.abbot&trainingType=OnlineClass
Return the transcript overview for "Materials" and "Videos"	/services/api/v1/transcripts/overview?externalId=paul.abbot&trainingType=Material,Video
Return all completed "Sessions"	/services/api/v1/transcripts/overview?externalId=paul.abbot&statusGroups=Completed&trainingType=Session
Return all completed "Curricula"	/services/api/v1/transcripts/overview?externalId=paul.abbot&statusGroups=Completed&trainingType=Curriculum
Return all transcript records with "Pending Approval"	/services/api/v1/transcripts/overview?externalId=paul.abbot&status=PendingApproval
Return transcript custom fields	/services/api/v1/transcripts/custom-fields?externalId=paul.abbot&learningObjectId=b42d13a5-f7dc-40d1-8a52-5e6b572604df
Return child related details for a curricula transcript record	/services/api/v1/transcripts/curriculum-child-lo-data?externalId=paul.abbot&learningObjectId=72be8841-0b7c-4e7a-baed-da906ce99c2b

# Assign a Training (POST)

Assign, approve and register a training.

/services/api/v1/transcripts/assign
{
  "externalId": "paul.abbot",
  "learningObjectId": "7ad38cb9-04e1-47be-8334-09a4484f82ad",
  "assignment": "registered",
}

# In Progress (PATCH)

Change a registered transcript record from "Registered" to "In Progress".

/services/api/v1/transcripts/progress
{
  "externalId": "paul.abbot",
  "learningObjectId": "7ad38cb9-04e1-47be-8334-09a4484f82ad"
}

# Update Due Date (PATCH)

Update Due Date.

/services/api/v1/transcripts/update
{
  "externalId": "paul.abbot",
  "learningObjectId": "b1a4185e-26b5-4b60-8ea7-ce5bc050804a",
  "dueDate": "2023-12-31",
  "comment": "Changed by API" 
}

# Update a Custom Field (PATCH)

Update a (textbox) custom field with the Email Tag name "Transcript Comment".

/services/api/v1/transcripts/update
{
  "externalId": "paul.abbot",
  "learningObjectId": "285a8af7-b7d0-475d-b199-dc88e6966bbf",
  "comment": "Changed by API", 
  "customFields": [
        {
        "name": "Transcript Comment",
        "values" : ["My Comment"]
        }
    ]
}

# Training Completion (PATCH)

Mark a learning object in an active users transcript complete. Ignore any (potential) post pending workflow configuration and right set the transcript record to "Completed".

/services/api/v1/transcripts/complete
{
  "externalId": "paul.abbot",
  "learningObjectId": "285a8af7-b7d0-475d-b199-dc88e6966bbf",
  "ignoreWorkflow": true
}

# Remove Training (PATCH)

Remove a Learning Object (LO) from a users transcript and place it in the 'Removed' tab of the transcript. The 'reason' needs to be a value from pre-defined list of reasons as configured in the portal.

/services/api/v1/transcripts/remove
{
  "externalId": "paul.abbot",
  "learningObjectId": "10e65284-3cdb-4f9f-9329-03823f56647c",
  "action": "remove",
  "reason": "Other",
  "comment": "Removed By API"
}