Skip to content

SMS Validation API (1.0.0)

Backend API for phone number validation via SMS and other channels. This API allows you to validate phone numbers by sending SMS verification codes and verifying them.

Rate Limiting

The API implements multi-level rate limiting per account, country, and phone number.

Offline Proof Verification

If your tenant has a verificationSecret configured, the API returns an HMAC proof in the validation response. This proof can be verified offline without calling the API (see /v1/verify-proof endpoint).

Download OpenAPI description
verifyapi_v1.json
verifyapi_v1.yaml
Overview
API Support

support@smsmanager.com

Languages
Servers
Mock server

https://api-ref.smsmanager.com/_mock/openapi/cs/verify/verifyapi_v1/

Production server

https://verify-api.smsmanager.com/

Validation

Phone number validation operations

Operations

Verify HMAC proof

Request

Verifies an HMAC proof for phone validation without storing any state. This endpoint is useful for backend verification when you have all the validation data but want SMS Manager to verify the HMAC calculation.

This endpoint not requires authentication - proof itself is the authentication.

All of these data are returned by the /v1/validations endpoint.

Note: This only works for accounts with a verificationSecret configured.

Bodyapplication/jsonrequired
phoneNumberstringrequired

The normalized phone number

Example: "1234567890"
tokenstringrequired

The validation token

Example: "61591bd88d8f..."
codestringrequired

The 6-digit verification code

Example: "123456"
timestampstring(date-time)required

The timestamp when validation started

Example: "2024-01-15T10:30:00Z"
proofstringrequired

The HMAC proof to verify

Example: "a1b2c3d4e5f6..."
curl -i -X POST \
  https://api-ref.smsmanager.com/_mock/openapi/cs/verify/verifyapi_v1/v1/verify-proof \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "1234567890",
    "token": "61591bd88d8f...",
    "code": "123456",
    "timestamp": "2024-01-15T10:30:00Z",
    "proof": "a1b2c3d4e5f6..."
  }'

Responses

Proof verification result

Bodyapplication/json
validboolean

Whether the proof is valid

expiredboolean

Whether the validation has expired (24 hours)

Response
application/json
{
  "valid": true
}

Start phone validation

Request

Initiates a new phone number validation by sending an message with a verification code. Returns a validation token that must be used for subsequent verification.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
phoneNumberstring^[1-9]\d{6,14}$required

The phone number to validate (digits only, including country code)

Example: "1234567890"
turnstileTokenstring

Turnstile verification token (required if tenant has requireTurnstile enabled)

Example: "0.abcdefghijklmnopqrstuvwxyz"
payloadobject

Optional custom payload to attach to the validation

Example: {"userId":"user123","source":"checkout"}
curl -i -X POST \
  https://api-ref.smsmanager.com/_mock/openapi/cs/verify/verifyapi_v1/v1/validations \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "phoneNumber": "1234567890"
  }'

Responses

Validation started successfully

Bodyapplication/json
tokenstringrequired

Unique validation token to use for verification

Example: "val_7af7215261b8497cb355e617b13f4ef2"
statusstring(ValidationStatus)required

Current status of the validation

Enum"pending""code_sent""verified""failed""expired"
expiresAtstring(date-time)required

When this validation expires (typically 10 minutes)

Example: "2024-01-01T00:10:00.000Z"
timestampstring(date-time)required

When this validation was started (used for HMAC verification)

Example: "2024-01-01T00:00:00.000Z"
proofstring

HMAC proof for offline verification (only if tenant has verificationSecret)

Example: "a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2c4e6f8b0d2e4f6a8c0e2f4b6d8f0a2"
Response
application/json
{
  "token": "61591bd88d8fbe7736bca535809d1216dd71cb0b5cbf2b07e5a08adfbeb5d35b",
  "status": "pending",
  "expiresAt": "2024-01-01T00:10:00.000Z",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Verify code

Request

Verifies the code entered by the user. On successful verification, returns all data needed for backend verification including the phone number, token, code, timestamp, and HMAC proof (if account has verificationSecret configured).

The number of attempts is limited based on account configuration (default: 6).

Security
ApiKeyAuth
Path
tokenstringrequired

The validation token returned from the start validation endpoint

Example: val_7af7215261b8497cb355e617b13f4ef2
Bodyapplication/jsonrequired
codestring^[0-9]{6}$required

The 6-digit verification code from SMS

Example: "123456"
curl -i -X POST \
  https://api-ref.smsmanager.com/_mock/openapi/cs/verify/verifyapi_v1/v1/validations/val_7af7215261b8497cb355e617b13f4ef2/verify \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "code": "123456"
  }'

Responses

Code verified successfully

Bodyapplication/json
verifiedbooleanrequired

Whether the verification was successful

Example: true
phoneNumberstring

The verified phone number (only present if verified is true)

Example: "1234567890"
tokenstring

The validation token (only present if verified is true)

Example: "550e8400-e29b-41d4-a716-446655440000_abc123"
codestring

The verification code that was verified (only present if verified is true)

Example: "123456"
timestampstring(date-time)

When the validation was started (only present if verified is true)

Example: "2024-01-15T10:30:00Z"
proofstring

HMAC proof for this verification (only present if verified is true and tenant has verificationSecret)

Example: "86dd8444ed76402c93ce62497cb29a0d7af7215261b8497cb355e617b13f4ef2"
verifiedAtstring(date-time)

When the verification was completed (only present if verified is true)

Example: "2024-01-15T10:31:15Z"
Response
application/json
{
  "verified": true,
  "phoneNumber": "1234567890",
  "token": "61591bd88d8fbe7736bca535809d1216dd71cb0b5cbf2b07e5a08adfbeb5d35b",
  "code": "123456",
  "timestamp": "2024-01-15T10:30:00Z",
  "proof": "86dd8444ed76402c93ce62497cb29a0d7af7215261b8497cb355e617b13f4ef2",
  "verifiedAt": "2024-01-15T10:31:15Z"
}

Verify proof (optional)

Request

Optional endpoint to verify a proof hash from a previous successful validation. This can be used to confirm that a validation was completed successfully.

Security
ApiKeyAuth
Path
tokenstringrequired

The validation token returned from the start validation endpoint

Example: val_7af7215261b8497cb355e617b13f4ef2
Bodyapplication/jsonrequired
proofstringrequired

The proof hash to verify

Example: "86dd8444ed76402c93ce62497cb29a0d7af7215261b8497cb355e617b13f4ef2"
curl -i -X PATCH \
  https://api-ref.smsmanager.com/_mock/openapi/cs/verify/verifyapi_v1/v1/validations/val_7af7215261b8497cb355e617b13f4ef2 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "proof": "86dd8444ed76402c93ce62497cb29a0d7af7215261b8497cb355e617b13f4ef2"
  }'

Responses

Proof verified successfully

Bodyapplication/json
validboolean

Whether the proof is valid

phoneNumberstring

The validated phone number

verifiedAtstring(date-time)

When the validation was completed

Response
application/json
{
  "valid": true,
  "phoneNumber": "string",
  "verifiedAt": "2019-08-24T14:15:22Z"
}

Tenant

Tenant configuration endpoints

System

System health and status endpoints

SmsManager.com - visit https://smsmanager.com to learn more