About the 2FA API Reference

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

If you want to send regular SMS, please refer to the SMS/Bulk SMS page.

If you want to simplify set up, see if Mitto offers an integration that covers your use case.

2FA API Endpoints

The 2FA API has endpoints to send or cancel an OTP and retrieve session detail records. It also has endpoints to check API usage and enforce API limits on usage. This section summarizes the endpoints and request types.

Send an OTP

https://cpaas.mittoapi.com/2fa/send
POST – send a request for an OTP to be sent to a particular number.

Verify an OTP

https://cpaas.mittoapi.com/2fa/verify
POST – send a request to verify an OTP you sent.

Cancel an OTP You Sent

https://cpaas/mittoapi.com/2fa/cancel
POST – send a POST request to cancel an OTP you’ve sent.

Retrieve Session Detail Records

https://cpaas.mittoapi.com/2fa/search
POST – send a POST request with filtering options for records with specific attributes.
GET – send a GET request to get all session detail records (SDRs).

https://cpaas.mittoapi.com/2fa/search/{OTPSid}
GET – send a GET request containing the ID for a specific OTP request to retrieve information about that request.

API Usage

https://cpaas.mittoapi.com/2fa/usage/records
GET – send a GET request for a list of all existing records associated with your 2FA account credentials.
POST – send a POST request with filtering options to filter records returned.

https://cpaas.mittoapi.com/2fa/usage/records/{subresource}
GET – send a GET request to filter usage records by blocks of time like daily, monthly, or yearly. You can also apply filters.

Limit API Use

https://cpaas.mittoapi.com/2fa/limits
POST – set limits by sending a POST request with options.

https://cpaas.mittoapi.com/2fa/limits/{limitSid}
PUT – update limits with a PUT request.
DELETE – delete limits with a DELETE request and details about the limit you want to remove.

https://cpaas.mittoapi.com/2fa/limits/search
GET – get a list of all the limits you’ve created.

Workflows

https://cpaas.mittoapi.com/2fa/workflows
POST – create a workflow.

https://cpaas.mittoapi.com/2fa/workflows/{workflowSid}
PUT – update a workflow.
DELETE – delete a workflow.

https://cpaas.mittoapi.com/2fa/workflows/search
GET – list workflows.

https://cpaas.mittoapi.com/2fa/workflows/search/{WorkflowSid}
GET – specific workflows.

Send an OTP Endpoint

You send an OTP by sending a POST request with basic authentication to the endpoint: https://cpaas.mittoapi.com/2fa/send

Request Parameters for Sending OTPs

This section provides request parameters for sending an OTP. This requires the use of a POST request.

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 no A method for sending an OTP message as sms or call or email. If not passed, default is SMS.
accountSid string no The OTP message will be sent on behalf of the accountSid you provide. The accountSid has to be a valid sub-account.
subject string Required for email channel Email subject for the OTP message, it’s required only in the email channel.
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.
repeat string no If you choose to send a voice message, you must specify the number of times the TTS OTP message will be played in the event that the user does not respond. It’s required for the call channel, but if you don’t enter a choice, it defaults to 1. 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.
length string no You can specify the number of digits for the OTP code. If you do not specify something, by default a 6 digit number will be generated for the OTP code.
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

e 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.

timeout string no You can choose the time in seconds for which an OTP is valid. Post timeout period, the OTP is automatically canceled if it is not successfully verified. The default is 300 seconds.
guardTime string no If you call the Send API again to send a new OTP with the same service (call or SMS) and the same parameters while the previously generated OTP is still valid, the previous OTP is cancelled, and the new OTP is sent. However, if the guardTime (in seconds) parameter is passed in the send request, the old OTP is valid for guardTime and then cancelled. This is to accommodate scenarios where the underlying SMS or call channel may be slow to deliver the message and by the time the new OTP is generated, the user might have received the old OTP.
limits string no Key-Value pair Limits to restrict on number of OTP’s generated based on criteria that developers select.
workflow string no The workflow name to apply to the corresponding workflow template.

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 OTPs

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 the sub error code.
requestID The unique OTP request identifier for the OTP request.

Error Codes for the /2fa/send Endpoint

This section details all the error codes that can be returned from requests to the Send API endpoint.

