Panorama API – YuJa Help Center

Authentication

Every API call requires an authentication token as part of the body or query of the request. When logged in, your token can be found by clicking on the Panorama browser extension. In your request, please label this parameter as an authentication Token.

Transport and Encoding

The current API only supports the JSON data format. It is recommended to specify the application/json as the accepted header, but it is not required.

API Base URL

The base URL for the Panorama API is dependent on which zone your institution is registered in. If you are unsure which zone your institution is in, please contact your Customer Success Manager. For security protocols, only https access is allowed.

For User, Institution, Course, Term and Sub-Account models:

United States Zone: https://panorama.yuja.com/api

Canadian Zone: https://panorama-cz.yuja.com/api

European Zone: https://panorama-ez.yuja.com/api

Australian Zone: https://panorama-az.yuja.com/api

For Document Models:

United States Zone: https://panorama-api.yuja.com/

Canadian Zone: https://panorama-api-cz.yuja.com/

European Zone: https://panorama-api-ez.yuja.com/

Australian Zone: https://panorama-api-az.yuja.com/

Rest API Response Codes

Status Code	Meaning
200	OK
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error
502	Bad Gateway

Models

The Panorama API is broken down into several models, each representing a different entity, such as courses or documents. The models below may not include all fields available and instead show only the core fields of that model.

1 - User Model API Overview

The User model represents all individuals who are associated with the access token provided or are part of the institution.

1.1 - User Models Core

Variable	Type	Description
userId	string	A unique userId that is generated by the system.
lmsUserId	string	The userId your lms has generated for the user.
email	string	The user's email address.
firstName	string	The user's first name.
lastName	string	The user's last name.
role	string	The system role of the user.
locked	boolean	Whether the system role for this user is locked or not.

1.2 - Main Endpoints

Method	Path	Description	Access Level Required
GET	/user/getUser	Retrieves the current user associated with the access token provided.	Student
GET	/user/getPaginatedUsers	Retrieves an array of users in your institution.	Administrator
POST	/user/updateUserInfo	Updates the user's first name, last name, and email address.	Administrator

1.2.1 - GET /user/getUser

Retrieves the current user associated with the access token provided.

Example URL: https://panorama.yuja.com/api/user/getUser

Parameter:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.

Example JSON Data:

{
"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tvc"
}

1.2.2 - GET /user/getPaginatedUsers

Retrieves an array of users in your institution.

Example URL: https://panorama.yuja.com/api/user/getPaginatedUsers

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
page	integer	A unique userId that is generated by the system.
pageSize	integer	The number of records to receive on each page.

Example JSON Request:

{
    "authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc",
    "page": 2,
    "pageSize": 10
}

1.2.3 - POST /user/updateUserInfo

Updates the user's first name, last name, and email address.

Example URL: https://panorama.yuja.com/api/user/updateUserInfo

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
userId	string	The unique userId of the user being updated.
firstName	string	The user's first name.
lastName	string	The user's last name.
email	string	The user's email address.

Example JSON Request:

{
    "authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc",
    "userId": "2ffdc6e2-b250-4c53-b706-d4e2856beaeb",
    "firstName": "Lauren",
"lastName": Barnes",
"email": "lauren.barnes@mail.utoronto.ca"
}

2 - Sub-Account Model API Overview

The sub-account model represents all sub-accounts available to the individual accessing the API.

2.1 - Sub-Account Model Core

Variable	Type	Description
subAccountId	string	A unique subAccountId that is generated by the system.
parentSubAccountId	string	A unique subAccountId that is generated by the system for the subAccount’s parent subAccount.
lmsSubAccountId	string	The subAccountId your lms has generated for the sub-account.
lmsParentSubAccountId	string	The subAccountId your lms has generated for the sub-accounts parent sub-account.
name	string	The name of the sub-account.

2.2 - Main Endpoints

Method	Path	Description	Access Level Required
GET	/subAccount/getPaginatedSubAccounts	Retrieves a list of sub-sccounts in your institution that you have access to.	Sub-Administrator

2.2.1 - GET /subAccount/getPaginatedSubAccounts

Retrieves a list of sub-accounts in your institution that you have access to.

Example URL: https://panorama.yuja.com/api/subAccount/getPaginatedSubAccounts

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
page	integer	The page to start on (starts at 1).
pageSize	integer	The number of records to receive on each page.

