TextKitDocs

Purchase a number

Supports the Idempotency-Key header: a retried purchase replays the original 201.

POST/v1/numbers

Body Parameters

  • phone_numberstringrequired

    Example: +15005550132.

  • customer_idstring

    Optional: assign the number to one of your customers

  • registration_idstring

    Optional (live numbers): the registration this number should send for. Without it the number follows your account's registration.

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.

Responses

  • 201Number

    Number purchased

  • 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

  • 409Error

    Idempotency conflict

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring

    Example: +15005550132.

  • objectnumber
  • phone_numberstring
  • statusactive, released
  • modetest, live
  • created_atstring (date-time)
  • customer_idstring

    The customer this number is assigned to Nullable.

  • labelstring

    Nullable.

  • tagsarray of string
  • poolsarray of string

    Pool ids

  • senderobject

    How the number stands with the carriers. null on sandbox numbers and on numbers that need no registration (toll-free, Canadian). Only an active number can text anyone; in every other state it can text only your verified numbers. Nullable.

  • sender.statetest_only, pending, active, action_needed

    test_only: no registration submitted. pending: a registration is in review, or approved and being linked. active: linked to an approved registration. action_needed: see reason.

  • sender.registration_idstring

    The registration it is (being) linked to Nullable.

  • sender.reasonstring

    What to do, in plain words, when state is action_needed Nullable.

  • sender.updated_atstring (date-time)
  • toll_freeobject

    Toll-free verification, on live toll-free numbers only (null on every other number). Only a verified number texts anyone; its texts and STOP/HELP replies name business. Until the account has live access it texts only your verified numbers, verified or not; the carriers verifying it also verifies its business with us and gives a sandbox account live access. Nullable.

  • toll_free.statusnot_started, pending, verified, rejected
  • toll_free.businessstring

    The business the verification names Nullable.

  • toll_free.use_casestring

    Nullable.

  • toll_free.verified_atstring (date-time)

    Nullable.

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

  • 409

    Idempotency conflict

  • 429

    Rate limit or quota exceeded

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.