Error Code HTTP Status Error Message Description Category
401 401 Validation failed This error code appears if validation failed for the provided accountSid and token. All
450 401 AccountSid passed is wrong or not sub-account of account “zzzzz”. If you pass in the wrong accountSid to the validation request or it is not a sub-account of the accountSid passed in the authentication header, you will get this error. All
451 400 Mandatory parameter “abc” is missing. “abc” is the parameter name that is missing. If you are missing multiple required parameters, you will get a list of comma separated parameter names. All
452 400 Underlying message from Mitto Error returned by underlying Mitto platform. All
453 409 Too many OTP request to same destination Number This error occurs when an OTP is sent to the same destination number within 1 min of your previous send. The 2FA API limits the number of OTP sent to the same number to a maximum of one per min. Send
470 404 Invalid OTP Unique Id Verify is called for a Unique ID which is not present in-system. Verify
472 409 OTP is expired Verify is called for a Unique Id which is present in the system but expired. Verify
473 409 OTP is cancelled Verify is called for a Unique Id which is present in the system but cancelled. Verify
474 401 Invalid OTP Code Verify is called for a Unique Id which is present but an Invalid Code is passed. Verify
497 409 Invalid Limits. There is no Limits with name “XXX” Send API is called with a Limits name that is not defined. Send
505 409 Invalid Workflow The API was called with a workflow name that is not defined. Send

Verify an OTP Endpoint

After you send an OTP, you will want to verify the code. Use the verify an OTP endpoint to check that the user entered the right verification code.

Request Parameters for Verifying OTPs

Verify the code you sent through SMS or Voice to the destination.

Parameter Data Type Required Description
service string yes The name of your service.
requestId string yes The request ID that you received when initiating the OTP message.
accountSid string no If your OTP message was initiated on behalf of an accountSd, you must include the same accountSid to be able to verify the OTP request.
code string yes The verification code that you sent to the user through SMS.

Response Parameters for Verifying an OTP

The response that comes back provides details about whether the OTP was correctly verified or not.

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

Error Codes for Verify Endpoint

Error Code HTTP Status Error Message Description Category
470 404 Invalid OTP Unique Id Verify is called for a request ID that doesn’t exist. Verify
472 409 OTP is expired Verify is called for an ID which exists, but is expired. Verify
474 401 Invalid OTP Code Verify is called for an ID which is present and an invalid code is passed. Verify

Cancel an OTP Endpoint

You can cancel an already sent OTP. You do this by sending a POST request with basic authentication to this endpoint: https://cpaas.mittoapi.com/2fa/cancel

Your request must include the request ID for the OTP that was sent. You can retrieve this information from the response you get when you use the Send API endpoint to request to send an OTP.

Request Parameters for Cancelling OTPs

If you are cancelling an OTP that you sent, your request for cancellation must include the request ID for the specific OTP.

Parameter Data Type Required Description
requestId string yes The requestID was received when initiating OTP message.
accoutSid string no If an OTP message was initiated on behalf of the accountSid, you must provide the same accountSid to be able to cancel the OTP request.

Response Parameters for Cancelling OTPs

When you cancel an OTP, you get back a response detailing the success or failure of your cancellation. For reference, the request ID that uniquely identifies the OTP you wanted to cancel is included.

Parameter Description
code The sub error code for the request
message The message for describing the sub error code.
requestID The unique OTP request identifier for the OTP request.

Error Codes for the /2fa/cancel Endpoint

Error Code HTTP Status Error Message Description Category
401 401 Validation failed If validation failed for provided accountSid and token All
450 401 AccountSid passed is wrong or not sub-account of account “zzzzz”. “zzzzz” is accountSid passed in validation request but is wrong or not sub-account of accountSid passed in authentication header. All
451 400 Mandatory parameter xxx is missing. xxx is actual parameter name. Comma separated parameters name if multiple. All
452 400 Underlying message from Mitto Error returned by underlying Mitto platform. All
490 404 Invalid OTP Unique Id Control (Cancel for now, but may be other too in future) is called for Unique ID which is not present in-system Control
472 409 OTP is expired Verify is called for Unique Id which is present in the system but expired Verify
473 409 OTP is cancelled Verify is called for Unique Id which is present in the system but cancelled Verify
493 409 Invalid limit id Limit ID passed is not present in the System Update, Search Single, Delete Limit

Retrieve Session Detail Records Endpoint

The Session Detail Record endpoint allows you to retrieve a specific OTP or a list of OTP sessions and its corresponding details like which channel was used to send an OTP, and underlying errors or successes.

You can retrieve a list of session detail records with the endpoint:

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

