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: 

MethodURLHTTP Request TypeDescription
Overallhttps://[region]/api/v2/clients/[Ally Client ID]/reports/overallGetBy 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.
Issueshttps://[region]/api/v2/clients/[Ally Client ID]/reports/issuesGetBy 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.

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:

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:

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:

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 valueDescriptionSupported inExample
courseName Sort by course name, e.g. Chemistry 101
(courseCode is not valid)
Overall and Issues endpoints endpoint-url?sort=courseName 
courseIdSort 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 
termNameSort by term Name. e.g. Summer Overall and Issues endpoints endpoint-url?sort=termName 
overallScoreSort by the overall accessibility score of each course.   Overall endpoint only.endpoint-url?sort=overallScore 
filesScoreSort the results by the file score of each course. Overall endpoint only.endpoint-url?sort=filesScore 
wysiwygScoreSort the results by the WYSIWYG score of each course. Overall endpoint and only available for Ally for LMS. endpoint-url?sort= wysiwygScore 
webPagesScoreSort the results by the webpage score of each domain. Overall endpoint and only available for Ally for Web and WCM. endpoint-url?sort= webPagesScore 

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 IDOverall and Issues endpoints 
departmentName Filter by the department name. e.g. Engineering Overall and Issues endpoints 
termIdFilter by the term IDOverall and Issues endpoints 
termName Filter by the term name. e.g. Summer Overall and Issues endpoints 
courseIdFilter 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 
allyEnabledBooleaneq, neYou can get the courses where Ally is active. 
Value is true or false. 
Overall and Issues endpoints 
courseNameStringeq, ne, co, nc, sw Filter by the name of a course. E.g. Chemistry 101
(courseCode is not valid)
Overall and Issues endpoints 
courseIdStringeq, ne, co, nc, sw Filter by the ID or a course. E.g. 123456
(this is usually a whole number) 
Overall and Issues endpoints 
termIdStringeq, ne, co, nc, sw Filter by the term ID. Overall and Issues endpoints 
termNameStringeq, ne, co, nc, sw Filter by the term name. e.g Summer Overall and Issues endpoints 
overallScoreNumbereq, 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.
filesScoreNumbereq, 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.
wysiwygScoreNumbereq, 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. 
webPagesScoreNumbereq, 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. 

Parameter values are case-sensitive.

Supported Operators

The following table contains the supported operators based on the field type: 

Field typeOperatorDescription
StringeqIs equal 
StringneIs not equal 
StringcoContains keyword 
StringncDoes not contains keyword 
StringswStarts with keyword 
NumbereqIs equal 
NumberneIs not equal 
NumberleLess than or equal 
NumberltLess than 
NumbergeGreater than or equal 
NumbergtGreater 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