This document will walk you through how to use the RESTful API for the Speechmatics SaaS. This document will show you

  • How to authenticate and connect to the Speechmatics SaaS endpoint
  • How to successfully submit a file for processing
  • How to check on the status of any transcription job
  • How to retrieve a transcript in the format of your choice

This section shows:

  • Supported languages and file formats
  • How to use the Authorization Token
  • How to connect to a valid Speechmatics endpoint
  • Rate limits

Supported languages

The Speechmatics SaaS supports the following languages. Your ability to use any or all of the languages will depend on what languages you are contracted to use.

LanguageLanguage Code

Please note any languages outside this list are not explicitly supported. Only one language can be processed within each request. Each language above has a two-letter ISO639-1 code that must be provided for any transcription request.

Supported file types

The Speechmatics SaaS supports the following file types for transcription:

  • aac
  • amr
  • flac
  • m4a
  • mp3
  • mp4
  • mpeg
  • ogg
  • wav

The list above is exhaustive - any file format outside the list above is explicitly not supported.

File Size Limits

The supported size limit for jobs is 2 hours of audio or 1 GB file size. Any larger or longer files may be rejected.

Data Retention Limits

Audio files, transcripts, and configuration data are stored in the Speechmatics SaaS for 7 days. Any request to retrieve a transcript or file more than 7 days after it was processed will receive a HTTP 404 error message and a status of expired.

You can delete audio or transcripts in advance of this 7 day period - how to do so is documented in the How-To Guide

Connecting to the Speechmatics SaaS

This section talks through the Pre-Requisites to authenticate to the Speechmatics SaaS

Authorization Token

Speechmatics Support will provide you a unique Authorization Token. This must be used with any interaction with the Speechmatics SaaS to authenticate to the service. Any interaction without this token will receive a HTTP 401 - Unauthorized response.

The Authorization Token must be passed in the header of any request to the Speechmatics SaaS. The Token itself conforms to OAuth2 protocols.

It is your responsibility to store the Authorization Token securely and ensure it is not mishandled. It is recommended that you store and provide access to the Token on the principle of least privilege. If you believe that your Token has been compromised, please contact Speechmatics Support.

Trial tokens

If you are using the trial Speechmatics endpoint, please note your authorization token may be time limited. If you try and use the token after the trial period has expired, you will receive a HTTP 401 - Unauthorized response.

Supported endpoints

Below are the supported endpoints.You should use the hostname for the region you are contracted to use:

  • EU region: asr.api.speechmatics.com
  • US region: us.asr.api.speechmatics.com
  • Trial: trial.asr.api.speechmatics.com

If you want to use a different region please contact sales@speechmatics.com. If you try to use a hostname for a region you are not contracted to use, that job will be unsuccessful

IP whitelisting (for notifications)

If you want to receive notifications from the Speechmatics SaaS, you will need to whitelist the following egress IP addresses. You should only whitelist the IP addresses from the geo region you are contracted to use

The list is below:

IP AddressRegion

Rate limiting

Speechmatics places limits on the SaaS to prevent any one user from monopolising the service. This takes the form of rate limiting. If you either submit jobs too quickly or try to poll the status of submitted jobs to frequently, you will receive a HTTP 429 - Rate Limited error response. In detail:

  • Submission of files is limited to a maximum of 2 jobs per second with a maximum of 100 jobs in progress at any one time.
  • Polling for the status of submitted jobs is limited to a maximum of 20 queries per second (across all jobs).

Speechmatics reserve the right to change the rate limits at any time in order to ensure continuity of service for all customers of the SaaS.

If for your use case you believe you need increased limits please contact support@speechmatics.com


Please note: all timestamps from the Speechmatics SaaS are in ISO 8601 format, and use Coordinated Universal Time (UTC).

A note on tools

Code samples in this guide use curl for making HTTP requests to the API, and the jq tool to parse and display JSON responses.

API Specification

The API uses a standardised authentication method, with a wide range of supported output formats and has a structured JSON configuration that is easier to extend in the future.

For the full API specification please refer to the Jobs API Reference section.