Retrieve Session Detail Records Parameters

Retrieve records with the choices from this table.

 

Parameter Data Type Required Description
page integer no Which page of OTP records to return, starting from 0.
pageSize integer no Number of records returned per page.
accountSid string no Only include OTP list that is initiated by this specific accountSid. The accountSid should be of one of the sub accounts of this account.
subAccounts boolean no If set to true, include the OTP list that is initiated by all the sub accounts within the accountSid you provided.
service string no Only include OTPs in the list that match this service text, partially or fully in any position. For example if OTP service is “Support” and the service filter parameter is “ppo”, it will match.
channel string no Only include OTPs in the list that are initiated via this channel. Possible values are call, sms, email, or combined. Combined is for OTPs sent as part of a workflow.
from string no Only include OTPs in the list that have a from which begins with this number or email. For example, if an OTP is sent from ‘15713316943’ and the from filter parameter is ‘1’, it will match. However if the from filter parameter is ‘3’, this record will not match. This allows you to filter for OTPs sent from a specific country code.
to string no Only include OTPs in the list if they begin with this number/email. For example, if the OTP’s ‘to’ is ‘16513333367’ and the to filter parameter is ‘1’, it will match. However if the to filter parameter is ‘3’, this record will not match. This allows you to filter the sent OTP to specific country codes.
targetSid string no Only include OTPs in the list that match the target sid of SMS, Call or Email provided, partially or fully in any position.
status string no Only include OTPs in the list that have this status. Possible values are success, cancelled, or expired.
startTime string no Only show OTPs in the list that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2019-10-05T22:45:32) or if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a 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 the UTC timezone.
endTime string no Only show OTPs in the list that were created on this date/time or earlier, given as an ISO-8601date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a 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 the UTC timezone.
channelStatus string no Only include OTPs in the list that match the underlying channel status, partially or fully in any position.

The available statuses for the channels are:

SMS – sending, sent, failed, received, delivered, and undelivered.

CALL – queued, ringing, in-progress, completed, failed, busy and no-answer.

Sort Returned Data

You can use the SortBy with the GET method to determine which attributes you want to sort by and in which direction. Available directions include:

  • asc – ascending
  • desc – descending

You use SortBy as a query parameter. The format would be: https://cpaas.mittoapi.com/2fa/search?sortBy=sorting attribute:direction

Query Request Parameter Description
DateCreated Sort by date on which the OTP was created
Service Sort by service
Status Sort by status

Retrieve Session Information by OTP Sid

You can return session information about a single OTP by sending a GET request to the URI: https://cpaas.mittoapi.com/2fa/search/{OTPSid}

OTPSid is the unique ID that comes back in the response when you send an OTP. The ID is referred to as the requestID.

The only parameter you send is the OTP.

Response Parameters for Retrieving SDRs

These response parameters apply to retrieving delivery reports by individual OTP, or multiple.

Response Parameter Description
sid OTP Unique Id that was returned when send API was called
service Service parameter passed in when send API was called
accountSid accountSid parameter passed in when send API was called
dateCreated Date when this OTP requested was initiated
dateUpdates Date when this OTP SDR was updated
status Status of this OTP request. Possible values are successful, expired or cancelled
.

  • successful : OTP was successfully verified by verify API call
  • expired : OTP expired
  • cancelled : OTP was cancelled either by calling cancel API or because send API was called to send new OTP while previous one has not yet been verified or expired.
uri Unique URI that you can call to get only this specific OTP SDR
checks Number of verify API calls that captures additional details like if it was valid or invalid and timestamp when verify was received by system. It also captures code used by verify API.
events This captures the events like SMS or call that was sent to end user. It has all details like sender, recipient, targetSid which is underlying platform Mitto id. It also exposes channel Error and message if delivery of SMS or Call fails.

Error Codes for Retrieving SDRs

Error Code HTTP Status Error Message Description Category
401 401 Validation failed If validation failed for provided accountSid and token All
450 401 AccountSid passed is wrong or not sub-account of account “zzzzz”. “zzzzz” is accountSid passed in validation request but is wrong or not sub-account of accountSid passed in authentication header. All
451 400 Mandatory parameter xxx is missing. xxx is actual parameter name. Comma separated parameters name if multiple. All
452 400 Underlying message from Mitto Error returned by underlying Mitto platform. All
480 404 Invalid OTP Unique Id Control (Cancel for now, but may be other too in future) is called for Unique ID which is not present in-system Control