Example JSON Data:

{
    "authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc",
    "page": 2,
    "pageSize": 10
}

3 - Term Model API Overview

The Term Model represents all terms available to the individual accessing the API.

3.1 - Term Model Core

Variable	Type	Description
termId	string	A unique termId that is generated by the system.
lmsTermId	string	The termId your lms has generated for the term.
name	string	The name of the sub-account.
start	Date	The term start date.
end	Date	The term end date.

3.2 - Term model Main Endpoints

Method	Path	Description	Access Level Required
GET	/term/getPaginatedTerms	Retrieves an array of Terms in your institution.	Instructor

3.2.1 - GET /term/getPaginatedTerms

Example URL: https://panorama.yuja.com/api/term/getPaginatedTerms

Retrieves an array of Terms in your institution.

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
page	integer	The page to start on (starts at 1).
pageSize	integer	The number of records to receive on each page.

Example JSON Data:

{
    "authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc",
    "page": 2,
    "pageSize": 10
}

4 - Institution Model API Overview

The Institution Model retrieves information administrators, and sub-admins have access to, such as Institution Reports, Content Reports, and Issues Reports.

4.1 - Institution Model Core

Variable	Type	Description
institutionId	string	A unique institutionId that is generated by the system.
lmsType	string	The type of lms associated with the institution (e.g. Canvas).
name	string	The institution’s name.
primaryIdentifierKey	string	A unique identifier key that is generated by the system.
secondaryIdentifierKey	string	A unique secondary identifier key that is generated by the system.
consumerKey	string	A unique key generated by the system to be used for LTI 1.1.
ltiSecret	string	A unique key generated by the system to be used for LTI 1.1.
clientId	string	The client Id associated with the institution. Used for LTI 1.3.
deploymentId	string	The deployment Id associated with an LTI deployment. Used for LTI 1.3.
iss	string	The issuer associated with the institution. Used for LTI 1.3.
OIDCEndpoint	string	The OIDC endpoint for the institution. Used for LTI 1.3.
JWKSEndpoint	string	The JWKS endpoint for the institution. Used for LTI 1.3.
domain	string	The domain of the institution.
lmsAPILink	string	The API endpoint associated with the institution.
accessToken	string	The access token of the institution. Used for API requests to the institution.

4.2 - Institution Model Main Endpoints

Method	Path	Description	Access Level Required
GET	/institution/getInstitutionInformation	Retrieves information about the institution associated with your account.	Administrator
GET	/institution/exportInstitutionReport	Downloads an accessibility report for the associated institution. It can be filtered by sub-accounts and terms that you have access to.	Sub-Administrator
GET	/content/exportContentReportData	Downloads a content report for the associated institution. It can be filtered by sub-accounts and terms you have access to.	Sub-Administrator
GET	/issue/exportIssuesReport	Download the Issues Report for the associated institution. It can be filtered by sub-accounts and terms you have access to.	Sub-Administrator

4.2.1 - GET /institution/getInstitutionInformation

Retrieves information about the institution associated with your account.

Example URL: https://panorama.yuja.com/api/institution/getInstitutionInformation

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.

Example JSON Data:

{
"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc"
}

4.2.2 - GET /institution/exportInstitutionReport

Email and download the LMS accessibility report. This report can be filtered by sub-accounts and terms, allowing you to view all relevant data for your institution and courses.

Example URL: https://panorama.yuja.com/api/institution/exportInstitutionReport

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
subAccountId	string	The subaccount ID by which you would like to filter the report. Optional.
terms	array	The term ID and term name by which you would like to filter the report. Optional.
email	string	The email that will receive the report.
shouldEmail	Boolean	The report will be emailed to the user if set to "true".
fileType	string	The type of file you want the report as. Options: "Excel" or "JSON"
startYear	integer	The year you'd like to start at.
startMonth	integer	The month you'd like to start at. (Months will begin counting at 1, with January being 1 and December being 12.)
endYear	integer	The year you'd like to end at.
endMonth	integer	The month you'd like to end at. (Months will begin counting at 1, with January being 1 and December being 12.)

Example JSON Data:

