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. GetResult
    4. Delete
    5. 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
  9. Example workflows

Gettting 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

Please use this link for a better overview of the current API endpoints

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, Audio, 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 is 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: http://api.sensusaccess.com/job.

Prerequisites

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

The authentication is done using a toke 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 of that the endpoints are called correctly and that the authentication is setup accordingly it is reccommended 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: http://api.sensusaccess.com/job/GetMessage. It will return the account user name if successful or "Anonymous" otherwise.

General Structure

The main endpoint for using the API resides under the following path: http://api.sensusaccess.com/job/

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:

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

Supported API requests

The exact methods can be viewed in the API overview. Please note that only the POST requests require using the HAWK authorization header.

Post

Request url: http://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: http://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 is 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 procesed
6 Created The job is created but not started
-1 Error An internal error prevented the job from completing successfully

GetResult

Request url: http://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: http://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.
  4. Depending on jobstatus from step 3.
    1. If jobstatus = 1. Call GetResult with the saved job ID to retrieve the converted file.
    2. If jobstatus = 2. Notify the user that the job has been cancelled.
    3. If jobstatus = -1. Notify the user that a conversion error has occured.
  5. Delete the job.
  6. End of workflow.

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 its 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 nummeric representations for the parameters are valid. Where defined it is reccommended to use the provided GET link in order to see a list of supported paramater values.

Accessibility

Parameter Name

Valid Values

Notes

FileContent

The input document can be in any file format supported by SensusAccess for this specific workflow

TargetDocumentFormat

OFF_MSWord

OFF_MSExcel

OFF_RTF

OFF_XML

OFF_PDF

OFF_PDFA

OFF_Text

OFF_CSV

OFF_HTML

OFF_TIFF

OFF_JPG

OFF_J2K

OFF_DOCX

OFF_XLSX

OFF_JBIG2

OFF_ALTO

OFF_EPUB

OFF_UTF8

OFF_UTF16

GET Link: api.sensusaccess.com/job/GetAccessibilityOutputOptions

Mp3

Parameter Name

Valid Values

Notes

FileContent

The input document can be in any file format supported by SensusAccess for this specific workflow

Language

enUS

enGB

bgBG

zhCN

zhHK

zhTW

czCZ

daDK

nlNL

fiFI

frFR

deDE

elGR

klGL

huHU

isIS

jaJP

koKR

itIT

ltLT

nbNO

plPL

ptPT

roRO

ruRU

skSK

slSI

esES

esCO

svSE

cyGB

enUS - English United States.

enGB - English Great Britain

bgBG - Bulgarian

zhCN - Chinese Mandarin China

zhHK - Chinese Cantonese Hong Kong

zhTW - Chinese Taiwanese Taiwan

czCZ - Czech Female

daDK - Danish (supports both genders)

nlNL - Dutch (supports both genders)

fiFI - Finnish

frFR - French

deDE - German

elGR - Greek

klGL - Greenlandic

huHU - Hungarian (supports both genders)

isIS - Icelandic (supports both genders)

jaJP - Japanese

koKR - Korean

itIT - Italian

ltLT - Lithuanian (supports both genders and both age groups)

nbNO - Norwegian

plPL - Polish

ptPT - Portuguese

roRO - Romanian

ruRU - Russian

skSK - Slovak Female

slSI - Slovenian

esES - Spanish Castilian

esCO - Spanish Latin America

svSE - Swedish

cyGB - Welsh Great Britain (supports both genders)

GET Link: api.sensusaccess.com/job/GetMp3Languages

SpeedOptions

Fastest = 10

Faster = 7

Fast = 3

Normal = 0

Slow = -3

Slower= -7

Slowest = -10

Any values between -10 (the slowest) and 10 (the fastest) can be used. These values are indicative of the equivalet SensusAccess configuration.

VoicePropriety

Male = 1

Female = 2

Older = 3

Younger = 4

None = 0

Please note that not all voices support these proprieties. Certain voices support both genders. Only Lithuanian (ltLT) supports both genders and both ages.

If more voice proprieties are desired for the same conversion it is possible to use a list of semicolon (;) separated values.

GET link: api.sensusaccess.com/job/GetMp3VoiceProprieties

Ebook

Parameter Name

Valid Values

Notes

FileContent

The input document can be in any file format supported by SensusAccess for this specific workflow

format

mobi = 1

epub = 2

txt = 3

rtf = 4

docx = 5

html = 7

chm = 8

epub3wmo = 16

The output format possibilities.