API Usage Endpoint

The Usage API lets you retrieve API usage information for your 2FA account during any time period and through any usage channel. This makes it easy to build reporting and analytics tools for your application.

You can retrieve information by sending a GET or POST request to the URI: https://cpaas.mittoapi.com/2fa/usage/records

Request Parameters for API Usage

Parameter Data Type Required Description
channel string no Only include Usage records that are initiated via this channel. Possible values are
:

  • call
  • SMS

If the channel is passed using the query format, the total number of calls or sms sent in a given time period will be shown.

to string no Only include usage records that begin with this number/text.
 For example if OTP to is “16513333367” and the filter parameter is “1”, it will match. However, if to filter parameter is “3”, this record will not match.
 This allows you to filter usage records sent to a specific country code.
status string no Only include usage records that have this status. Possible values are
:

  • success
  • cancelled
  • expired
startTime string no Only include usage that has occurred on or after this date. Format is YYYY-MM-DDTHH:MM:SS (ISO-8603). All dates are in GMT. As a convenience, you can also specify offsets to today. For example, startTime=-30days will make startTime be 30 days before today.
endTime string no Only include usage that has occurred on or after this date. Format is YYYY-MM-DDTHH:MM:SS (ISO-8603). All dates are in GMT. As a convenience, you can also specify offsets to today. For example, endTime=-30days will make endTime be 30 days before today.
channelStatus string no Only include usage records that match the underlying channel status, partially or fully in any position. For SMS, the values can be queued, sending, sent, failed, received, delivered, and undelivered. For Call, they can be queued, ringing, in-progress, completed, failed, busy, and no-answer.
service string no Only include usage records that match this service text, partially or fully in any position. For example if the OTP service is “Support” and the service filter parameter is “ppo”, it will match.
subAccounts boolean no If set to true, include usage records that are initiated by all the sub accounts within this account. By default the value is false.
checkStatus string no Only include Usage records that have this check status. Possible values are
:

  • valid
  • invalid

If there are multiple checks with invalid and finally valid, these records are counted for both the valid and invalid filter.

accountSid string no Only include Usage record that is initiated by this specific accountSid.

Request Parameters to Add to the URL to Schedule Usage Reports

If you want to arrange for scheduled reports, you can add a sub resource to the endpoint: /2fa/usage/records/{Subresource}

Supported sub resources include:

Sub Resource Description
Daily Return a usage record on a daily basis. If no date filter is passed, Mitto retrieves the last 30 days of usage.
Monthly Return a usage record on a monthly basis. If no date filter is passed, Mitto retrieves the last 12 months of usage.
Yearly Return a usage record on a yearly basis. If no date filter is passed Mitto only retrieves this year and the previous year’s usage.
Today Return a usage record for today.
Yesterday Return a usage record for yesterday.
ThisMonth Return a usage record for this month.
LastMonth Return a usage record for last month.

Response Parameters for API Usage

The response parameters are the same as whatever you set for the filters in your initial request plus a few more, detailed here.

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.

API Usage Error Codes

 

Error Code HTTP Status Error Message Description Category
401 401 Validation failed If validation failed for the provided accountSid and token you’ll see this error message. All
450 401 AccountSid passed is wrong or not the sub-account of account “zzzzz”. “zzzzz” is the accountSid passed in the validation request, but it is wrong or not the the sub-account of the accountSid passed in the authentication header. All
451 400 Mandatory parameter zzz is missing. zzz is the actual parameter name. Comma separated parameters appear if there are multiple parameter issues. All
452 400 This is an underlying message from cpaas.mittoapi An error returned by the underlying cpaas.mittoapi platform. All

Limit API Use Endpoint

You make a request to create a new limit by sending a POST request to: https://cpaas.mittoapi.com/2fa/limits

Limits provide the capability to enforce limitations on the number of OTPs sent based on various keys you define. Keys can be defined to put limits based on many parameters. Some examples include:

  • Phone Number
  • End User IP Address
  • Application specific Session-Id
  • Geolocation of End User IP Address

This enables developers to safeguard against malicious attacks like bots trying to sign in to an application from one specific IP address or some user intentionally trying to generate many OTPs.

