API Documentation

INPUTS & ORDERS

Summary Upload a source file to be used in an order.
URL /fileUpload
Detailed Description Use this operation to send files to be transcribed.

You must specify the filename and content type for the file. Upon successful completion, the JSON response will include the ID for the file that will be referenced in the webhook notification that returns the completed transcript.

There are two ways to transfer the media:

  • Upload it directly. To do so, send the media data as the body of the post. Set the Content-Type header appropriately and use the Content-Disposition header to specify the filename for the media.
  • Have us retrieve the data from a server of your choice. To do so, send a JSON entity, as shown in the “sample request entity” section below.
    This will give us the URL and, optionally, the filename and content-type for the  The URL must be publicly accessible.

We also allow users of the API to specify if transcription should be done using our Verbatim option and to specify if Timestamps should be included. Timestamps are free when placed via the FFT API, but you still need to specify that timestamps should be included.

You can also optionally specify the desired file formats for the finished transcription files. We support these formats:

MS Word .docx
JSON .json
Text .txt
PDF .pdf
SRT .srt

Specifying these formats in the order request is optional – internally we produce the transcripts in a canonical format and can then export them on-the-fly as any of the above formats. However, if you specify the formats in the order request, then our team can make sure the produced transcripts are optimized for your desired formats, so we recommend doing so if the desired formats are known. By default, we optimize for Microsoft Word.

PO or project numbers can be passed via the API request for associating with the appropriate project upon invoicing.

Request Headers Content-Type – if the media is being directly uploaded, this should be the content type for the media.
Request Body The binary data contents of the media file JSON entity specifying a location from which the media can be retrieved.
Parameters
Name Type Description
apikey String The API Key provided by TOPS
job String Job Name / Number
contact String Email address of the contact person
turnaround Integer Turnaround time (in hours). 0 = rush
speakers Integer Number of speakers for focus Group/IDI
timestamping Integer Time stamping requirement (in seconds).
No value = No Time stamp required
language String Language. No value provided = English
format String Format
(Notes, Edited, Standard, Excel, Respondent ID).
No value = Verbatim
File String The url of an external service to download the file.
(Not required if file contents are passed in the body
of the request)
Path String The name and path to save the file in our system. For
users that utilize our File Management platform, you
can specify a subfolder to place the file into by using
the format “folder/myfilename.mp3”. If no folder is
specified (such as myfilename.mp3), the file will be
placed in the root directory of your client folder.
Response 200 Success
400 or 500 error as detailed below.
Response Body Code: 200

Content-Type: application/json

Content: {“file_uploaded”: “the id of your file”}

Error Codes Code: 400 BAD REQUEST

Content-Type: application/json

Content: {error: “Missing/invalid parameters”}

 

Code: 401 UNAUTHORIZED

Content-Type: application/json

Content: {error: “Invalid API Key”}

 

Code: 405 METHOD NOT ALLOWED

Content-Type: application/json

Content: {error: “Operation not supported”}

 

Code: 409 CONFLICT

Content-Type: application/json

Content: {error: “A file with the same name already exists”}


Code:
500 INTERNAL SERVER ERROR

Content-Type: application/json

Content: {error: “The server encountered an error. Please try
again”}

Code: 502 BAD GATEWAY

Content-Type: application/json

Content: {error: “The file could not be retrieved from specified
URL”}

Sample request for transcription Below is an example of the JSON request entity.

{

“apikey”: “123456”,

“job”: “PO54321”,

“contact”: “myemail@company.com”,

“turnaround”: 48,

“speakers”: 4,

“timestamping”: 300,

“language”: “English”,

“format”: “Verbatim”,

“File”: “https://publicurlofyourfile.com”,

“Path”: “folder/myfilename.mp3”

}

Simple to set up, triple secure and guaranteed accuracy, our API clients enjoy the highest service level.
The most efficient speech to text process around, we have dedicated API corporate solutions support that fits your budget and timeline.
Corporate solution API clients also enjoy the highest customization transcripts, volume based rates and monthly invoices.