Create Free API Account

Generate and validate 2FA / MFA codes via SMS

Learn how MTA can generate and then validate verification codes via SMS for simplified two-factor authentication.

SMS Verification Overview

SMS verification is a form of two-factor authentication (2FA) where a user receives a one-time code via SMS to verify access to an application. SMS verification ensures that even if a password is stolen, an attacker would also need access to the user's phone to complete a login request.

The Mobile Text Alerts SMS Verification API provides an easy way to manage SMS multi-factor authentication workflows within your application. These endpoints provide verification code generation, delivery of SMS messages and validation of user supplied codes.

Why use SMS verification?

Steps for SMS validation with the MTA API

  1. Generate a SMS verification code to be sent to your user's number by calling the /send-code endpoint.

  2. If this is a valid phone number, the user receives a code and enters it into your application.

  3. You will then send this code to MTA to validate the request via the /check-code endpoint.

  4. MTA will return the Verification Status of the request. You can then use this status code to allow/deny access to your application.

Generate and send SMS verification code

One time verification codes can be generated and sent to a user by calling the send verification code endpoint detailed below.

The user will receive a message in this format:

Your ${} verification code is: ${code}

Optional request parameters allow you to customize this verification code such as the amount of time the code will be valid for and the code's length.

Successful responses include an identifying verificationId that can be used to check the validity of a user supplied code after it has been sent.

Send Verification Code endpoint verify/sms/send-code

Duplicate Requests (Idempotency)

This endpoint is idempotent which means that it handles de-duplicating requests in the event of networking issues or other issues that might cause a request to be in an unknown state.

When sending your request to the endpoint, simply include an X-Request-Id header with an alphanumeric value. If you're unsure if the request succeeded or not, you can simply re-send the request with the same X-Request-Id and the send endpoint will detect if it's a duplicate or not.

For duplicate requests, a 409 Conflict error is returned.

Request Fields

Name
Type
Description

to - required

string

The destination phone number to be sent the SMS verification code.

serviceName -required

string

A customer friendly name for your service, that will be included in the verification message

timeoutSeconds

number

The number of seconds the verification code will be considered valid. MTA will store a timestamp associated with this timeout and reflect an EXPIRED status if a code is checked after the timeout period has elapsed.

Default: 300

codeLength

number

Determines the length of the code generated. codeLength must be between 4 and 8 digits.

Default: 6

externalId

string

The externalId parameter is an optional field intended for you create and assign your own identifier for each message request. The externalId will be included in webhook notifications.

realtime

boolean

Indicates the number should be validated using the number verification service.

bypass

boolean

Indicates if you choose to bypass number validation. If true, a risk type will be returned in the response.

longcodeId

number

The id for a longcode to use when sending the verification code.

tags

object

A set of properties to attach to the outgoing message. These are for internal use only.

poolId

number

The id for a pool of longcodes to use when sending the verification code.

Response Fields

Name
Type
Description

to

string

The destination number supplied in the request

timeoutSeconds

number

The number of seconds the verification code will be considered valid. This value is provided in the request

type

string

The type of verification code.

For this response, this value will always be: sms

status

enum

An enum value representing the current status of this verification request. See Verification Status to see possible status codes.

verificationId

string

A unique identifier that identifies this specific verification request. Can be used when checking code validity to identify the associated verification request

messageId

string

An additional unique identifier for alignment with webhook calls that fire as a result of this verification message.

Webhook event payloads for message-send and delivery-status include this messageId in the tags array.

deliverable

boolean

Indicates if the number is valid.

reason

string

If the number is invalid, this will contain any additional information from the verification service.

carrier

string

The carrier identified for the to number.

lineType

string

The phone number type identified for the to number.

Possible values:landline ,mobile ,tollfree ,satellite ,voip ,premium ,pager ,unknown

risk

string

Any validation issues with the number, only present when bypass is true. See Risk Types below.

Risk Types

This endpoint will return a risk type when the bypass field in the request is set to true.

Possible values:

  • invalid_format

    • The phone number format itself is invalid.

  • deny_list

    • On our internal deny list pulled from delivery reports.

  • unsubscribed

    • Marked as unsubscribed for your account.

  • suspended

    • The number has been temporarily suspended by the carrier.

  • deactivated

    • The number has been deactivated by the carrier.

  • landline

    • The number is a landline number.

  • voip

    • The number is a VOIP (Voice-over-IP) number.

  • unknown

    • The number is invalid but the reason is unknown

Trigger SMS Verification Code

post
Authorizations
Body
tostringRequired
serviceNamestringRequired
timeoutSecondsnumberOptional
codeLengthnumberOptional
realtimebooleanOptional
bypassbooleanOptional
externalIdstringOptional
longcodeIdnumberOptional
poolIdstringOptional
senderNamestringOptional
Responses
200
Success
application/json
post
POST /v3/verify/sms/send-code HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 211

{
  "to": "text",
  "serviceName": "text",
  "timeoutSeconds": 1,
  "codeLength": 1,
  "realtime": true,
  "bypass": true,
  "externalId": "text",
  "longcodeId": 1,
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "poolId": "text",
  "senderName": "text"
}
{
  "to": "text",
  "timeoutSeconds": 1,
  "type": "sms",
  "status": "PENDING",
  "messageId": "text",
  "verificationId": "text",
  "deliverable": true,
  "reason": "text",
  "carrier": "text",
  "lineType": "text",
  "risk": null
}

Validate SMS code

After initiating an SMS Verification request, the user receives a code via SMS to be entered into your application. Once you've received this code, it can be validated using the Check SMS Code endpoint. You must retain one identifier for this request in order to validate it with the user-supplied code.

Check SMS Code endpoint verify/sms/check-code

Request Fields

Name
Type
Description

to*

string

The destination phone number this SMS verification code was sent to.

verificationId*

string

The unique identifier supplied in the response to a "Trigger SMS Verification Code" request that identifies this specific verification code request.

code - required

string

The code supplied by the user that should be validated for this verification request. Length must match the configured codeLength for this request.

*Either the to or verificationId field is required to identify the request.

Response Fields

Name
Type
Description

to

string

The destination number supplied in the request.

verificationId

string

The verification request ID supplied in the request.

If only to is supplied in the request, the response will still include this field for reporting purposes.

status

enum

An enum value representing the current status of this verification request. See Verification Status to see possible status codes.

Verification Status

This Verification Status is an enum value representing the current status of the SMS verification request. This is used to confirm the validity of the user supplied code.

Status codes:

  • PENDING

    • The verification request has been processed by Mobile Text Alerts and was sent to the user.

  • APPROVED

    • The supplied verification code is valid and the request has not yet expired.

  • EXPIRED

    • The verification request has expired. This status does not indicate whether the supplied code was/is valid or invalid.

  • INVALID

    • The verification request has not yet expired but the supplied code did not match the code sent to the user via SMS.

Check SMS Verification Code

post
Authorizations
Body
tostringOptional
verificationIdstringOptional
codestringRequired
Responses
200
Success
application/json
post
POST /v3/verify/sms/check-code HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "to": "text",
  "verificationId": "text",
  "code": "text"
}
{
  "to": "text",
  "verificationId": "text",
  "status": "PENDING"
}
PreviousSetting up your first webhookNextFAQ

Last updated

Was this helpful?