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

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

500

InternalServerError

application/json

post

HTTPcURLJavaScriptPython

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

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

500

InternalServerError

application/json

post

HTTPcURLJavaScriptPython

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"
}