Generate and validate 2FA / MFA codes via SMS

Learn how Mobile Text Alerts 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, SMS message delivery, and validation of user-supplied codes.

Why use SMS verification?

Steps for SMS validation with the Mobile Text Alerts API

1. Generate an SMS verification code to send to your user’s phone number by calling the /send-code endpoint.

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

3. You then send this code to Mobile Text Alerts to validate it via the /check-code endpoint.

4. Mobile Text Alerts returns the Verification Status for the request. You can use this status to allow or 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 ${serviceName} verification code is: ${code}

Optional request parameters allow you to customize the verification code, such as how long it will be valid 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 it deduplicates requests when network retries or other issues leave the request state unclear.

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

For duplicate requests, a 409 Conflict error is returned.

Request Fields

Name	Type	Description
to - required	string	The destination phone number to send the SMS verification code to.
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. Mobile Text Alerts stores a timestamp for this timeout and returns an EXPIRED status if a code is checked after the timeout period has elapsed. Default: 300
codeLength	number	Determines the length of the generated code. codeLength must be between 4 and 8 digits. Default: 6
externalId	string	The externalId parameter is an optional field for creating 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 want 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 for possible status codes.
verificationId	string	A unique identifier for this verification request. Use it to check code validity for the associated request.
messageId	string	An additional identifier you can use to correlate webhook events triggered by this verification message. Webhook event payloads for message-send and delivery-status include this messageId in the tags array.
deliverable	boolean	Indicates whether the number is valid.
reason	string	If the number is invalid, this contains 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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

tostringRequired

serviceNamestringOptional

timeoutSecondsnumberOptional

codeLengthnumberOptional

realtimebooleanOptional

bypassbooleanOptional

externalIdstringOptional

longcodeIdnumberOptional

poolIdstringOptional

senderNamestringOptional

gatedbooleanOptional

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

500

InternalServerError

application/json

post

/verify/sms/send-code

HTTPcURLJavaScriptPython

POST /v3/verify/sms/send-code HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "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",
  "gated": true
}

{
  "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 enter into your application. Once you receive the code, you can validate it using the check SMS code endpoint. You must retain one identifier for the request so you can validate 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 returned by the send-code request for this verification attempt.
code - required	string	The code supplied by the user to validate 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 does not indicate whether the supplied code was valid.

• 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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

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

/verify/sms/check-code

HTTPcURLJavaScriptPython

POST /v3/verify/sms/check-code HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "to": "text",
  "verificationId": "text",
  "code": "text"
}

{
  "to": "text",
  "verificationId": "text",
  "status": "PENDING"
}