2FA provides flexibility for Developers to define Limits based on mixed keys. For example, 1 OTP per min per number but 4 OTP per min per IP address etc. Each limit has buckets associated with (maximum of 2 buckets allowed per limit) to put restrictions for that limit. For example, 1 OTP per 60 seconds and 10 OTP per 86400 seconds (24 hrs) for a limit based on phone number. This means the OTP will be limited to 1 minimum and 10 maximum per day for the same phone number recipient. You must pass a list of your limits when invoking the Send API to enforce limits.

Note

If no limit is defined or if no limit is passed when invoking Send API, by default 1 OTP per min per recipient phone number will be applied as default.

Request Parameters for Create Limit Endpoint

Parameter Data Type Required Description
name string yes A unique name that you choose for the limit you are creating. You pass this as a key when passing a limit to the Send API.
buckets yes The buckets parameter can contain one or more buckets. An example JSON body looks like this:
"buckets":[
{
"name":"bucket1",
"max":"1",
"interval":"10"
},
{
"name":"bucket2",
"max":"10",
"interval":"86400"
}
]

For each bucket you provide a name for the bucket (name), the maximum number of OTPs that can be sent in a given time (max), and the time interval (interval).
description string no You can include a description of the limit, to make it easier to use later.
accountSid string no If you want to associate the limit with a specific sub-account, you put the account ID here.

Response Parameters for Creating a Limit

The response body contains a code telling you whether the limit was successfully created, a message describing the code, and the data for the limit.

The response returned is a JSON body. Parameters include:

Parameter Description
code Sub-error code in case of an error.
message Message describing the error if an error occurred or a success message.
data
Parameter Description
sid This is a unique limit ID.
accountSid Unique account identifier for which this particular limit was created.
dateCreated The timestamp when this limit was created.
dateUpdated The timestamp when this limit was updated.
name The unique name of this limit.
buckets There can be up to two buckets created for a limit. Each bucket has the following three parameters:

  • name – Any descriptive name that makes sense
  • max – Maximum OTP allowed for a given interval in seconds
  • interval – The time period in seconds to throttle send OTP requests
description The description you want to provide for this limit
uri A unique URI that you can call to get the specific Enterprise associated with the limit (if any).
accountEmail The email for the account associated with the accountSid.
targetAccountSid The unique account for which this particular limit was created.
targetAccountEmail The unique account email corresponding to the targetAccountSid.

Update a Limit Endpoint

You use the Limit endpoint to update an existing limit for a given account. You can make an update by sending a PUT request to:
https://cpaas.mittoapi.com/2fa/limits/{limitSid}

Request Parameters for Updating a Limit

Parameter Data Type Required Description
limitSid string yes The unique SID of the limit that was returned when you created the limit.
buckets string no Optional. JSON formatted Buckets as explained below

  • name : Any descriptive name that makes sense
  • max : Maximum OTP allowed for given interval in seconds
  • interval : Time period in seconds to throttle send OTP requests.
description string no A description for the limit.

Response Parameters for Updating a Limit

Parameter Description
data
Parameter Description
sid The unique ID for the limit.
name The name of the limit you updated.
buckets The buckets (up to 2) associated with the specific limit. Each bucket lists the name of the bucket, the max number of OTPs that can be sent for a set interval, and the interval in seconds.
description If a description was provided for the limit, it appears here.
code The error or success code telling you about the response status.
message A message describing the meaning of the error or success code you received.
requestID The unique ID identifying the request you sent to update the limit.

Delete a Limit Endpoint

You can use the Limit endpoint to delete an existing limit for a given account. You can make a deletion by sending a DELETE request to:
https://cpaas.mittoapi.com/2fa/limits/{limitSid}

Request Parameters for Deleting a Limit

Parameter Data Type Required Description
limitSid string yes The unique ID representing the limit that was returned when you created a limit.

Response Parameters for Deleting a Limit

Parameter Description
code Sub-error code in case of an error or a success code.
message A message describing the error or success code.
data
Parameter Description
sid The unique ID for the limit.
name The name of the limit you updated.
buckets The buckets (up to 2) associated with the specific limit. Each bucket lists the name of the bucket, the max number of OTPs that can be sent for a set interval, and the interval in seconds.
description If a description was provided for the limit, it appears here.
code The error or success code telling you about the response status.
message A message describing the meaning of the error or success code you received.
requestID The unique ID identifying the request you sent to update the limit.
requestID If your request fails, you will receive the request ID in the returned response.

Retrieve a List of Limits Endpoint

You can list the limits created under your account by sending a GET request to:
https://cpaas.mittoapi.com/2fa/limits/search

