Reporting API Endpoints
Warning
Endpoints included in the API for reporting are private endpoints and do not come with a deprecation policy at this time. Anthology Ally may change or update these endpoints depending on our roadmap or future releases.
Review the following technical documentation to learn how to appropriately set up and customize your endpoints. Feel free to check how to Integrate Ally's API with an External Reporting Tool for additional guidance.
Available methods
The Ally API for reporting has two methods. The following section describes them:
Method | URL | HTTP Request Type | Description |
Overall | https://[region]/api/v2/clients/[Ally Client ID]/reports/overall | Get | By default, this method returns a dataset with information about the course, WYSIWYG, and files' scores and file types included in each course from the LMS instance, regardless of whether Ally is enabled or not. |
Issues | https://[region]/api/v2/clients/[Ally Client ID]/reports/issues | Get | By default, this method returns a dataset with the information related to all the accessibility issues happening in each course, included in the LMS instance, regardless of whether Ally is enabled or not. |
Tip
Replace [Ally Client ID] with your Ally ID. If you do not know your ID, you can create a support ticket to request it.
Tip
Replace [Region] depending on the region where the Ally environment of your institution is hosted:
US data center: prod.ally.ac
Canadian data center: prod-ca-central-1.ally.ac
European data center: prod-eu-central-1.ally.ac
Singapore data center: prod-ap-southeast-1.ally.ac
Australian data center: prod-ap-southeast-2.ally.ac
The information above may vary depending on the LMS. You can review the column definition in the Course Report Documentation for each LMS:
HTTP Status Response
The Ally API includes an status field in the metadata as follows:
Status 200 - Successful: Your request was received successfully and the requested dataset is part of the response.
Status 202 - Processing: Your request was received successfully but the dataset is under preparation, and is not available yet. Repeat your request after some time (at least one minute is recommended).
Status 401 - Unauthorized: The Ally Client ID or the authorization token are not correct.
Status 400 - Bad request: The URL has an invalid parameter name, for example, an unknown filter option, operator or value. Review the syntax of the URL. Remember that some of the filter and sorting options are case sensitive.
Methods Documentation
Method: Overall
HTTP request: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall
Replace [Ally Client ID] with your Ally ID. If you do not know your ID, you can create a support ticket to request it.
Replace [Region] depending on the region where the Ally environment of your institution is hosted:
US data center: prod.ally.ac
Canadian data center: prod-ca-central-1.ally.ac
European data center: prod-eu-central-1.ally.ac
Singapore data center: prod-ap-southeast-1.ally.ac
Australian data center: prod-ap-southeast-2.ally.ac
Authorization: OAuth bearer token.
Parameters: Optional filters or sorting options.
Request Body: None
Response:
{
"data": [
{
"application/x-quiz": 2,
"observedDeletedOn": "",
"termName": "Fall 2016",
"courseId": "1",
"application/x-announcement": 0,
"image": 4,
"termId": "2",
"document": 93,
"allyEnabled": true,
"pdf": 74,
"courseCode": "BIO101",
"application/x-assignment": 0,
"departmentId": "1",
"totalFiles": 192,
"courseUrl": "https://ally.instructure.com/courses/1",
"departmentName": "Anthology Ally",
"application/x-page": 1,
"filesScore": 0.6022810739019293,
"application/x-syllabus": 1,
"numberOfStudents": 1,
"html-page": 5,
"lastCheckedOn": "2022-04-13 15:33:23",
"WYSIWYGScore": 1.0,
"totalWYSIWYG": 5,
"courseName": "Biology 101",
"application/x-discussion-topic": 1,
"other": 11,
"overallScore": 0.6129724428830603,
"presentation": 5
}
],
"metadata": {
"filteredTotal": 0,
"total": 7186,
"to": 7186,
"status": "Processing",
"from": 1
}
} Method: Issues
HTTP request: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall
Replace [Ally Client ID] ID with your Ally ID. If you do not know your ID you can create a support ticket to request it.
Replace [Region] depending on the region where the Ally environment of your institution is hosted:
US data center: prod.ally.ac
Canadian data center: prod-ca-central-1.ally.ac
European data center: prod-eu-central-1.ally.ac
Singapore data center: prod-ap-southeast-1.ally.ac
Australian data center: prod-ap-southeast-2.ally.ac
Authorization: OAuth bearer token
Parameters: Optional filters or sorting options.
Request Body: None
Response:
{
"data": [
{
"imageDecorative2": 4,
"htmlEmptyHeading2": 0,
"imageSeizure1": 2,
"observedDeletedOn": "",
"htmlObjectAlt2": 0,
"security1": 3,
"termName": "Fall 2016",
"courseId": "1",
"languageCorrect3": 14,
"htmlColorContrast2": 2,
"htmlLinkName3": 0,
"termId": "2",
"languagePresence3": 10,
"allyEnabled": true,
"htmlLabel2": 0,
"alternativeText2": 68,
"htmlImageAlt2": 0,
"htmlImageRedundantAlt3": 0,
"headingsPresence2": 20,
"courseCode": "BIO101",
"headingsSequential3": 4,
"departmentId": "1",
"htmlHeadingsPresence2": 0,
"courseUrl": "https://ally.instructure.com/courses/1",
"headingsStartAtOne3": 4,
"departmentName": "Anthology Ally",
"htmlHeadingsStart2": 0,
"htmlTdHasHeader2": 0,
"htmlList3": 0,
"htmlDefinitionList3": 0,
"htmlCaption2": 0,
"tableHeaders2": 23,
"htmlEmptyTableHeader2": 0,
"htmlHasLang3": 1,
"ocred2": 0,
"scanned1": 6,
"htmlBrokenLink2": 0,
"numberOfStudents": 1,
"htmlHeadingOrder3": 0,
"lastCheckedOn": "2022-04-13 15:33:23",
"headingsHigherLevel3": 0,
"contrast2": 28,
"title3": 46,
"imageOcr3": 0,
"tagged2": 4,
"libraryReference": 172,
"courseName": "Biology 101",
"imageContrast2": 0,
"imageDescription2": 4,
"htmlTitle3": 1,
"parsable1": 2
}
],
"metadata": {
"filteredTotal": 0,
"total": 7186,
"to": 7186,
"status": "Processing",
"from": 1
}
} Where:
Data: contains the data set of the results.
Metadata:
To: record to which data will be fetched, it's “offset” + “limit” or “total” if the sum exceeds “total”.
From: record from which data will start, it's “offset” + 1.
Total: total number of courses considered by Ally in the LMS instance.
Offset - from which record start
First row is offset = 0,
When offset < 0, then the user gets error 400 - [Invalid value (parameter=offset, message=No such data)],
When (offset >= total) => then user gets error 400 - [Invalid value (parameter=offset, message=No such data) ]
Limit - how many records are retrieved beginning from offset
When (limit < 1), then the user gets error 400 - [Invalid value (parameter=limit, message=Limit out of boundaries)]
When (limit > 10000) then the user gets error 400 - [Invalid value (parameter=limit, message=Limit out of boundaries)]
When (offset < total && offset + limit > total), then we change the limit in the background for you, and data will be retrieved until last (total)
Filters and sorting options
Endpoint responses can be filtered in the URL. This section describes the available options:
Sorting options
You can define if you want to display the results sorted in ascending or descending order considering one criterion. If you need to add a sorting option, you must add the sorting parameter as described below:
endpoint-url?sort=<Sort parameter value>
Where <Sort parameter value> can be any of the following parameter values:
Parameter value | Description | Supported in | Example |
courseName | Sort by course name, e.g. Chemistry 101 (courseCode is not valid) | Overall and Issues endpoints | endpoint-url?sort=courseName |
courseId | Sort by course ID, e.g. 123456 (this is usually a whole number) | Overall and Issues endpoints | endpoint-url?sort=courseId |
termId | Sort by term ID. E.g. Sum | Overall and Issues endpoints | endpoint-url?sort=termId |
termName | Sort by term Name. e.g. Summer | Overall and Issues endpoints | endpoint-url?sort=termName |
overallScore | Sort by the overall accessibility score of each course. | Overall endpoint only. | endpoint-url?sort=overallScore |
filesScore | Sort the results by the file score of each course. | Overall endpoint only. | endpoint-url?sort=filesScore |
wysiwygScore | Sort the results by the WYSIWYG score of each course. | Overall endpoint and only available for Ally for LMS. | endpoint-url?sort= wysiwygScore |
webPagesScore | Sort the results by the webpage score of each domain. | Overall endpoint and only available for Ally for Web and WCM. | endpoint-url?sort= webPagesScore |
Note
Parameter values are case-sensitive, and only one sorting option can be used at a time.
By default, results are sorted in ascending order. If you want to set a different order, you can add the order parameter:
endpoint-url?sort=<Sort parameter value>&order=<Order value>
Where <Order value> can be: asc or desc
Example:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Filtering options
You can use filtering options to obtain smaller or reduced responses based on the selected criteria. If you need to add a filtering option, you must add the filtering parameter as described below:
Filter Parameters (without operator)
Filter parameter name | Description | Supported In |
allyEnabled | You can get the courses where Ally is active Value is true or false | Overall and Issues endpoints |
departmentId | Filter by the department ID | Overall and Issues endpoints |
departmentName | Filter by the department name. e.g. Engineering | Overall and Issues endpoints |
termId | Filter by the term ID | Overall and Issues endpoints |
termName | Filter by the term name. e.g. Summer | Overall and Issues endpoints |
courseId | Filter by the ID or a course. e.g. 123456 (this is usually a whole number) | Overall and Issues endpoints |
courseName | Filter by the name of a course. E.g. Chemistry 101 (courseCode is not valid) | Overall and Issues endpoints |
endpoint-url?<Filter Parameter>=<value>
Filter Parameters (with operator)
endpoint-url?<Filter Parameter>=<Operator>:<value>
Where:
<Filter Parameter>: Filtering parameter to get a smaller set of results. You can consult the supported parameters in the table below.
<Operator>: You must use an operator to filter, like equal, not equal.
<value>: Value used in the filter.
Filter parameter name | Field type | Supported operators | Description | Supported In |
allyEnabled | Boolean | eq, ne | You can get the courses where Ally is active. Value is true or false. | Overall and Issues endpoints |
courseName | String | eq, ne, co, nc, sw | Filter by the name of a course. E.g. Chemistry 101 (courseCode is not valid) | Overall and Issues endpoints |
courseId | String | eq, ne, co, nc, sw | Filter by the ID or a course. E.g. 123456 (this is usually a whole number) | Overall and Issues endpoints |
termId | String | eq, ne, co, nc, sw | Filter by the term ID. | Overall and Issues endpoints |
termName | String | eq, ne, co, nc, sw | Filter by the term name. e.g Summer | Overall and Issues endpoints |
overallScore | Number | eq, ne, le, lt, ge, gt | You can filter by an overall score. e.g Courses with a score equal to 90% | Overall endpoint and in all Ally solutions: LMS, websites, and WCM. |
filesScore | Number | eq, ne, le, lt, ge, gt | You can filter by the files score. e.g Courses with a files score equal to 90% | Overall endpoint and in all Ally solutions: LMS, websites, and WCM. |
wysiwygScore | Number | eq, ne, le, lt, ge, gt | You can filter by the WYSIWYG score. e.g Courses with a WYSIWYG score equal to 90% | Overall endpoint and only available for Ally for LMS. |
webPagesScore | Number | eq, ne, le, lt, ge, gt | You can filter by the score of a domain. e.g. Web pages with a score equal to 90%. | Overall endpoint and only available for Ally for Web or WCM. |
Note
Parameter values are case-sensitive.
Supported Operators
The following table contains the supported operators based on the field type:
Field type | Operator | Description |
String | eq | Is equal |
String | ne | Is not equal |
String | co | Contains keyword |
String | nc | Does not contains keyword |
String | sw | Starts with keyword |
Number | eq | Is equal |
Number | ne | Is not equal |
Number | le | Less than or equal |
Number | lt | Less than |
Number | ge | Greater than or equal |
Number | gt | Greater than |
Example:
The following example retrieves all the courses that contain the keyword "tests" in the course name:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Using multiple filters
You can combine the sorting and filtering options in the same endpoint URL by adding the "&" character between the two conditions. For example, let's say you want to retrieve all the courses that contain the keyword "test" in the course name where Ally is enabled, and that the overall score Is less than 90%. The URL would look like this:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
You can also use two filtering options. For example, let's say you need to obtain all the courses that have an overall score between 10% and 70%:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7