GET link: api.sensusaccess.com/job/GetEbookFormats

basefontsize

LARGE = 16

XLARGE = 24

HUGE = 40

(Optional) Predefined font sizes. If not selected the original document font size is preserved.

Braille

Parameter Name

Valid Values

Notes

FileContent

The input document can be in any file format supported by SensusAccess for this specific workflow

BrailleDotsFormats

sixdot = 6

eightdot = 8

GET link: api.sensusaccess.com/job/GetBrailleDotsFormats

Language

enUS

enGB

bgBG

daDK

frFR

huHU

isIS

itIT

nbNO

plPL

ptPT

roRO

slSI

esES

enUEB

enUS - English USA. Contractions: grade1 and grade2. Braille format: 6 dot.

enGB - English Great Britain. Contractions: grade1 and grade2. Braille format: 6 and 8 dot.

bgBG - Bulgarian. Contraction: grade1. Braille format: 6 dot.

daDK - Danish. Contractions: small, large and full. Braille format: 6 and 8 dot.

frFR - French. Contraction: grade1. Braille format: 6 dot.

huHU - Hungarian. Contraction: grade1. Braille format: 6 dot.

isIS - Icelandic. Contraction: grade1. Braille format: 6 dot.

itIT - Italian. Contraction: grade1. Braille format: 6 dot.

nbNO - Norwegian(bokmal). Contraction: level 0, 1 and 2. Braille format: 6 dot.

plPL - Polish. Contraction: grade1. Braille format: 6 dot.

ptPT - Protuguese. Contraction: grade1. Braille format: 6 dot.

roRO - Romanian. Contraction: grade1. Braille format: 6 dot.

slSI - Slovenian. Contraction: grade1. Braille format: 6 dot.

esES - Spanish. Contraction: grade1. Braille format: 6 dot.

enUEB - Unified English Braille. Contraction: grade1 and grade2. Braille format: 6 dot. Output format: Unicode, Pef, NACB

GET link: api.sensusaccess.com/job/GetBrailleLanguages

Contraction

full = 1

small = 2

large = 3

grade1 = 4

grade2 = 5

level0 = 6

level1 = 7

level2 = 8

Supported by the language(s): daDK

Supported by the language(s): daDK

Supported by the language(s): daDK

Supported by the language(s): (all languages except daDK and nbNO)

Supported by the language(s): enUS, enGB

Supported by the language(s): nbNO

Supported by the language(s): nbNO

Supported by the language(s): nbNO

GET link: api.sensusaccess.com/job/GetBrailleContractions

OutputFormat

None = 0

OctoBraille = 1

Unicode = 2

Pef = 3

NACB = 4

Pef stands for Portable Embosser Format

NACB stands for North American Computer Braille

GET link: api.sensusaccess.com/job/GetBrailleOutputFormats

ConversionPath

texttobraille = 0

brailletotext = 1

(Optional) Default is texttobraille = 0

CharactersPerLine

number: 0 = no pagination and greater than (>) 10 for a valid pagination

Default is 0

LinesPerPage

number: 0 = no pagination and greater than (>) 2 for a valid pagination

Default is 0

PageNumbering

none = 0

right = 1

left = 2

(Optional) Default is none = 0.

Daisy

Parameter Name

Valid Values

Notes

FileContent

The input document can be in any file format supported by SensusAccess for this specific workflow

DaisyOutput

TalkingBook = 1,

Epub3WMO = 2 (deprecated: Please use the Ebook endpoint for this format)

GET link: api.sensusaccess.com/job/GetDaisyOutputs

Example workflows

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