Request Parameters for Retrieving a List of Limits

Parameter Data Type Required Description
page integer no Use this to specify which page of limit records to return, starting from 0. If not mentioned, the default is 0.
pageSize integer no Specify the number of records returned per page. If not mentioned, the default is 10.
name string no Optional parameter. Only show Limits that match name text, partially or fully.
startTime string no Only show limits that were created on 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 a 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 show limits that were created on 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 a 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.

Response Parameters for Retrieving a List of Limits

Parameter Description
code This is the error or success code for the response.
message This is a message describing the error or success code.
data
Parameter Description
result This returns the data parameters that were returned when you create a limit. You can see these parameters in the response section for creating a limit.
pageSize This is the number of records returned per page.
total This is the total number of records returned.
page This shows what page of records is returned.
numPages This is the total number of pages.
start This is the starting offset of the page.
end This is the ending offset of the page.
firstPageUri This is a unique URI that you can call to get records in the first page.
nextPageUri This is a unique URI that you can call to get records in the next page.
uri This is a unique URI that you can call to get records.

Retrieve a Single Limit

You can retrieve a single limit by its unique identifier by sending a GET request to:

https://cpaas.mittoapi.com/2fa/limits/search/{LimitSid}

Request Parameters for Retrieving a Single Limit

Parameter Data Type Required Description
limitSid string yes This is the unique SID for the limit that was returned in the response when you created a limit.

The response parameters are the same as returned when you create a limit. To see this information, refer to the Response Parameters for Creating a Limit section.

Error Codes for Limits Endpoints

 

Error Code HTTP Status Error Message Description Category
401 401 Validation failed If validation failed for the provided accountSid and token you’ll see this error message. All
450 401 AccountSid passed is wrong or not the sub-account of account “zzzzz”. “zzzzz” is the accountSid passed in the validation request, but it is wrong or not the the sub-account of the accountSid passed in the authentication header. All
451 400 Mandatory parameter zzz is missing. zzz is the actual parameter name. Comma separated parameters appear if there are multiple parameter issues. All
452 400 This is an underlying message from cpaas.mittoapi An error returned by the underlying cpaas.mittoapi platform. All
492 409 A limit with that name already exists. A limit name should be unique in a given account. Create a limit.
493 409 Invalid Limit Id The limit sid passed is not present in the system. Update, Search Single, Delete Limit

Create a Workflow

Workflows combine SMS and voice in any sequence you want. For example, you could have a workflow where you send an OTP with SMS, then wait for 60 seconds and send the OTP as a voice (text-to-speech) message. Then wait 60 seconds and send one more time with TTS. If the end user verifies the OTP successfully at any point, the workflow is stopped. For another example, you could send an OTP with TTS, wait 60 seconds and then send using TTS again.

You can set any timeout period between events that you like, with the minimum value for a timeout being 15 seconds.

To create a workflow, you send a POST request to this endpoint: https://cpaas.mittoapi.com/2fa/workflows

Request Parameters for Create Workflow

 

Parameter Data Type Required Description
name string yes A unique name for your workflow. You pass this as a key when passing the workflow to the Send an OTP endpoint.
channels JSON yes A JSON body containing the events you want to happen. For example:
“channels”:[{“channel”:”sms”, “timeout”:”60″}, {“channel”:”voice”, “timeout”:”60″}, {“channel”:”voice”, “timeout”:”60″}, {“channel”:”voice”, “timeout”:”60″}]channel: Indicates via which channel the OTP event should be sent to the end user. Only SMS and voice are supported as of today.timeout: Time period in seconds from previous event where if OTP is not verified, the next event for the workflow will start. An event is defined by channel you want to try sending the message through, and the length of the timeout. The timeout must be a minimum of 15 seconds. If a value less than 15 is passed, an error is returned. A maximum of 5 channels can be definied for any workflow.
description string no You can include a description for the workflow and what it does.
accountSid string no You can provide the sub-account Sid for which limit is to be created. If it’s not passed the limit is created for the same account calling the API.

Response Parameters for Create a Workflow

 

