Trovacast

Contacts

Verify (one-time codes)

Send a one-time code by SMS, WhatsApp, a voice call or email, and check the code the person types back — with expiry, attempt limits, resend cool-downs and fraud protection built in.

/v1/verify (scopes verify:write to send and check, verify:read to read) runs the whole one-time-code flow for you: Trovacast makes the code, sends it, and tells you whether the code the person typed is the right one. Your application never sees or stores a code. It is separate from /v1/verifications, your project's own business verification.

Send a code

A six-digit code by SMS
curl -X POST 'https://api.trovacast.com/v1/verify' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "sms",
  "to": "+919876543210",
  "templateId": "TEMPLATE_ID",
  "metadata": {
    "userId": "u_123"
  }
}'
  • sms — templateId names one of your APPROVED SMS templates with exactly one variable, which receives the code. To India it must be a DLT template registered as TRANSACTIONAL (OTPs are transactional under TRAI) with its DLT template id. Priced at your plan's SMS rate for the destination, per segment.
  • whatsapp — templateId names an APPROVED AUTHENTICATION template; every variable (the body's, a copy-code button's) receives the code. Priced at the WhatsApp authentication rate.
  • voice — Trovacast calls the number and speaks the code twice, digit by digit. The call is a /v1 call like any other: every dial rule applies and it is rated per minute. The code is spoken inside a sensitive step, so every recording of the call and its live transcript pause for it. When your recording policy records the call on a channel whose carrier cannot pause its own recording (sensitiveGather: false in GET /v1/calls/channels), the code is not spoken: the call's flow fails (call.flow.failed, cause RECORDING_NOT_CONTROLLABLE).
  • email — a plain transactional email from your project's active email sender; an address on your suppression list is refused. Priced at your plan's email rate.
  • senderId picks one of your ACTIVE senders when you have more than one on the channel. codeLength is 4 to 10 digits (6 by default); ttlSeconds 60 to 1,800 (600 by default).
201 (json)
{
  "object": "verify",
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "livemode": true,
  "channel": "sms",
  "to": "•••• ••3210",
  "status": "pending",
  "codeLength": 6,
  "attempts": {
    "used": 0,
    "max": 5
  },
  "sends": {
    "count": 1,
    "max": 5,
    "lastSentAt": "2026-11-06T09:00:00.000Z",
    "nextResendAt": "2026-11-06T09:00:30.000Z"
  },
  "expiresAt": "2026-11-06T09:10:00.000Z",
  "approvedAt": null,
  "endedAt": null,
  "callId": null,
  "metadata": {
    "userId": "u_123"
  },
  "createdAt": "2026-11-06T09:00:00.000Z"
}

Check the code

Check what the person typed
curl -X POST 'https://api.trovacast.com/v1/verify/VERIFY_ID/check' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "482913"
}'

The answer is { "object": "verify_check", "valid": true|false, "verify": … }. A right code approves the verification (status: approved, and verify.approved fires once). A wrong one counts against attempts; the fifth wrong code fails it (status: failed). Once a verification is no longer pending every check is 409 VERIFY_NOT_PENDING — start a new one.

Resend

POST /v1/verify/{verifyId}/resend sends a new code on the same channel and stops the old one working; wrong attempts already made still count. A verification sends at most five codes in all, at least thirty seconds apart (429 VERIFY_RESEND_TOO_SOON with retryAfterSeconds; 409 VERIFY_SEND_LIMIT after the fifth). Each send is billed.

Expiry and events

A code that is not checked in time expires (status: expired) and verify.expired fires once. Both events carry the verification exactly as GET /v1/verify/{verifyId} reads it, and need verify:read on the endpoint's key. Neither ever carries a code.

Fraud protection

  • Codes are never sent to premium-rate or shared-cost numbers, to the satellite and international-network prefixes (+870, +881, +882, +883) or international premium and shared-cost services (+979, +808), or to destinations your project's destination policy blocks — 422 VERIFY_DESTINATION_BLOCKED.
  • At most 5 verifications to one destination an hour and 10 a day, and 60 a minute and 10,000 a day for the project — 429 VERIFY_RATE_LIMITED.
  • No SMS or WhatsApp code reaches a number whose contact opted out of that channel with your project — 422 VERIFY_RECIPIENT_OPTED_OUT. A marketing opt-out lets codes through only if your project turns on ignoreMarketingOptOut (PATCH /v1/settings/verify, your compliance decision); an SMS STOP is never overridden.
  • The code is never stored: Trovacast keeps a keyed hash bound to the verification and compares it in constant time. The destination is stored encrypted and shown masked (•••• ••3210, p•••@example.com).

