TextKitDocs

Send a verification code

Generates a one-time code and sends it by text (channel: "sms", the default) or by email (channel: "email" with email).

POST/v1/verify

Body Parameters

  • channelsms, email

    How the code goes out. sms needs phone; email needs email. Default "sms".

  • phonestring

    The number to text the code to (channel sms). to works too. Example: +14155550132.

  • emailstring

    The address to email the code to (channel email). Disposable addresses are refused. Example: ada@example.com.

  • app_namestring

    Your product name, shown in the message At most 24 characters.

  • user_ipstring

    Optional. Your end user's IP address, as your server saw it. With it, one person requesting codes for many numbers or addresses is limited (20 an hour per IP on your account, texts and emails together); without it there is no per-IP limit, since requests come from your server.

  • fromstring

    Optional, channel sms only: send from a number you own instead of the TextKit pool

  • customer_idstring

    Optional: attribute the verification to one of your customers

Headers

  • Idempotency-Keystring

    Makes retries safe for 24 hours: the same key and body replays the original successful response (with Idempotent-Replayed: true); a different body returns 409. Failed requests release the key. At most 255 characters.

Details

Enforces expiry, attempt limits and anti-pumping controls. You do NOT need to own a phone number; TextKit sends from its own verification pool.

If the pool is unavailable, a live code is sent from one of your own numbers that can already text anyone (sender status active, or a verified toll-free number, whose codes always name its verified business); a number still being registered is never used, and with none ready the request is refused (400) and nothing is sent. Nothing is billed here; a verification is charged only when the code is checked successfully.

Supports the Idempotency-Key header, so a retried request does not text a second code. By email: the same template, limits per address and per domain, disposable addresses refused (403 verification_blocked), and test keys never send (the code is 111111).

Responses

  • 201Verification

    Verification created

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 403Error

    Blocked by Shield, or recipient_opted_out (the number opted out, or texted STOP to the number the code comes from; they text START to get codes again). charged: false

  • 409Error

    Idempotency conflict

  • 429Error

    Rate limit or quota exceeded

  • 503Error

    channel_unavailable: email codes cannot go out right now. Send a text instead (charged: false)

Response Fields

  • idstring

    Example: ver_a1B2c3D4e5F6g7H8.

  • objectverification
  • channelsms, email

    The channel the current code went out on

  • phonestring

    null on an email verification Nullable.

  • emailstring

    null until a code is emailed Nullable.

  • statuspending, approved, expired, max_attempts, blocked
  • attemptsinteger
  • testboolean
  • chargedboolean
  • created_atstring (date-time)
  • expires_atstring (date-time)
  • fallback_atstring (date-time)

    When the verification moved from text to email. Present only then.

  • customer_idstring

    The customer this is attributed to. Present only when set.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 403

    Blocked by Shield, or recipient_opted_out (the number opted out, or texted STOP to the number the code comes from; they text START to get codes again). charged: false

  • 409

    Idempotency conflict

  • 429

    Rate limit or quota exceeded

  • 503

    channel_unavailable: email codes cannot go out right now. Send a text instead (charged: false)

Idempotency

Send an Idempotency-Key header to make retries safe. For 24 hours the same key with the same body replays the original successful response (with Idempotent-Replayed: true); the same key with a different body returns 409. A failed request releases its key.