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.

Steps for SMS validation with the MTA API
Generate a SMS verification code to be sent to your user's number by calling the /send-code endpoint.
If this is a valid phone number, the user receives a code and enters it into your application.
You will then send this code to MTA to validate the request via the /check-code endpoint.
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
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
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
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
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
verify/sms/check-code
Request Fields
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
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.
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"
}
Last updated
Was this helpful?