TextKitDocs

Act on many numbers at once

Tag, untag, label, pool, unpool or release up to 1000 numbers (100 for release).

POST/v1/numbers/bulk

Body Parameters

  • idsarray of stringrequired

    At most 1000 items.

  • actionadd_to_pool, remove_from_pool, add_tags, remove_tags, set_label, releaserequired
  • pool_idstring

    add_to_pool / remove_from_pool

  • tagsarray of string

    add_tags / remove_tags. Lowercased; up to 20 per number.

  • labelstring

    set_label; null clears At most 64 characters. Nullable.

  • confirmstring

    release only Example: RELEASE 2.

Details

Returns 200 with a result per id even when some fail. Release requires confirm: "RELEASE <count of ids>"; test keys cannot release live numbers.

Responses

  • 200BulkResult

    Per-id results

  • 400Error

    Malformed request or missing release confirmation

  • 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

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • objectbulk_result
  • actionstring
  • requestedinteger
  • succeededinteger
  • failedinteger
  • resultsarray of object
  • results[].idstring
  • results[].okboolean
  • results[].errorinvalid_id, duplicate, not_found, too_many_tags, mode_mismatch, carrier_error
  • results[].messagestring

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.

  • 400

    Malformed request or missing release confirmation

  • 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

  • 429

    Rate limit or quota exceeded