Clarity Web API

Documentation

Overview

The Clarity Web APIs are organized around REST. Our APIs have predictable, resource-oriented URLs and use HTTP response codes to indicate API errors. We use built-in HTTP features, such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. If you want to check the APIs in action, please go to test page.

Authentication and authorization

The Clarity Web APIs use the OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources. You should pass your credentials in the Authorization header in a get access token request. In exchange for these credentials, the Clarity Web APIs authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner. The access_token field in the get access token response contains a bearer token.

How to get an access token

Send a request to the token endpoint. The body of the request contains the following data:
  • grant_type: "password"
  • username: <the user's email>
  • password: <password>
HTTP request: 
POST https://awsclarity.commonlook.com/ClarityAPI/Token HTTP/1.1
Host: awsclarity.commonlook.com
Connection: keep-alive
Content-Length: 67
Accept: */*
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36
Content-Type: application/json
Referer: https://awsclarity.commonlook.com/ClarityAPI/
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,ar;q=0.8
grant_type=password&username=alice%40example.com&password=Password1!
HTTP response: 
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
Date: Tue, 13 Nov 2018 08:04:34 GMT
Content-Length: 711

{
"access_token":"kwOG3zCXh....",
"token_type":"bearer",
"expires_in":3599,
"userName":"alice@example.com",
".issued":"Tue, 13 Nov 2018 08:04:34 GMT",
".expires":"Tue, 13 Nov 2018 09:04:34 GMT"
}
Now that we have a bearer token, we can make an authenticated request to the API. This is done by setting the Authorization header in the request.
Note: All requests to Validation must use access_token.

Standards

The Clarity web API validate PDF files against Section 508, WCAG 2.0 AA, PDF/UA, and HHS standards, but You can validate your files against one or more standards only.

Standards List

In order to know all supported standards by Clarity web API, Send a request to the Standards endpoint.
HTTP request: 
GET https://awsclarity.commonlook.com/ClarityAPI/Standards HTTP/1.1
Host: awsclarity.commonlook.com
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest
Authorization: Bearer kwOG3zCXh....
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36
Referer: https://awsclarity.commonlook.com/ClarityAPI
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,ar;q=0.8
HTTP response: 
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 13 Nov 2018 08:14:49 GMT
Content-Length: 59

["STRUCTURAL","S508","WCAG2_0","PDF_UA_1","HHS","HHS_2018"]

Validation

The Clarity Web APIs validation process allows users to validate PDF files and get compliance reports. The process of Validation is divided into 3 steps
  • Request Validation.
  • Get Status.
  • Get Compliance Report.

Request Validation

To request validation, send a request to the Validation endpoint. The body of the request shall contain the following form-url-encoded data:
  • URL: "http://example.com/file.pdf"
  • Standards: (Optional) Array of standards against which you want your file to be validated
HTTP request: 
POST https://awsclarity.commonlook.com/ClarityAPI/api/Validation HTTP/1.1
Host: awsclarity.commonlook.com
Connection: keep-alive
Content-Length: 154
Accept: application/json, text/javascript, */*; q=0.01
Origin: https://awsclarity.commonlook.com
X-Requested-With: XMLHttpRequest
Authorization: Bearer kwOG3zCXh....
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36
Content-Type: application/json; charset=UTF-8
Referer: https://awsclarity.commonlook.com/ClarityAPI/
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,ar;q=0.8

{"URL":"http://example.com/file.pdf","Standards":["STRUCTURAL","S508"]}
HTTP response: 
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/10.0
Date: Tue, 13 Nov 2018 08:09:28 GMT
Content-Length: 2

24

Get Status

After requesting a PDF file validation, you may check the API for validation status. The response should be one of the following:
  • Requested (Your request has been queued and waiting for processing)
  • Processing (Validation engine is processing your request)
  • Completed (Your validation report is ready)
  • Failed - {Reason} (Validation failed, and you will get the reason of fail in the result)
