Verify (OTP)

One-time passcodes over SMS or email, with the anti-abuse half already built.

Anyone can send a six-digit code. What this exists for is the part customers do not want to own: stopping an attacker turning a public "send me a code" endpoint into an SMS-pumping ATM against their bill.

POST /api/v1/verifications
POST /api/v1/verifications/{id}/check
GET  /api/v1/verifications/{id}

Scope: write:verifications to start and check a code, read:verifications to look one up.

Start a verification

curl -X POST https://www.sendoka.com/api/v1/verifications \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"sms","to":"+14155550142","from":"+14155550100"}'
{ "id": "ver_...", "status": "pending", "channel": "sms", "expires_at": "2026-08-18T12:10:00.000Z" }
field default notes
channel — sms or email
to — E.164 or an email address, at most 320 characters
template Your verification code is {{code}} {{code}} is the only variable
code_length 6 4–10
ttl_seconds 600 60–3600
max_attempts 5 1–10
from — required. A phone number / sender ID registered to your org (SMS), or an address on a domain you have verified (email). The same senders /v1/sms and /v1/emails accept — a verification is your message to your user, so it goes out under your sender. Your org's sandbox sender counts, under the same rule as on /v1/emails: with a live key it only reaches your org members' verified addresses (403 SANDBOX_RECIPIENT_NOT_ALLOWED otherwise), so real users need your own domain. An email from is otp@yourdomain.com or Name <otp@yourdomain.com>; the display name is quoted or RFC 2047-encoded for you, the same way /v1/emails sends it. A malformed address, a second @ or a quoted local part answers 422 INVALID_FROM before anything is charged.
subject Your verification code email only
dlt_template_id — SMS only. Required for +91 destinations. See India (DLT).

The destination is not echoed back. The caller already knows it, and echoing it turns any log or proxy that captures responses into a store of end users' phone numbers.

Send an Idempotency-Key. A verification is a billed send, and a retry after a timeout used to text the user a second code — for a verification id the caller never saw. A retry under the same key now replays the recorded 201 (same id), and one that arrives while the first is still sending gets 409 IDEMPOTENCY_IN_FLIGHT. The 201 is recorded before it is returned, so a retry sent the moment the first response arrives replays it rather than seeing IN_FLIGHT. Only the 201 is stored: a refusal, or a 502 SEND_FAILED, frees the key so the retry really sends. Both SDKs attach a key automatically. See idempotency.md.

Email codes route and bounce like any other email from your domain. With a live key, a code goes out through the sending domain's region and fallback region, and through its dedicated IP pool when it has one. A paused pool refuses the request with 409 IP_POOL_PAUSED before anything is written. A hard bounce or spam complaint suppresses the address, scoped to the sending tenant, and from then on a code to that address answers 422 SUPPRESSED. A code is not a message, so it does not appear in GET /v1/emails and fires no message.* webhooks — its delivery is on the verification itself (below) and on the verification.* events.

One key per code request — never one per user or per destination. A replay sends nothing and returns the first verification for 24h: same id, status: "pending" and the original expires_at, even after that code has expired. A key such as otp-${userId} turns every later "resend code" into a silent replay, and the user never gets a new code. Mint a fresh key each time the user asks for a code, and reuse it only to retry that one request.

India (DLT)

An Indian carrier scrubs every message against a template registered on the DLT registry. A +91 send with no registration attached is accepted by the provider and dropped on the way to the handset — you get a message id for a code nobody received, which is the worst possible outcome for an OTP.

So a +91 verification takes the same dlt_template_id /v1/sms takes:

curl -X POST https://www.sendoka.com/api/v1/verifications \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"sms","to":"+919812345678","from":"SENDOKA",
       "template":"{{code}} is your verification code",
       "dlt_template_id":"dlt_..."}'

The id must name a template of yours in approved status that the DLT provider has issued provider-side ids for. The entity PEID and the provider's template id travel with the send as the carrier's DestinationCountryParameters; the dlt_ id itself is recorded on the verification row, so a dropped-OTP support case can start from the registration the send actually used.

Omitting it refuses the send before anything is written or any ceiling is spent, with the same codes /v1/sms answers:

code meaning
DLT_TEMPLATE_REQUIRED +91 destination, no dlt_template_id
DLT_TEMPLATE_NOT_FOUND the id is not a template of yours
DLT_TEMPLATE_NOT_APPROVED registered, but not yet approved
DLT_TEMPLATE_NOT_PROVISIONED approved locally, but the provider has issued no entity/template ids — the carrier has nothing to scrub against

All four are 422. The body your template renders has to match the registered DLT content, variables included; the registry rejects paraphrases.

Set DLT_ENFORCE=false (dev only) and the gate steps aside entirely. Every other destination ignores the field — email has no destination country, and a non-+91 number resolves no registration, so nothing is stored on the row.

Check a code

curl -X POST https://www.sendoka.com/api/v1/verifications/ver_.../check \
  -H "Authorization: Bearer $SENDOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'
{ "id": "ver_...", "status": "approved" }
{ "id": "ver_...", "status": "denied", "reason": "invalid" }

reason is one of invalid, expired, not_found, max_attempts. Codes are single-use.

A check is scoped like the lookup: the key's own mode, its project and a tenant-bound key's own tenant. A verification outside that scope is not_found, and checking it spends none of its attempts.

A 503 is ours, not the user's. It means the attempt could not be recorded — the code they are holding still works, and showing them "wrong code" would be a lie about whose fault it is. Retry.

