Transcript Search

Use this API to pull for multiple users' transcript data.

  • This API observes all business rules configured in the portal.
  • Only Transcript data for active users can be retrieved using this API.
  • This API does not support training and transcript custom fields, i.e., custom fields are not returned in the response.
  • API responses are paginated with a maximum of 50 records included in each page. Additional data can be retrieved through subsequent calls by incrementing the pageNumber query parameter.
  • Date/time attributes sent in the request should be in Coordinated Universal Time (UTC).
  • API calls for time durations will be limited to 24 Hours. See additional guidance below in the 'Time Ranges' section.
  • If no duration is provided, API responses will default to the last 24 hours from the time the request is made.
  • If only the ModificationStartDate parameter is provided, data from the following 24 hours will be returned.
  • If only the ModificationEndDate parameter is provided, data from the past 24 hours will be returned.
  • If multiple query parameters are used in the call (for example, ModificationEndDate, UserId, and LOType) the AND operator will be used for retrieving the data.

Permissions Required:

  • Users - View
  • View Transcript Item

OAuth 2.0 Scope: transcript:read

Time Ranges

The Transcript Search API allows retrieving transcript data for multiple users within a given date/time range. If you are calling the service in consecutive iterations, the date/time value needs to be properly included in the request to prevent the possibility of duplicate transcript records in the responses. Here are some examples of time ranges.

Daily Call Examples:

  • First request:
  • ModificationStartDate: 2013-02-26T00:00:00
  • ModificationEndDate: 2013-02-26T23:59:59
  • Second request:
  • ModificationStartDate: 2013-02-27T00:00:00
  • ModificationEndDate: 2013-02-27T23:59:59

This works as well (without the ModifcationEndDate value):

  • First request:
  • ModificationStartDate: 2013-02-26T00:00:00
  • Second request:
  • ModificationStartDate: 2013-02-27T00:00:00

For daily API calls, if the ModificationStartDate value of the second request is the same as the ModificationEndDate value of the first request, then there is a possibility of the API returning duplicate transcript records. That is why we recommend having the ModificationStartDate be in the YYYY-MM-DDT00:00:00 format and the ModificationEndDate be in the YYYY-MM-DDT23:59:59 format, so that the request spans the entire day properly and doesn’t overlap with the previous and next request’s date/time range.

Hourly Calls Examples:

  • First request:
  • ModificationStartDate: 2013-02-26T11:00:00
  • ModificationEndDate: 2013-02-26T11:59:59
  • Second request:
  • ModificationStartDate: 2013-02-26T12:00:00
  • ModificationEndDate: 2013-02-26T12:59:59

For hourly API calls, if the ModificationStartDate value of the second request is the same as the ModificationEndDate value of the first request, then there is a possibility of the API returning duplicate transcript records. That is why it’s recommended to have the ModificationStartDate be in the YYYY-MM-DDTHH:00:00 format and the ModificationEndDate be in the YYYY-MM-DDTHH:59:59 format for hourly calls, so that the request spans the entire hour properly and doesn’t overlap with the previous and next request’s date/time range.

Record Duplication:

The Transcript Search API sends responses as soon as it becomes available rather than waiting until it receives all the records from the database before sending them out. This allows the API to provide access to very large data sets very efficiently, using a relatively small memory footprint on our servers. This is important to consider because it means the data the Transcript Search API operates on can potentially change at any time, while you are executing your queries. As you retrieve records, page after page, new transcript data created or updated in your Cornerstone portal can cause the record positions returned in the API to shift. A previously retrieved record can potentially re-appear in subsequent pages and potentially cause errors as you process it on your end. This effect can be minimized by reducing the time duration for which you are retrieving the transcript records. However, it cannot be avoided completely.

It is highly recommended that you first stage the data you retrieve using this API across all pages in temporary storage, run any validation logic you deem necessary, including checking for duplicate records, before sending it to its final destination in your pipeline.

Localization

The following request and response fields support localization. The API considers the language of the user associated with the OAuth 2.0 application to determine the locale for these fields.

Localized Request Fields:

  • LOType
  • Status

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 to validate the value you sent in the query.

Localized Response Fields:

  • LOType
  • CourseId
  • CourseName
  • CourseDescription
  • TranscriptStatus

Cornerstone's Data Warehouse

The Transcript Search API by default fetches data from your Cornerstone portal's transactional database. The API limits the page size to 50 records to reduce the impact on our resources while providing reliable service to all our clients using the API.

However, in certain instances, you may want to retrieve large volumes of transcript data using this API. To provide a scalable method to retrieve large volumes of transcript data, this API includes a boolean query parameter called UseDataWarehouse. If you set this value to true, the API retrieves data from your Cornerstone portal's data warehouse with increased page size (up to 1000 records per page). Note that the data warehouse is refreshed about every 15 minutes from the transactional database, so there might be a slight delay in a transaction occurring in the UI and it appearing in the Transcript Search API.

Transcript Statuses

The table below lists the valid values for the Status request parameter.

Transcript Status in the UIValue that should be in the "Status" Parameter
ApprovedApproved
CancelledCancelled
CompletedCompleted
DeniedDenied
DiscontinuedDiscontinued
ExpiredExpired
FailedFailed
WaitlistedGranted Waitlist
ExemptMarked Exempt
IncompleteMarked Incomplete
Payment DeniedPayment Denied
Pending paymentPending payment
Payment refundedPurpose category modified
RegisteredRegistered
Exception RequestedRequested Exception
SF-182 Form DeniedSF-182 Form Denied
In ProgressStarted
WithdrawnWithdrawn

Action Statuses

The service pulls historical data (e.g. for status change information) from the action history table. Depending on the data constellation (for example, if the transcript status has been updated or not), this can lead to returning the latest "action status" (e.g. "Edited") rather than returning the "transcript status" in the response.

Learning Object Types

The table below lists the valid values for the LOType request parameter.

Learning Object Type
Action Step
Book
Connect Block
Connect Item
Connect Topic
Curriculum
Discussion
Document
Evaluation Test
Event
External Training
Form
Library
Material
Note
Objective
Observation Checklist
Online Class
Online Resource
Q&A
Quick Course
Section
Session
Test
Topic
Video

Error Descriptions

Handled Error List

Error TypesError Message
StatusStatus missing.
ModificationStartDateInvalid ModificationStartDate
ModificationEndDateInvalid ModificationEndDate