To request the validation status send a request to the Validation endpoint with the id of the file for which you want check the status
HTTP request: 
GET https://awsclarity.commonlook.com/ClarityAPI/api/validation?id=24 HTTP/1.1
Host: awsclarity.commonlook.com
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest
Authorization: Bearer kwOG3zCXh....
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36
Referer: https://awsclarity.commonlook.com/ClarityAPI
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,ar;q=0.8
HTTP response: 
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 13 Nov 2018 08:14:49 GMT
Content-Length: 11

"Completed"

Get Compliance Report

To request a validation report, send a request to the Validation endpoint with the id of the file for which you want check the status
HTTP request: 
GET https://awsclarity.commonlook.com/ClarityAPI/api/Validation/html?id=24 HTTP/1.1
Host: awsclarity.commonlook.com
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest
Authorization: Bearer kwOG3zCXh....
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36
Referer: https://awsclarity.commonlook.com/ClarityAPI/
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,ar;q=0.8
HTTP response: 
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 3719951
Content-Type: text/html
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 13 Nov 2018 08:17:21 GMT

 <!DOCTYPE html><html lang="en"><head><meta charset="utf-8" /><title>CommonLook Clarity</title>...

Webhooks

A Webhook (also called a web callback or HTTP push API) is a way for an application to provide other applications with real-time information. Webhooks deliver data to other applications as they happen, meaning you get the data immediately (unlike typical APIs where you would need to poll for data very frequently in order to get it real-time.)
Clarity Web APIs support Webhooks for the "verification complete event." Once your PDF file has been verified, Clarity Web APIs will callback with the status and Id of the completed file.

Webhook Subscription

To subscribe to a Webhook you should provide a URL to which callbacks are posted. This means that you also need to set up a URL in your application that is accessible to the public.
To subscribe to a Webhooks, send a request to the Webhook endpoint. The body of the request shall contains the following data:
  • URL: "http://myapp/webhooksreciever"
  • Secret Key: must be between 32 and 64 characters long
Note: Your URL should return echo query parameter as plain text in the response, otherwise, use NoEcho query parameter to ignore validation
HTTP request: 
GET https://awsclarity.commonlook.com/ClarityAPI/api/webhooks/registrations HTTP/1.1 
Host: awsclarity.commonlook.com
Connection: keep-alive
Content-Length: 103
Accept: application/json, text/javascript, */*; q=0.01
Origin: https://awsclarity.commonlook.com
X-Requested-With: XMLHttpRequest
Authorization: Bearer kwOG3zCXh....
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36
Content-Type: application/json; charset=UTF-8
Referer: https://awsclarity.commonlook.com/ClarityAPI/
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,ar;q=0.8

{"WebHookUri":"http://myapp/webhooksreciever?NoEcho","Secret":"12345678911234567891123456789141"}
HTTP response: 
HTTP/1.1 201 Created
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 3719951
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 13 Nov 2018 08:17:21 GMT
Content-Length: 224

{"Id":"f370f63eab074cc5a328390927c47855","WebHookUri":"http://myapp/webhooksreciever?NoEcho","Secret":"12345678911234567891123456789141","Description":null,"IsPaused":false,"Filters":["*"],"Headers":{},"Properties":{}}

Receiving Webhooks

Once your file has been validated, you will get a POST request with your file's Id and whether verification has completed or failed.
{
  "Id": "735224c42d3e4c53b5c29b5ae1739f00",
  "Attempt": 1,
  "Properties": {},
  "Notifications": [
    {
      "Action": "fileVerificationComplete",
      "FileId": 24,
      "Status": "Completed"
    }
  ]
}
Note: For validation, you will get your secret key in the request header hashed using SHA256.Ex:ms-signature=sha256%3dB1FB51555524E8EE2B2CDE81FC929A0F98B19605BD8039715B0D50E994A670A1