TextKitDocs

Email the code instead

The text did not arrive: email a code for the same verification.

POST/v1/verify/{id}/fallback

Path Parameters

  • idstringrequired

Body Parameters

  • emailstringrequired

    The address to email the code to Example: ada@example.com.

  • channelemail

    The channel to fall back to. Only email today. Default "email".

  • user_ipstring

    Optional. Your end user's IP address, counted in the same per-IP limit as POST /verify.

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

One verification id, so one charge when the code is checked. The email carries a new code that replaces the texted one; Check it by email: it proves the address, not the phone (a check by phone answers 409 invalid_state).

The try count carries over and the new code gets a fresh 10 minutes. Once per verification, while it is pending (409 invalid_state otherwise).

The email limits of POST /verify apply. Test keys send nothing; the code stays 111111.

Supports the Idempotency-Key header.

Responses

  • 200Verification

    The verification, now on channel email

  • 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 (charged: false)

  • 404Error

    Not found

  • 409Error

    invalid_state: already moved to email, or no longer pending; or an idempotency conflict

  • 429Error

    Rate limit or quota exceeded

  • 503Error

    channel_unavailable: email codes cannot go out right now (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 (charged: false)

  • 404

    Not found

  • 409

    invalid_state: already moved to email, or no longer pending; or an idempotency conflict

  • 429

    Rate limit or quota exceeded

  • 503

    channel_unavailable: email codes cannot go out right now (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.