One-Time Passwords via SMS

Contiguity offers a free OTP API that simplifies phone number verification using OTPs via SMS, which eliminates the need to develop custom logic. Gone are the days of paying for this simple feature.

Contiguity still bills you for the text messages on our Usage tier, includes them in Unlimited, and subtracts them from your quota if you’re on the Free tier.We don’t charge extra for the OTP API.

JavaScript
Python

Installing the SDK

Install the SDK

Bun
pnpm
npm
Yarn

bun add contiguity

pnpm add contiguity

npm install contiguity

yarn add contiguity

Initialize the Client

With API key
From env

import { Contiguity } from "contiguity";
const contiguity = new Contiguity("contiguity_sk_...your_key...");

import { Contiguity } from "contiguity";
// Reads CONTIGUITY_API_KEY or CONTIGUITY_TOKEN
const contiguity = new Contiguity();

Sending and Verifying OTPs

Send an OTP

To verify a user’s phone number, you’ll first need to send them an OTP.

const res = await contiguity.otp.new({ 
    to: "+1234567890", 
    language: "en", 
    name: "MyApp" 
});

The name parameter is optional, but recommended. It customizes the message to say “Your [name] code is…”, e.g. “Your Twilio code is…”

Verify the Code

When your user inputs the code, verify it using the OTP ID from the previous step.

const res = await contiguity.otp.verify({ 
    otp_id: "otp_123", 
    otp: "123456" 
});

The verification will return a boolean (true/false). OTPs expire 15 minutes after sending.

Resend if Needed

If needed, you can resend an OTP using the original OTP ID.

const res = await contiguity.otp.resend({ 
    otp_id: "otp_123" 
});

Resending an OTP does not renew its expiry time.

Parameters

otp.new(params)

string

required

The recipient’s phone number in E.164 format (e.g., “+1234567890”).

string

required

The language code for the OTP message. See supported languages below.

string

required

The name of your application or service. This will be included in the OTP message as “Your [name] code is…“.

otp.verify(params)

string

required

The unique OTP identifier returned from the otp.new() call.

string

required

The 6-digit verification code entered by the user.

otp.resend(params)

string

required

The unique OTP identifier from the original otp.new() call.

Reverse OTP

Reverse OTP verifies a phone number by having the user send a code to you. Start a session with otp.reverse.initiate():

const session = await contiguity.otp.reverse.initiate({
    service: "sms"
});

If you already know the phone number, in cases such as 2FA, pass number to require that exact sender:

const session = await contiguity.otp.reverse.initiate({
    number: "+1234567890",
    service: "sms"
});

The service can be "sms" or "imessage" and defaults to "sms". Using iMessage requires an active iMessage-capable leased number and an iMessage entitlement.Check the session’s status or cancel it using the returned otp_id:

const status = await contiguity.otp.reverse.verify(session.otp_id);
await contiguity.otp.reverse.cancel(session.otp_id);

otp.reverse.initiate(params)

string

Optional expected sender phone number in E.164. Omit it to discover the number from the inbound message.

string

The number the user sends the code to. It defaults to a random Contiguity-owned number. When using iMessage, provide an iMessage-capable number leased through Contiguity.

string

default:"sms"

The messaging service used to receive the code. Accepts "sms" or "imessage".

string

default:"en"

The language code used for the returned UI instructions.

string

A webhook URL called after successful verification. If omitted, Contiguity uses your configured webhook preferences.

Response

string

The Reverse OTP session ID used to check or cancel the session.

string | null

The sender’s phone number. Null until a matching message arrives if you omitted number at initiate.

string

The 6-character alphanumeric code the user must send (e.g. ABC123). Generated by Contiguity.

string

The number the user must message.

string

The messaging service receiving the code: "sms" or "imessage".

string

The session expiration time in ISO 8601 format.

object

Localized text instructions and a qr_code payload for opening the user’s messaging app.

string | null

The webhook URL used for successful verification.

object

Request metadata including ID, timestamp, and API version.

otp.reverse.verify(otp_id)

string

required

The Reverse OTP session ID returned by otp.reverse.initiate().

Response

