Ctrlk
Jump to...Create Free API Account
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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. A E.164 formatted string is recommended.

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
tostringRequired
serviceNamestringRequired
timeoutSecondsnumberOptional
codeLengthnumberOptional
realtimebooleanOptional
bypassbooleanOptional
externalIdstringOptional
longcodeIdnumberOptional
poolIdstringOptional
senderNamestringOptional
Responses
200

Success

application/json
post/verify/sms/send-code
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: 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": "invalid_format"
}

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
tostringOptional
verificationIdstringOptional
codestringRequired
Responses
200

Success

application/json
post/verify/sms/check-code
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"
}
PreviousPhone Number Format Guide
NextAppointment Reminders with confirmation replies

Last updated

Was this helpful?