{
    "authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc",
    "subAccountId": "21a6a8d8-a609-4d60-ab21-9eca9013bb65",
    "terms":"[{\"termId\":\"055e8635-c857-4f13-8b0f-63de5cb66aa1\",\"name\":\"Fall Term\"}]",
"email": "mathew.tyler@yuja.com",
"shouldEmail": true,
"fileType": "Excel",
"startYear": 2022,
"startMonth": 4,
"endYear": 2023,
"endMonth": 5
}

4.2.3 - GET /content/exportContentReportData

Downloads a content report for the associated institution with the option to filter by sub-accounts and terms you have access to.

ExampleURL: https://panorama.yuja.com/api/content/exportContentReportData

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
subAccountId	string	The subaccount ID you would like to filter the report by. Optional.
termId	string	The term ID you would like to filter the report by. Optional.
email	string	The email that will receive the report.
shouldEmail	Boolean	The report will be emailed to the user if set to "true".
fileType	string	The type of file you want the report as. Options: "Excel" or "JSON"
startYear	integer	The year you'd like to start at.
startMonth	integer	The month you'd like to start at. (Months will begin counting at 1, with January being 1 and December being 12.)
endYear	integer	The year you'd like to end at.
endMonth	integer	The month you'd like to end at. (Months will begin counting at 1, with January being 1 and December being 12.)

Example JSON Data:

{
    "authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc",
    "subAccountId": "21a6a8d8-a609-4d60-ab21-9eca9013bb65",
    "termId": "60450295d546b0b925a2a7c4",
"email": "mathew.tyler@yuja.com",
"shouldEmail": true,
"fileType": "Excel",
"startYear": 2022,
"startMonth": 4,
"endYear": 2023,
"endMonth": 5
}

4.2.4 - GET /issue/exportIssuesReport

Download the Issues Report for the associated institution. It can be filtered by sub-accounts and terms you have access to.

Example URL: https://panorama.yuja.com/api/issue/exportIssuesReport

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
subAccountId	string	The sub-account ID you would like to filter the report by. Optional.
termId	string	The term ID you would like to filter the report by. Optional.
email	string	The email that will receive the report.
fileType	string	The type of file you want the report as. Options: "Excel" or "JSON"
startYear	integer	The year you'd like to start at.
startMonth	integer	The month you'd like to start at. (Months will begin counting at 1, with January being 1 and December being 12.)
endYear	integer	The year you'd like to end at.
endMonth	integer	The month you'd like to end at. (Months will begin counting at 1, with January being 1 and December being 12.)

Example JSON Data:

{
    "authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc",
    "subAccountId": "21a6a8d8-a609-4d60-ab21-9eca9013bb65",
    "termId": "60450295d546b0b925a2a7c4",
"email": "mathew.tyler@yuja.com",
"fileType": "Excel",
"startYear": 2022,
"startMonth": 4,
"endYear": 2023,
"endMonth": 5
}

5 - Course Model API Overview

The Course model retrieves courses and course reports

5.1 - Course Model Core

Variable	Type	Description
contextId	string	The course Id your lms has generated for the course.
name	string	The name of the course.

5.2 - Course Model Main Endpoints

Method	Path	Description	Access Level Required
GET	/course/getPaginatedCourses	Retrieves an array of courses in your institution that you have access to.	Instructor
GET	/document/getPaginatedCourseDocuments	Retrieves an array of documents in a course.	Instructor
GET	/course/exportCourseReport	Downloads a course report for the associated course.	Administrator

5.2.1 - GET /course/getPaginatedCourses

Retrieves an array of courses in your institution that you have access to.

Example URL: https://panorama.yuja.com/api/course/getPaginatedCourses

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
page	integer	The page to start on (starts at 1).
pageSize	integer	The number of records to receive on each page.

Example JSON Data:

{
    "authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc",
    "page": 2,
    "pageSize": 10
}

5.2.2 - GET /document/getPaginatedCourseDocuments

Retrieves an array of documents in a course.

Example URL: https://panorama.yuja.com/api/document/getPaginatedCourseDocuments

Parameters:

Name	Type	Description
authenticationToken	string	Your authentication token. Used for authenticating the request.
contextId	string	The ID of the course you would like to get the documents of.
page	integer	The page you'd like to start on (starts at 1).
pageSize	integer	The number of
startYear	integer	The year you'd like to start at.
startMonth	integer	The month you'd like to start at. (Months will begin counting at 1, with January being 1 and December being 12.)
endYear	integer	The year you'd like to end at.
endMonth	integer	The month you'd like to end at. (Months will begin counting at 1, with January being 1 and December being 12.)