string

The Reverse OTP session ID.

string

The session’s current status: "pending", "verified", "cancelled", or "expired".

string | null

The phone number that texted the code. Null until verified if you omitted number at initiate.

string

The session expiration time in ISO 8601 format.

object

Request metadata including ID, timestamp, and API version.

otp.reverse.cancel(otp_id)

string

required

The Reverse OTP session ID returned by otp.reverse.initiate().

Response

string

The cancelled Reverse OTP session ID.

string

Confirms that the session was cancelled.

object

Request metadata including ID, timestamp, and API version.

See the Reverse OTP API reference for API behavior, or learn more about Reverse OTP with iMessage.

Installing the SDK

Install the SDK

pip install contiguity

Initialize the Client

import contiguity
client = contiguity.login("your_token_here")

You can also initialize it with the optional ‘debug’ flag:

client = contiguity.login("your_token_here", True)

Sending and Verifying OTPs

Send an OTP

To verify a user’s phone number, you’ll first need to send them an OTP.

otp_id = client.otp.send({
    'to': "+15555555555",
    'language': "en",
    'name': "Contiguity"
})

The name parameter is optional, but recommended. It customizes the message to say “Your [name] code is…”, e.g. “Your Twilio code is…”

Verify the Code

When your user inputs the code, verify it using the OTP ID from the previous step.

verify = client.otp.verify({
    'otp_id': otp_id,  # from the previous step
    'otp': input       # the 6 digits your user inputted
})

The verification will return a boolean (true/false). OTPs expire 15 minutes after sending.

Resend if Needed

If needed, you can resend an OTP using the original OTP ID.

resend = client.otp.resend({
    'otp_id': otp_id  # from the first step
})

Resending an OTP does not renew its expiry time.

Parameters

otp.send(params)

string

required

The recipient’s phone number in E.164 format (e.g., “+15555555555”).

string

required

The language code for the OTP message. See supported languages below.

string

required

The name of your application or service. This will be included in the OTP message as “Your [name] code is…“.

otp.verify(params)

string

required

The unique OTP identifier returned from the otp.send() call.

string

required

The 6-digit verification code entered by the user.

otp.resend(params)

string

required

The unique OTP identifier from the original otp.send() call.

Supported Languages

Contiguity currently supports 33 languages for OTPs, including: English (en), Afrikaans (af), Arabic (ar), Catalan (ca), Chinese / Mandarin (zh), Cantonese (zh-hk), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Malay (ms), Norwegian (nb), Polish (pl), Portuguese - Brazil (pt-br), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Tagalog (tl), Thai (th), Turkish (tr), and Vietnamese (vi)

Getting Started

SDK Documentation by Product

SDK Documentation by Language

One-Time Passwords via SMS

Installing the SDK

Sending and Verifying OTPs

Parameters

otp.new(params)

otp.verify(params)

otp.resend(params)

Reverse OTP

otp.reverse.initiate(params)

Response

otp.reverse.verify(otp_id)

Response

otp.reverse.cancel(otp_id)

Response

Installing the SDK

Sending and Verifying OTPs

Parameters

otp.send(params)

otp.verify(params)

otp.resend(params)

Supported Languages

​Installing the SDK

​Sending and Verifying OTPs

​Parameters

​otp.new(params)

​otp.verify(params)

​otp.resend(params)

​Reverse OTP

​otp.reverse.initiate(params)

​Response

​otp.reverse.verify(otp_id)

​Response

​otp.reverse.cancel(otp_id)

​Response

​Installing the SDK

​Sending and Verifying OTPs

​Parameters

​otp.send(params)

​otp.verify(params)

​otp.resend(params)

​Supported Languages

Installing the SDK

Sending and Verifying OTPs

Parameters

otp.new(params)

otp.verify(params)

otp.resend(params)

Reverse OTP

otp.reverse.initiate(params)

Response

otp.reverse.verify(otp_id)

Response

otp.reverse.cancel(otp_id)

Response

Installing the SDK

Sending and Verifying OTPs

Parameters

otp.send(params)

otp.verify(params)

otp.resend(params)

Supported Languages