Parameter Description
code Sub-error code in case of an error.
message Message describing the error if the error occurred or a success message.
data
Parameter Description
sid Unique Workflow Id
accountSid Unique cpaas.mittoapi account that called the API to create the workflow.
accountEmail Unique cpaas.mittoapi account email corresponding to accountSid.
targetAccountSid Unique cpaas.mittoapi account for which this particular workflow is created.
targetAccountEmail Unique cpaas.mittoapi account email corresponding to a targetAccountSid
dateCreated The timestamp for when this workflow was created.
dateUpdated The timestamp for when this workflow was updated.
name The unique name of this limit.
channels JSON formatted channels are:
channel: Channel via which the OTP is sent like SMS or voice.
interval: Time period in seconds from previous event to send OTP via defined channel.
description The description for this workflow.
uri The unique URI that you can call to get only this specific workflow.

Error Codes for Create Workflow Endpoint

 

Error Code HTTP Status Error Message Description Category
502 409 A workflow with that name already exists. The workflow name should be unique in the given account. Create, Update Workflow
504 409 Too many channels, max is 5. A maximum of 5 channels can be defined for a given workflow. Create, Update Workflow
507 409 Channel Timeout cannot be smaller than 15. If the timeout passed is less than 15 seconds, this error is returned. Create, Update Workflow

Update a Workflow

You can update a workflow using a PUT request with the endpoint: https://cpaas.mittoapi.com/2fa/workflows/{workflowSid}

Request Parameters for Update a Workflow

You can update a workflow by adding an additional event on to it or changing the description of the workflow.

Parameter Data Type Required Description
workflowSid string yes The unique SID of the workflow that was returned when create workflow was invoked.
channels JSON no JSON formatted channel with the following fields:
channel: Channel via which the OTP event is sent
interval: Time period in seconds after the previous event to send the OTP via the next channel
description string no Description for what this workflow is.

Response Parameters for Update a Workflow

Parameter Description
code Sub-error code in case of an error.
message A message describing the error if an error occurred or a success message.
data
Parameter Description
sid Unique Workflow Id
accountSid Unique cpaas.mittoapi account that called the API to create the workflow.
accountEmail Unique cpaas.mittoapi account email corresponding to accountSid.
targetAccountSid Unique cpaas.mittoapi account for which this particular workflow is created.
targetAccountEmail Unique cpaas.mittoapi account email corresponding to a targetAccountSid
dateCreated The timestamp for when this workflow was created.
dateUpdated The timestamp for when this workflow was updated.
name The unique name of this limit.
channels JSON formatted channels are:
channel: Channel via which the OTP is sent like SMS or voice.
interval: Time period in seconds from previous event to send OTP via defined channel.
description The description for this workflow.
uri The unique URI that you can call to get only this specific workflow.

Error Codes for Update a Workflow

Error Code HTTP Status Error Message Description Category
503 409 Invalid Workflow Id The workflow sid passed is not present in the system. Update, Search Single, Delete Workflow
502 409 Workflow with that name already exists. Workflow name should be unique in a given account. Create, Update Workflow
504 409 Too many channels, Max is 5. A maximum of 5 channels can be defined for a given workflow. Create, Update Workflow
507 409 Channel Timeout canot be smaller than 15 If the timeout passed is less than 15 seconds, this error is returned. Create, Update Workflow

Delete a Workflow

You can delete a workflow by sending a DELETE request to the endpoint: https://cpaas.mittoapi.com/2fa/workflows/{workflowSid}

Request Parameters for Delete a Workflow

Parameter Data Type Required Description
workflowSid string yes The unique SID for the workflow you want to delete. The unique SID was returned when the Create Workflow was first invoked.

Response Parameters for Delete a Workflow

Parameter Description
code Sub-error code is returned here if there’s an error.
message A message describing the error if one occurred or a success message.
data
Parameter Description
sid Unique Workflow Id
accountSid Unique cpaas.mittoapi account that called the API to create the workflow.
accountEmail Unique cpaas.mittoapi account email corresponding to accountSid.
targetAccountSid Unique cpaas.mittoapi account for which this particular workflow is created.
targetAccountEmail Unique cpaas.mittoapi account email corresponding to a targetAccountSid
dateCreated The timestamp for when this workflow was created.
dateUpdated The timestamp for when this workflow was updated.
name The unique name of this limit.
channels JSON formatted channels are:
channel: Channel via which the OTP is sent like SMS or voice.
interval: Time period in seconds from previous event to send OTP via defined channel.
description The description for this workflow.
uri The unique URI that you can call to get only this specific workflow.

Error Codes

 

Error Code HTTP Status Error Message Description Category
503 409 Invalid Workflow Id Workflow sid passed is not present in the system. Update, Search Single, Delete Workflow