Workflow Name Input Parameters Expected Output
Accessibility workflows
MS Document to text TargetDocumentFormat: OFF_TXT
FileContent: A doc/docx/rtf file
A txt file with the same name as the input file, containing only the text from the original document
MS Presentation to pdf TargetDocumentFormat: OFF_PDF
FileContent: A ppt/pptx file
A pdf file with the same name as the input file, containing only the text from the original document
html to text TargetDocumentFormat: OFF_TXT
FileContent: A html file
A txt file with the same name as the input file
image to text TargetDocumentFormat: OFF_TXT
FileContent: A png/jpg/jpeg/tiff file
A .txt file with the same name as the input file
pdf to docx TargetDocumentFormat: OFF_DOCX
FileContent: A pdf file.
A docx file with the same name as the input file
scanned pdf to tagged pdf TargetDocumentFormat: OFF_PDF
FileContent: A pdf file.
A pdf file with the same name as the input file
Mp3 workflows
text to mp3 Language: (Check valid parameters for Mp3)
SpeedOptions: (Check valid parameters for Mp3)
FileContent: A txt file
A mp3 file with the same name as the input file
HTML to mp3 Language: (Check valid parameters for Mp3)
SpeedOptions: (Check valid parameters for Mp3)
FileContent: A html file
A mp3 file with the same name as the input file
pdf/image to mp3 Language: (Check valid parameters for Mp3)
SpeedOptions: (Check valid parameters for Mp3)
FileContent: A pdf/png/jpeg/jpg/tiff file
A mp3 file with the same name as the input file
MS Document to mp3 Language: (Check valid parameters for Mp3)
SpeedOptions: (Check valid parameters for Mp3)
FileContent: A doc/docx/rtf file
A mp3 file with the same name as the input file
E-book workflows
pdf to epub2 EbookFormat: epub
FileContent: A pdf file
A epub file with the same name as the input file
image to epub2 EbookFormat: epub
FileContent: A png/jpeg/jpg/tiff file
A epub file with the same name as the input file
pdf to mobi EbookFormat: mobi
FileContent: A pdf file
A mobi file with the same name as the input file
html to epub2 EbookFormat: epub
FileContent: A html file
A epub file with the same name as the input file
docx to epub3 with media overlay (WMO) EbookFormat: Epub3WMO
FileContent: A docx file
A epub file with the same name as the input file
pdf to epub3 WMO EbookFormat: Epub3WMO
FileContent: A pdf file
A epub file with the same name as the input file
image to epub3 WMO EbookFormat: Epub3WMO
FileContent: A png/jpeg/jpg/tiff file
A epub file with the same name as the input file
Braille workflows
text to braille BrailleFormat: (Check valid parameters for Braille)
Language: (Check valid parameters for Braille)
Contraction: (Check valid parameters for Braille)
OutputFormat: None
ConversionPath: texttobraille
LinesPerPage: 0
CharactersPerLine: 0
FileContent: A txt file
PageNumbering: None
A txt file with the same name as the input file containing the desired braille format and contraction
MS Presentation to braille BrailleFormat: (Check valid parameters for Braille)
Language: (Check valid parameters for Braille)
Contraction: (Check valid parameters for Braille)
OutputFormat: None
ConversionPath: texttobraille
LinesPerPage: 0
CharactersPerLine: 0
FileContent: A ppt/pptx file
PageNumbering: None
A txt file with the same name as the input file containing the desired braille format and contraction
image to braille BrailleFormat: (Check valid parameters for Braille)
Language: (Check valid parameters for Braille)
Contraction: (Check valid parameters for Braille)
OutputFormat: None
ConversionPath: texttobraille
LinesPerPage: 0
CharactersPerLine: 0
FileContent: A png/jpg/jpeg/tiff file
PageNumbering: None
A txt file with the same name as the input file containing the desired braille format and contraction
pdf to braille BrailleFormat: (Check valid parameters for Braille)
Language: (Check valid parameters for Braille)
Contraction: (Check valid parameters for Braille)
OutputFormat: None
ConversionPath: texttobraille
LinesPerPage: 0
CharactersPerLine: 0
FileContent: A pdf file
PageNumbering: None
A txt file with the same name as the input file containing the desired braille format and contraction
docx to braille BrailleFormat: (Check valid parameters for Braille)
Language: (Check valid parameters for Braille)
Contraction: (Check valid parameters for Braille)
OutputFormat: None
ConversionPath: texttobraille
LinesPerPage: 0
CharactersPerLine: 0
FileContent: A docx file
PageNumbering: None
A txt file with the same name as the input file containing the desired braille format and contraction
html to braille BrailleFormat: (Check valid parameters for Braille)
Language: (Check valid parameters for Braille)
Contraction: (Check valid parameters for Braille)
OutputFormat: None
ConversionPath: texttobraille
LinesPerPage: 0
CharactersPerLine: 0
FileContent: A html file
PageNumbering: None
A txt file with the same name as the input file containing the desired braille format and contraction
Daisy workflows
docx to daisy talking book DaisyOutput: TalkingBook
FileContent: A docx file
A zip archive with the same name as the input file containing the daisy talking book
pdf to daisy talking book DaisyOutput: TalkingBook
FileContent: A pdf file
A zip archive with the same name as the input file containing the daisy talking book
image to daisy talking book DaisyOutput: TalkingBook
FileContent: A png/jpg/jpeg/tiff file
A zip archive with the same name as the input file containing the daisy talking book