Guide

This page provides a comprehensive guide for setting up a connection to the SensusAccess API.

Table of Contents

1. Getting started
2. Overview
3. Prerequisites
4. General Structure
5. Supported API request
   1. Post
   2. GetStatus
   3. GetJobStatus
   4. GetResult
   5. Delete
   6. Other request methods
6. General workflow
7. Demo API call and source code
8. Worflow details
   1. Accessibility
   2. Mp3
   3. Ebook
   4. Braille
   5. Daisy
   6. Translation
9. Example workflows

Getting started

In order to use the SensusAccess API please register first for an account. Once your registration is complete Sensus will review and activate the account for using the API. The account status can be checked after logging in to the SensusAccess API account. A User ID and API key will also be associated with the account and will be used to authenticate the API requests. Please make sure these are not disclosed to unauthorized users.

Overview

For the purpose of this document the name “endpoint(s)” will be used when providing general information about all endpoints. Information relevant to each component will be provided by referencing their names. The supported conversions of the API are Braille, MP3, Daisy, Ebook and Accessibility. They are collectively referred to in this document as "workflow(s)" or "conversion workflow(s)". References to parameters that must be supplied at runtime are marked by using the name or description of the parameter inside curly brackets, such as: "{your job ID}". The main path for the API is https://api.sensusaccess.com/job.

Prerequisites

In order to use the API, the account must be registered and activated.

The authentication is done using a token based authentication scheme, more specifically the HAWK authentication scheme. Each POST request to the API must be accompanied by a HAWK Authorization header. Third party libraries exist in most major programming languages that can create the HAWK Authorization header automatically. The header is created using the user id, api key fields and the sha256 encryption algorithm. More advanced parameters for HAWK should be generated by the specific libraries.

In order to make sure that the endpoints are called correctly and that the authentication is set up accordingly it is recommended to use Postman or similar software for creating test requests.

To make sure the account is registered successfully for using the API it is possible to call the following endpoint using a GET method and the HAWK authorization header: https://api.sensusaccess.com/job/GetMessage. It will return the account user name if successful or "Anonymous" otherwise.

General Structure

The API supports the same conversion workflows as SensusAccess, therefore its structure is made to reflect this similarity. The following job POSTing endpoints are available:

• Accessibility
• Mp3
• Ebook
• Braille
• Daisy
• Translation

More details regarding the creation of each conversion request is provided in their respective sections below.

Supported API requests

Please note that only the POST requests require using the HAWK authorization header.

Post

Request url: https://api.sensusaccess.com/job/{Workflow name}

Http method: POST

Requires authorization header: Yes

The POST request contains all the necessary parameters for starting a job in the API, including the file to be converted. The POST content type is "multipart/form-data". Each request returns a unique ID used to track and retrieve the job. Please store this ID as there is no other way to retrieve the converted file afterwards. The job ID is in the form of: “ca427b75-bb66-e511-91f0-1c6f65d84158”.

This ID will be used in the next three methods as an URL encoded parameter following the endpoint path.

GetStatus

Request url: https://api.sensusaccess.com/job/GetStatus?Id={your job ID}

Http method: GET

Requires authorization header: No

This method will return a status code for the respective job. Their values and interpretation are as follows:

Code	Meaning	Description
1	Done	The job is finished and the result can be retrieved
2	Cancelled	The job has been cancelled by the user
3	Started	The job has been started
4	Queued	The job is queued for starting
5	Processing	The job is being processed
6	Created	The job is created but not started
-1	Error	An internal error prevented the job from completing successfully

GetJobStatus

Request url: https://api.sensusaccess.com/job/GetJobStatus?Id={your job ID}

Http method: GET

Requires authorization header: No

This method will return JobID, Status, ErrorCode, ErrorMessage for the respective job. This API is an alternate to the GetStatus and the status code interpretation are exactly as above in the GetStatus. We recommend using GetJobStatus over GetStatus because this endpoint gives you Status along with an error message if the status code is -1.

   
        {
        "JobID": "67ca0072-db8f-ec11-8e57-9eb6d0c418a3",
        "JobStatus": 3,
        "ErrorCode": null,
        "ErrorMessage": null
        }   
    

You can download the complete error codes at Download error codes.

GetResult

Request url: https://api.sensusaccess.com/job/GetResult?Id={your job ID}

Http method: GET

Requires authorization header: No

The GetResult request will return the converted file. The result file will have the same name as the input file. Please make sure that the GetStatus request returns the value 1 before attempting to return the file result.

Delete

Request URL: https://api.sensusaccess.com/job/Delete?Id={your job ID}

HTTP method: DELETE

Requires authorization header: Yes

Please note that all jobs are stored on the SensusAccess servers for 7 days. However, it is also possible to issue a delete request after the job is finished. Please note that the job cannot be recovered afterwards. It is recommended to use the delete request when the job status returns an error message in order to not run into unexpected conflicts when retrying the same conversion.

Other request methods

Other GET request methods exist to aid the creation of the POST request. They provide valid lists of input parameter values, such as supported languages or output formats. Further details are provided when presenting each job type.

General workflow

The workflow described below should be followed for all conversion types (Accessibility, Mp3, Ebook, Braille, Daisy).

1. POST the authenticated job request to the desired endpoint
2. Store the ID of the job
3. Repeat: Call GetStatus with the saved job ID in regular time intervals. Repeat until the job status value equals is either 1, 2 or -1, or some predefined timeout. There is also an alternate API GetJobStatus which gives you an object with JobID, Status, ErrorCode, ErrorMessage. We recommend you use GetJobStatus over GetStatus because the purpose of the GetStatus is to support the older clients.
4. Depending on job status from step 3.
   1. If job status = 1. Call GetResult with the saved job ID to retrieve the converted file.
   2. If job status = 2. Notify the user that the job has been cancelled.
   3. If job status = -1. Notify the user that a conversion error has occurred.
5. Delete the job.
   
6. End of workflow.
   Note: If you POST the job to the API with the optional parameter DeliveryMethod=Email and DeliveryEmail=some email address, don't delete the job because if you delete the job the API might be unable to send the email. This could be the case that your application could delete the before email scheduler picket the job to send in the email. By POSTing the job to API with DeliveryMethod=Email, you could also avoid the above other steps except for the first one because the API will be responsible to deliver the converted result to a given email address once the conversion is completed. But it depends on your implementations.

Example API call and source code

The demo application is a console application developed in C# and Visual Studio (2015 or higher). The application demonstrates how to post a job to the API, how to get the status of the posted job, how to fetch the result and how to delete the job from the server after conversion. To run the demo application, you are required to have a UserId and an API key. The sample code is well documented and it's clearly mentioned where to put UserId and API Key in the code. There are two dependencies namely Thinktecture.IdentityModel.Hawk and Newtonsoft.Json which are available at nuget. You can download the source code of the demo application at Download source code

Workflow details

The specific details for constructing the POST requests for each workflow is presented here. Unless specified otherwise both the string and numeric representations for the parameters are valid. Where defined it is recommended to use the provided GET link in order to see a list of supported parameter values.

Accessibility

Mp3

Ebook

Braille

Daisy

Translation

The FileContent, SourceLanguage, TargetLanguage and SiteId are the required fields for the Translation converion type.

Example workflows

The following table presents some typical workflows associated with each endpoint.