Get a List of Workflows

If you want to review all the workflows you created for a particular account or associated sub-account, send a GET request to:
https://cpaas.mittoapi.com/2fa/workflows/search

Request Parameters for Get a List of Workflows

 

Parameter Data Type Required Description
page integer no Which page of workflow records to return, starting from 0. If you do not include this parameter, by default the page is 0.
pageSize integer no Number of records returned per page. If you do not include this parameter, by default the pageSize will be 10.
name string no Only show workflows that match name text, partially or fully.
accountSid string no Only show workflows initiated by this specific accountSid. The accountSid should be one of the sub accounts of this account.
subAccounts boolean no If set to true, include workflows associated with all the sub accounts within this account. By default it’s false.
startTime string no Only show workflows created on 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, f you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight on the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone.
endTime

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction. The direction can either be ‘asc’ for ascending and ‘desc’ for descending sort ordering. Here’s the overall format: SortBy=sorting attribute:direction. If no direction parameter is provided, then the listing of workflows is sorted by the attribute in ascending order. You can sort by name or dateCreated.

Response Parameters for Get a List of Workflows

 

Parameter Description
code The sub-error code for the response.
message A message describing the error if an error occurred or a success message.
data A list of workflows.

Parameter Description
result Workflows data.

Parameter Description
sid Unique Workflow Id
accountSid Unique cpaas.mittoapi account that called the API to create the workflow.
accountEmail Unique cpaas.mittoapi account email corresponding to accountSid.
targetAccountSid Unique cpaas.mittoapi account for which this particular workflow is created.
targetAccountEmail Unique cpaas.mittoapi account email corresponding to a targetAccountSid
dateCreated The timestamp for when this workflow was created.
dateUpdated The timestamp for when this workflow was updated.
name The unique name of this limit.
channels JSON formatted channels are:
channel: Channel via which the OTP is sent like SMS or voice.
interval: Time period in seconds from previous event to send OTP via defined channel.
description The description for this workflow.
uri The unique URI that you can call to get only this specific workflow.
pageSize Number of records returned per page.
total Total number of records.
page Which page of records to return.
numPages Total number of pages.
start Starting offset of page.
end Ending offset of page.
firstPageUri A unique URI that you can call to get records in the first page.
nextPageUri A unique URI that you can call to get records in the next page.
uri Unique URI that you can call to get records.

Error Codes

 

Error Code HTTP Status Error Message Description Category
503 409 Invalid Workflow Id The workflow sid passed is not present in the system. Update, Search Single, Delete Workflow

Get a Single Workflow

You can retrieve a single workflow for an account or sub-account using its unique identifier. Retrieve a workflow by sending a GET request to:
https://cpaas.mittoapi.com/2fa/workflows/search/{WorkflowSid}

Request Parameters for Get a Single Workflow

Parameter Data Type Required Description
workflowSid string yes The unique SID of the workflow that was returned when you created a workflow.

Response Parameters for Get a Single Workflow

Parameter Description
code The sub-error code for the response.
message A message describing the error if an error occurred or a success message.
data A list of workflows.

Parameter Description
result Workflows data.

Parameter Description
sid Unique Workflow Id
accountSid Unique cpaas.mittoapi account that called the API to create the workflow.
accountEmail Unique cpaas.mittoapi account email corresponding to accountSid.
targetAccountSid Unique cpaas.mittoapi account for which this particular workflow is created.
targetAccountEmail Unique cpaas.mittoapi account email corresponding to a targetAccountSid
dateCreated The timestamp for when this workflow was created.
dateUpdated The timestamp for when this workflow was updated.
name The unique name of this limit.
channels JSON formatted channels are:
channel: Channel via which the OTP is sent like SMS or voice.
interval: Time period in seconds from previous event to send OTP via defined channel.
description The description for this workflow.
uri The unique URI that you can call to get only this specific workflow.
pageSize Number of records returned per page.
total Total number of records.
page Which page of records to return.
numPages Total number of pages.
start Starting offset of page.
end Ending offset of page.
firstPageUri A unique URI that you can call to get records in the first page.
nextPageUri A unique URI that you can call to get records in the next page.
uri Unique URI that you can call to get records.

Error Codes

Error Code HTTP Status Error Message Description Category
503 409 Invalid Workflow Id The workflow sid passed is not present in the system. Update, Search Single, Delete Workflow