Docs
Numbersv4

Buy numbers

POST/numbers

Buy 1 to 10 US local numbers found with GET /numbers/available, with products turned on. The purchase finishes asynchronously: the response is a provisioning purchase, and number.purchase.completed or number.purchase.failed fires when it settles (or poll GET /numbers/purchases/{purchaseId}). Retrying with the same Idempotency-Key and body returns the same purchase. An SMS number sends texts once it's assigned to a provisioned 10DLC campaign, which Blooio does automatically when the organization has one. OAuth apps need numbers:manage.

Headers

AuthorizationRequiredstring

Your API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.

Bearer
Idempotency-KeyRequiredstring

Unique key that makes the purchase safe to retry.

Body parameters

JSON
phone_numbersRequiredstring[]

US local numbers in E.164 format, as returned by GET /numbers/available.

productsRequiredTelecomProduct[]

Products to turn on for every number in the purchase.

Returns

dataoptionalNumberPurchase
purchase_idRequiredstring

Purchase id (pur_...).

statusRequiredstring

completed once every number is an active channel; failed when the carrier refused the order.

"provisioning""completed""failed"
phone_numbersRequiredstring[]
productsRequiredTelecomProduct[]
erroroptionalobject

Present on a failed purchase.

codeoptionalstring
created_atRequiredinteger

Epoch ms.

Response codes

202The purchase, provisioning
400`products_required`, `invalid_products`, `idempotency_key_required`, or `invalid_phone_numbers` (with the offending `phone_numbers`).
401Your API key is missing or invalid. Pass it as a bearer token.
403`feature_not_enabled`: Blooio SMS and Blooio Voice aren't enabled on this organization.
409`number_limit_reached` (with the organization's `limit`), `number_unavailable` (with the `phone_numbers` already taken), or `idempotency_key_reused_with_different_body`.
422`number_unavailable`: the carrier refused the order.
502`upstream_unavailable`: the carrier network couldn't be reached. Retry with backoff.
503`telephony_unavailable`: Blooio Voice isn't configured. Buy without `voice`, or retry later.

Sends a live request with your values and shows the real response below. Your key is stored only in this browser.

Request
curl -X POST https://api.blooio.com/v4/numbers \
Body object
Response objectexample
{  "data": {    "purchase_id": "obj_a1b2c3d4",    "status": "provisioning",    "phone_numbers": [      "+15551234567"    ],    "products": [      "sms"    ],    "error": {      "code": "number_unavailable"    },    "created_at": 0  }}