A check takes no Idempotency-Key, so the SDKs do not resend one through a timeout or a 5xx on your behalf: a check whose first attempt did land would spend a second attempt, or answer not_found for the code it had just approved. On a 503, have the user submit the code again.

Look up a verification

"My user never got the code" is the commonest Verify support case. Read the verification:

curl https://www.sendoka.com/api/v1/verifications/ver_... \
  -H "Authorization: Bearer $SENDOKA_API_KEY"
{
  "id": "ver_...",
  "status": "pending",
  "channel": "sms",
  "to": "+14*******42",
  "attempts": 1,
  "max_attempts": 5,
  "environment": "live",
  "tenant_id": null,
  "dlt_template_id": null,
  "delivery_status": "failed",
  "delivery_error": "TEXT_UNREACHABLE",
  "delivery_updated_at": "2026-08-18T12:00:09.000Z",
  "expires_at": "2026-08-18T12:10:00.000Z",
  "approved_at": null,
  "created_at": "2026-08-18T12:00:00.000Z"
}

Scope read:verifications. Reading spends no attempt, so it is safe to poll. The lookup is scoped like GET /v1/sms/{id}: the key's own mode, its project and a tenant-bound key's own tenant. Anything else is 404, and so is a row past the 2-day retention.

field meaning
status pending, approved (a correct code consumed it — approved_at says when), expired, or max_attempts (locked by wrong guesses). Derived in the order a check refuses in.
to The destination, masked: +14*******42, j***@example.com. The full value is never echoed, for the same reason POST does not echo it.
attempts Wrong guesses spent. A correct code spends none.
delivery_status sent: the provider accepted the code. Then at most one terminal outcome, first one wins: delivered; bounced, for a hard email bounce or an invalid number; or failed, for a send the provider refused (the POST answered 502 SEND_FAILED), a soft email bounce, a carrier filter, an expiry or an unreachable handset. null for a test key, which contacts no provider, and for verifications created before delivery tracking existed.
delivery_error The carrier's or provider's reason for bounced / failed. A send the provider refused carries one of the fixed send-failure sentences, never the provider's exception text.

An SMS stays at sent unless the carrier returns a receipt. Not every route does, so sent alone does not mean the code was lost.

The same receipts are webhook events:

event fires when
verification.delivered The receipt says the code reached the handset or mailbox.
verification.failed The receipt says it did not: delivery_status is bounced or failed.
{
  "event": "verification.failed",
  "data": {
    "verification_id": "ver_...",
    "channel": "sms",
    "delivery_status": "failed",
    "error": "TEXT_UNREACHABLE",
    "occurred_at": "2026-08-18T12:00:09.000Z"
  },
  "timestamp": "2026-08-18T12:00:10.113Z",
  "environment": "live",
  "tenant_id": null,
  "delivery_id": "whd_..."
}

The payload never names the destination. Each fires at most once per verification, and only for live codes. A refusal at send time already answered your POST with 502, so it fires nothing. The events are scoped to the verification's tenant like any other.

In the dashboard, Verify (under Send) lists the last two days of codes with the same masked destination, status and delivery verdict. To find one user's codes, type their full number or address into the search box. It matches exactly and shows only that user's rows.

What is enforced

  1. Destination allowlisting. The premium NANP ranges and the satellite/network prefixes (+870, +878, +881/+8816, +882, +883) that pumping rings target are refused outright — before anything is written or sent.
  2. Two hourly ceilings, both spent up front: 5 per destination and 1,000 per org. Spending them after committing is what leaves a row nothing can satisfy. Test-key calls are counted in ceilings of their own, the same size: a test key asking for codes to a real user's number cannot use up that number's live allowance and lock the user out.
  3. Hash-only storage. sha256, never the code. A database read must not hand over a working credential.
  4. An atomic attempt cap. The claim is one statement with the cap in the WHERE and the increment in a CASE, so a correct code spends no attempt and concurrent guesses cannot each pass a check they read as under the cap. Read-modify-write is not a counter — N racing guesses all read the same value and all write value+1, leaving the real bound on a ~1e6 space at the attacker's connection count.

Test mode

A sok_test_* key creates the verification without contacting a provider. An OTP flow is the thing most worth exercising repeatedly in CI, and doing that against a real handset costs money and a phone.

The test-mode code is fixed: code_length zeros — 000000 at the default length, 0000 for code_length: 4. Check it like any other code:

curl -X POST https://www.sendoka.com/api/v1/verifications/ver_.../check \
  -H "Authorization: Bearer $SENDOKA_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"000000"}'
# { "id": "ver_...", "status": "approved" }

Everything else behaves as in live mode, so a CI suite can exercise each branch: any other code is denied with reason: "invalid" and spends an attempt, the max_attempts cap and ttl_seconds expiry apply, and an approved code is single-use. The code is still never returned by the API in any environment, and a live verification never gets it — live codes are always random.

Each test verification is one of test mode's daily allowance of messages (rate limits), charged after the hourly ceilings above: a request those refuse spends none of it.

Each key checks only verifications its own mode created. Every check spends one of the verification's attempts and a correct one consumes it, so a live verification is not_found to a test key, as an id it cannot see: a leaked test key cannot lock a real user out of their code. The reverse holds too: a test verification is not_found to a live key. Its code is the published 000000, so a live key that could check it would let anyone holding a test key mint a verification for a real user's number and pass your live sign-in flow with it.

Billing and retention

Metered on the channel it sent through, so a verification costs what the SMS or email it sent costs.

Rows are reaped after 2 days — shorter than the 7 days the signup sweeps use, because these are other people's end users. A code lives ten minutes and no support case needs the row a week later.