Skip to main content
POST
/
reverse
/
initiate
cURL
curl --request POST \
  --url https://api.contiguity.com/otp/reverse/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "+15551234567",
  "factor": "1234",
  "to": "+16465550123",
  "language": "en",
  "success_url": "https://example.com/webhooks/otp/success"
}
'
{
  "id": "req_xxxxxxxxxxxxxxxx",
  "timestamp": 1765397289220,
  "api_version": "v2025.12.10",
  "object": "response",
  "data": {
    "otp_id": "r_otp_123456",
    "number": "+15551234567",
    "factor": "1234",
    "to": "+16465550123",
    "expires_at": "2025-02-01T12:00:00.000Z",
    "ui": {
      "text": "Text 1234 to +1 (646) 555-0123 to verify your phone number.",
      "qr_code": "sms:+16465550123?body=1234"
    },
    "success_url": "https://example.com/webhooks/otp/success"
  }
}

​
What is a Reverse OTP?

A reverse OTP verifies a user’s phone number by having the user send a code to you via SMS, rather than you sending it to them. This approach offers several key benefits compared to traditional SMS OTPs:
  • Receiving SMS messages is easy and often free, so attackers may abuse online services to receive codes and bypass standard verification.
  • Sending an SMS, however, requires the user to use their own phone and carrier plan, making it more difficult to fake and providing greater confidence in the user’s authenticity.
  • You save on operational costs, since you’re not paying to send SMS codes to your users.
  • Message delivery rates are often higher. Outbound SMS can be blocked, delayed, or filtered by carriers—especially for international users or high-volume senders. When users initiate the message themselves, it is much more likely to be delivered, as their carrier typically supports sending SMS to the US from anywhere in the world.
Streamline the experience with a QR codeOnce you’ve initiated a reverse OTP session, Contiguity provides a payload that you can turn into a QR code. Display this QR code to your user, who can then scan it with their phone to automatically populate their phone number and code fields.
const session = await contiguity.otp.reverse.initiate({
    number: "+15551234567",
    language: "en"
});
Next:
await generateQRCode(session.ui.qr_code);

Result

In most cases, it’s helpful to present both the QR code and written instructions to the user. That said, if you want to maximize the chance the message is sent from a mobile device, you may prefer to display only the QR code, since scanning it typically requires using a phone.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
number
string
required

Expected sender phone number. Must be in E.164 format.

Example:

"+15551234567"

​
factor
string

Code or phrase the user will send. Defaults to a random 4-digit code if not provided.

Maximum string length: 16
Example:

"1234"

​
to
string

Phone number to text. If you lease a number from Contiguity, you can enter it here. Defaults to a random Contiguity-owned number.

Example:

"+16465550123"

​
language
string
default:en

Language code for UI strings

Example:

"en"

​
success_url
string<uri>

Webhook URL to post successful verification. By default, Contiguity will use your existing webhook preferences.

Example:

"https://example.com/webhooks/otp/success"

Response

Start a Reverse OTP verification session

​
id
string
required
Example:

"req_xxxxxxxxxxxxxxxx"

​
timestamp
number
required
Example:

1765397289220

​
api_version
string
required
Example:

"v2025.12.10"

​
object
string
required
Example:

"response"

​
data
object
required