Example JSON Data:

{
    "authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc",
    "contextId": "362",
    "page": 10,
"pageSize": 12
"startYear": 2022,
"startMonth": 4,
"endYear": 2023,
"endMonth": 5
}

5.2.3 - GET /course/exportCourseReport

Download a course report for the associated course.

Example URL: https://panorama.yuja.com/api/course/exportCourseReport

Parameters:

Name	Type	Description
authenticationToken	string	The user’s authentication token. Used for authenticating the request.
contextId	string	The contextId of the course you would like to get the report of.
email	string	The email that will receive the report.
fileType	string	The type of file you want the report as. Options: "Excel" or "JSON"
startYear	integer	The year you'd like to start at.
startMonth	integer	The month you'd like to start at. (Months will begin counting at 1, with January being 1 and December being 12.)
endYear	integer	The year you'd like to end at.
endMonth	integer	The month you'd like to end at. (Months will begin counting at 1, with January being 1 and December being 12.)

Example JSON Data:

{
"authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc",
"contextId": "202"
"email": "mathew.tyler@yuja.com",
"fileType": "Excel",
"startYear": 2022,
"startMonth": 4,
"endYear": 2023,
"endMonth": 5
}

6 - Document Model

The Document Model retrieves information indicating the status of documents and their Alternative Formats.

6.1 - Document Model Main Endpoints

Variable	Type	Description
accessibilityFormats	Array<ConversionFormat>	A list of alternative formats for the document and which state of processing they are in.
errorInterceptingDocument	boolean	A boolean indicating whether or not the document has had an error during retrieval from the LMS.
accessibilityReportInfo	AccessibilityReportInfo	Information surrounding the accessibility report of the document. Only available with sufficient permissions.
fileTypeNotSupported	boolean	A boolean indicating whether or not the document is of a file type supported by Panorama.
uploadedByStudent	boolean	A boolean indicating whether or not the document is uploaded by a student.
formatsHiddenFromStudents	boolean	A boolean indicating whether or not the document’s alternative formats are hidden from students.
sourceDocumentUnavailable	boolean	A boolean indicating whether or not the document has had an error during source file retrieval.
documentExpired	boolean	A boolean indicating whether or not the document has expired.
documentId	string	A unique institutionId that is generated by the system.
documentFormat	string	The extension type of the document.
documentName	string	The document’s name.
documentType	String	The document type.
documentSource	string	The source of the document.

6.2 - Document Model Main Endpoints

Method	Path	Description	Access Level Required
POST	/api/documentDetails	Retrieves all details about a specified document.	Instructor for full access to the API and student for limited access.
POST	/api/generateFormat	Generates an Alternative Format or Accessibility Report for a specified document.	Instructor for full access to the API and student for limited access.
POST	/api/downloadFormatUrl	Retrieves a download URL that can be used to download an Alternative Format for a specified document.	Instructor for full access to the API and student for limited access.

6.2.1 - POST /api/documentDetails

Retrieves all details about a specified document.

Example URL: https://panorama-api.yuja.com/api/documentDetails

Parameters:

Name	Type	Description
identifierKey	string	The primary identifierKey for your institution.
extensionToken	string	Your authentication token. Used for authenticating the request.
documentId	string	A unique ID of the document that can be retrieved from the paginated course documents API in section 5.2.2.

Example JSON Data:

{
"identifierKey": "3b7a63c37e8c860bbb05bb550c5c1f0e817c2aad73056efd87bc848545a7f1j4",
"extensionToken": "1127c11a-eb75-4a41-8ccc-566646f94blc",
"documentId": "fcb6e196-b807-480d-9030-c29413e5bc2f1"
}

6.2.2 - POST /api/generateFormat

Generates an Alternative Format or Accessibility Report for a specified document.

Example URL: https://panorama-api.yuja.com/api/generateFormat

Note: The identifierKey and extensionToken must be set as Query Params. The identifierKey must be set as the Key, and the extensionToken must be set as the Value.

Parameters:

