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:

• 2FA API Endpoints. – See a complete list of endpoints available with the 2FA API.
• Send an OTP Endpoint. – Review details about request and response parameters. See available languages for text-to-speech (TTS).
• Cancel an OTP Endpoint. – See all request and response parameters. Use these to cancel an OTP.
• Retrieve Session Detail Records Endpoint. – This section explains how to retrieve session detail records (SDRs). It includes error codes specific to SDRs.
• API Usage Endpoint. – See how often you use the API for OTPs. You can filter for different channels like call or SMS.
• Limit API Use Endpoint. – Use limits to enforce limitations on the number of OTPs sent.
• Update a Limit Endpoint. – Update a limit you created.
• Delete a Limit Endpoint. – Delete a limit you don’t need.
• Retrieve a List of Limits Endpoint. – Get a complete list of limits.
• Retrieve a Single Limit. – Get details about a single limit.
• Create a Workflow – Combine different ways to send an OTP into a single workflow.
• Update a Workflow – Add another event to an existing workflow, or add/change a description about the workflow.
• Delete a Workflow – Remove a workflow if you don’t need it anymore.
• Get a List of Workflows – Retrieve a list of all workflows for an account or sub-account.

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.

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.

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.

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.

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.

Response Parameters for Verifying an OTP

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

Error Codes for Verify Endpoint

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.

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.

Error Codes for the /2fa/cancel Endpoint

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.

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

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.

Error Codes for Retrieving SDRs

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

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:

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.

API Usage Error Codes

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

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:

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

Response Parameters for Updating a 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

Response Parameters for Deleting a Limit

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

Response Parameters for Retrieving a List of Limits

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

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

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

Response Parameters for Create a Workflow

Error Codes for Create Workflow Endpoint

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.

Response Parameters for Update a Workflow

Error Codes for Update a 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

Response Parameters for Delete a Workflow

Error Codes

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

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

Error Codes

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

Response Parameters for Get a Single Workflow

Error Codes