Test mode

A test key's verification sends nothing and bills nothing, and its code is always the first codeLength digits of 1234567890 (123456 by default) — so a test suite can run the whole flow, events included (to your test endpoints), without a phone. Every other rule — limits, attempts, expiry, blocked destinations — applies as in live mode.

Billing

Each code sent is one charge at your plan's message rate for the channel (an SMS per segment and per destination country, WhatsApp at the authentication rate, email at the email rate), taken from your balance once the provider accepted it — never for a refused request or a send the provider refused. A voice code is a call, rated per minute like every call. A send your balance cannot cover is refused before anything goes out (402 BILLING_INSUFFICIENT_BALANCE).

Errors

CodeStatusMeaning and what to do
VERIFY_CHANNEL_UNAVAILABLE422The channel cannot send for your project: no ACTIVE sender on it, more than one and no senderId, or a senderId that is not one of yours.What to do: Pass senderId of one of your active senders on the channel (GET /v1/sms/senders lists SMS ones, GET /v1/whatsapp/account WhatsApp numbers), or set the channel up first.
VERIFY_DELIVERY_FAILED502The channel's provider did not accept the code. Nothing was billed; a first send's verification is canceled, a resend's stays pending.What to do: After a first send, start a new verification; after a resend, resend once the cool-down has passed. Use a new Idempotency-Key either way — the same key replays this error.
VERIFY_DESTINATION_BLOCKED422Codes are never sent there: a premium-rate or shared-cost number, a high-risk international prefix, a destination your project's destination policy blocks, or an email address on your suppression list. See Verify → Fraud protection.What to do: Do not retry this destination: ask the person for another number or address, or verify them on another channel.
VERIFY_DESTINATION_INVALID422to is not a phone number in E.164 (sms, whatsapp, voice) or an email address (email) — or it is not one its country assigns. See Verify.What to do: Ask the person for their number again and send it in E.164 (+ and the country code), or an email address for email. Do not retry the same to.
VERIFY_NOT_PENDING409The verification is no longer pending — approved, expired, failed or canceled (status names which) — so it takes no check and no resend.What to do: Do not check or resend it again: start a new verification with POST /v1/verify if the person still needs a code.
VERIFY_RATE_LIMITED429Too many verifications: 5 an hour or 10 a day to one destination, or 60 a minute or 10,000 a day for the project. The message says which.What to do: Do not retry at once: wait out the minute, hour or day the message names. Many codes to one destination are a sign of abuse — see Fraud protection.
VERIFY_RECIPIENT_OPTED_OUT422The number's contact opted out of the channel with your project: a full opt-out (an SMS STOP, an unsubscribe, a complaint), or a marketing opt-out your project does not let codes pass. Nothing was sent or billed.What to do: Do not retry the same channel. Verify the person on another channel (email, voice), or — if the opt-out was from marketing only and your compliance rules allow a code the person asked for — turn on ignoreMarketingOptOut with PATCH /v1/settings/verify. A STOP is never overridden: the person can text START to opt back in.
VERIFY_RESEND_TOO_SOON429A resend inside thirty seconds of the last code.What to do: Resend after retryAfterSeconds; meanwhile the person can still enter the code already sent.
VERIFY_SEND_LIMIT409The verification has sent five codes already.What to do: Start a new verification with POST /v1/verify (and a new Idempotency-Key).
VERIFY_TEMPLATE_INVALID422templateId is missing or cannot carry a code: SMS needs an APPROVED template with exactly one variable (to India a DLT TRANSACTIONAL template with its DLT id); WhatsApp needs an APPROVED AUTHENTICATION template.What to do: Pass the templateId of a template that fits (GET /v1/templates shows each one's status and category); create one and wait for its approval if you have none. See Send a code.