Name	Type	Description
identifierKey	string	The primary identifierKey for your institution.
extensionToken	string	Your authentication token. Used for authenticating the request.
documentId	string	The unique ID of the document.
type	string	Choose whether you'd like to "generate" or "reprocess" the document. Valid options: generate: Generates the Alternative Format if not available. reprocess: Reprocesses the Alternative Format if it’s been generated.
format	string	The Alternative Format you'd like to generate or reprocess. Valid options: enhanced_html report source base pdf immersive_html gradient_txt txt epub brf mp3 png math_latex math_txt math_mp3 ocr_pdf ocr_reconstructed_docx ocr_reconstructed_pdf ocr_reconstructed_html ocr_txt ocr_mp3
language	string	The language in which the Alternative Format is generated. If no translation is needed, then this field should be sent as the following: default If a translation is needed, please set this field to be the language code. examples: For Canadian French, this field should be: fr-ca For Greek, this field should be: el
documentType	string	The document source returned from the document details API in section 6.2.1.
documentSource	string	The document source returned from the document details API in section 6.2.1.

Example JSON Data:

{
"identifierKey": "3b7a63c37e8c860bbb05bb550c5c1f0e817c2aad73056efd87bc848545a7f1j4",
"extensionToken": "1127c11a-eb75-4a41-8ccc-566646f94blc",
"documentId": "fcb6e196-b807-480d-9030-c29413e5bc2f1",
"type": "generate",
"format": "pdf",
"language": "el",
"documentType": "discussion",
"documentSource": "lms"
}

6.2.3 - POST /api/downloadFormatUrl

Example URL: https://panorama-api.yuja.com/api/downloadFormatUrl

Note: The download URL returned will only be available for one hour, and this format must have previously been generated and have a status of complete when viewing its status in document details.

Parameters:

Name	Type	Description
identifierKey	string	The primary identifierKey for your institution.
extensionToken	string	Your authentication token. Used for authenticating the request.
documentId	string	The unique ID of the document
format	string	The Alternative Format you'd like to download. Valid options: enhanced_html report source base pdf immersive_html gradient_txt txt epub brf mp3 png math_latex math_txt math_mp3 ocr_pdf ocr_reconstructed_docx ocr_reconstructed_pdf ocr_reconstructed_html ocr_txt ocr_mp3
language	string	The language in which the Alternative Format is generated. If no translation is needed, then this field should be sent as the following: default If a translation is needed, please set this field to be the language code. example: For Canadian French, this field should be: fr-ca For Greek, this field should be: el

Example JSON Data:

{
"identifierKey": "3b7a63c37e8c860bbb05bb550c5c1f0e817c2aad73056efd87bc848545a7f1j4", "extensionToken": "1127c11a-eb75-4a41-8ccc-566646f94blc",
"documentId": "fcb6e196-b807-480d-9030-c29413e5bc2f1",
"format": "pdf",
"language": "el"
}

Authentication

Transport and Encoding

API Base URL

For User, Institution, Course, Term and Sub-Account models:

For Document Models:

Rest API Response Codes

Models

1 - User Model API Overview

1.1 - User Models Core

1.2 - Main Endpoints

1.2.1 - GET /user/getUser

1.2.2 - GET /user/getPaginatedUsers

1.2.3 - POST /user/updateUserInfo

2 - Sub-Account Model API Overview

2.1 - Sub-Account Model Core

2.2 - Main Endpoints

2.2.1 - GET /subAccount/getPaginatedSubAccounts

3 - Term Model API Overview

3.1 - Term Model Core

3.2 - Term model Main Endpoints

3.2.1 - GET /term/getPaginatedTerms

4 - Institution Model API Overview

4.1 - Institution Model Core

4.2 - Institution Model Main Endpoints

4.2.1 - GET /institution/getInstitutionInformation

4.2.2 - GET /institution/exportInstitutionReport

4.2.3 - GET /content/exportContentReportData

4.2.4 - GET /issue/exportIssuesReport

5 - Course Model API Overview

5.1 - Course Model Core

5.2 - Course Model Main Endpoints

5.2.1 - GET /course/getPaginatedCourses

5.2.2 - GET /document/getPaginatedCourseDocuments

5.2.3 - GET /course/exportCourseReport

6 - Document Model

6.1 - Document Model Main Endpoints

6.2 - Document Model Main Endpoints

6.2.1 - POST /api/documentDetails

6.2.2 - POST /api/generateFormat

6.2.3 - POST /api/downloadFormatUrl

Related articles