About the Voice API Reference

The Voice API reference contains details about API request and response parameters. We also provide information about status codes. We divide Voice API reference information into these sections:

For product information about Voice, refer to the Product:Voice page.

Voice API Endpoints

The Voice API allows you to send an OTP using text-to-speech (TTS).

Send a Voice Message Containing an OTP

https://cpaas.mittoapi.com/2fa/send

POST – send a request for an OTP to be sent to a particular number.

Retrieve Usage Records

https://cpaas.mittoapi.com/2fa/usage/records

GET – send a request to retrieve usage records.

Send a Voice Message Containing an OTP

You send a voice message with an OTP by making a POST request to:

https://cpaas.mittoapi.com/2fa/send

Request Parameters for Sending a Voice Message

Parameter Name Data Type Required Description
service string yes The name of your service. For 2FA it will be 2FA.
from string yes The phone number that is making the call, or sending the SMS containing the verification code.
to string yes The destination phone number to send the OTP message containing the verification code.
body string yes The content of the OTP message. Use {code} as a placeholder for the location of the verification code in your SMS content. This {code} will be replaced automatically with a random code generated by the system.
channel string yes You must set the channel to call.
accountSid string yes The OTP message will be sent on behalf of the accountSid you provide.
voice string no If you choose to send a voice message, you use this parameter with the language parameter. You specify whether you want a male or female voice. Choices for this parameter are:

  • man
  • woman

Be sure a language is available with the voice gender you choose when you pick your language. For a list of languages and voice options, see the Available Voices for TTS section. NOTE: This feature is available as a separately purchased add-on. If you only bought SMS capabilities you will not be able to use this.
language string no If you choose to send a voice message, you would use this parameter to provide the Text-to-Speech (TTS) language tag for speaking the OTP message over the call channel. For a list of languages, see the Available Voices for TTS section. NOTE: This feature is available as a separately purchased add-on. If you only bought SMS capabilities you will not be able to use this.

Available Voices for TTS

NOTE:

This feature is available as a separately purchased add-on. If you only bought SMS capabilities you will not be able to use this.

If you choose to send an OTP using voice, it’s done with text-to-speech. Language codes are case sensitive. Use the language code with the language parameter and man or woman for the voice parameter. We recommend that you check your messages to make sure they sound the way you want.

Language Language Code Gender
Arabic arb woman
Chinese, Mandarin cmn-CN woman
Danish da-DK woman, man
Dutch nl-NL woman, man
English, Australian en-AU woman, man
English, British en-GB woman, man
English, Indian en-IN woman
English, US en-US woman, man
English, Welsh en-GB-WLS man
French fr-FR woman, man
French, Canadian fr-CA woman
Hindi hi-IN woman
German de-DE woman, man
Icelandic is-IS woman, man
Italian it-IT woman, man
Japanese ja-JP woman, man
Korean ko-KR woman
Norwegian nb-NO woman
Polish pl-PL woman, man
Portuguese, Brazilian pt-BR woman, man
Portuguese, European pt-PT woman, man
Romanian ro-RO woman
Russian ru-RU woman, man
Spanish, European es-ES woman, man
Spanish, Mexican es-US woman
US Spanish es-US woman, man
Swedish sv-SE woman
Turkish tr-TR woman
Welsh cy-GB woman

Response Parameters for Sending a Voice Message

When you send an OTP, the response returned includes details about whether your request was successful and the unique OTP request identifier, which you can use with the other API endpoints to collect details about the request.

Response Description
code Sub error code for the request.
message Message for describing a sub error code.
requestID The unique OTP request identifier for the OTP request.

Retrieve Usage Records

You can retrieve details about the voice messages you send by making a GET request to:
https://cpaas.mittoapi.com/2fa/usage/records

Request Parameters for Usage Records

This section lists the parameters you can use in a request for usage records.

Parameter Name Data Type Required Description
service string yes Only include usage records that match this service text, partially or fully in any position.
channel string yes Set the channel to be call.
from string yes Only include usage records for from numbers that begin with the number provided.
to string yes Only include usage records for to numbers that begin with the number provided.
status string no Only include usage records that have the status you select. Possible values include:

  • success
  • canceled
  • expired
startTime string no Only include usage records for OTPs created this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only the date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC time zone.
endTime string no Only include usage records for OTPs created this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only the date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC time zone.
channelStatus string Only include usage records that match the underlying channel status, partially or fully in any position.
checkStatus string no Only include usage records that have the status you list.

  • valid
  • invalid

If there are multiple checks with invalid and finally valid, this record is counted for both the valid and invalid filter.
accountSid string no Only include usage records that are for this specific account ID. The accountSid should be one of the sub accounts of this account.
subAccounts string no If set to true, include usage records that are initiated by all the sub accounts within this account. By default, this is set to false.

Response Parameters for Usage Records

This section lists the parameters you get back from a request for usage records.

Parameter Description
description This provides a description of the filter you chose for the channel. If you didn’t set a filter, you’ll get the message for All, otherwise you will get a description for SMS or call depending on your selection.
count The number of OTPs sent through the specified channel, or all channels, depending on what filter choice you made.
unit This will say OTP each time, because this is what you are checking on – OTP usage.
uri The uri shows your query parameter request.

Common Response Error Codes

This section lists the error codes that can be returned if something goes wrong with a request.

Error Code HTTP Status Error Message Description Category
401 401 Validation failed Occurs when validation failed for the provided accountSid and token. All
450 401 AccountSid passed is wrong or not the sub-account of the account “zzzzz”. “zzzzz” is the accountSid passed in the validation request, but is wrong or not the sub-account of the accountSid passed in the authentication header. All
451 400 Mandatory parameter is missing. is the actual parameter name that is missing. All
452 400 Platform error. Error internal to the platform. Contact Mitto for assistance. All