TextKitDocs

Buy many numbers in an area code

Quota is checked for the whole quantity up front (429, nothing bought).

POST/v1/numbers/bulk-purchase

Body Parameters

  • area_codestringrequired

    Example: 415.

  • quantityintegerrequired

    Maximum 50. Minimum 1.

  • pool_idstring

    Add the new numbers to this pool

  • tagsarray of string

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

After that, carrier refusals are reported per number and backfilled from spare inventory; shortfall counts any the area code could not supply. Test keys mint sandbox numbers.

Supports the Idempotency-Key header: a retried request replays the original response instead of buying again.

Responses

  • 201JSON object

    At least one 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

  • objectbulk_purchase
  • requestedinteger
  • purchasedarray of Number
  • failedarray of object
  • failed[].phone_numberstring
  • failed[].errorstring
  • failed[].messagestring
  • shortfallinteger

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.