Partner phone numbers

Give each customer its own dedicated number from Blujay’s ready numbers, in the area code you choose. When a customer no longer needs it, release it.

Partner accounts only. These calls need a partner admin key and the customer’s Blujay-Workspace header.

Assign a number

Name an area_code, or leave it out for any available number.

curl -X POST https://api.blujay.io/v1/phone-numbers \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Blujay-Workspace: workspace_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "area_code": "602" }'

const response = await fetch("https://api.blujay.io/v1/phone-numbers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLUJAY_API_KEY}`,
    "Blujay-Workspace": "workspace_abc123",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ area_code: "602" }),
});
const number = (await response.json()).data;
console.log(number.phone_number_id, number.display_number);

import os
import requests

response = requests.post(
    "https://api.blujay.io/v1/phone-numbers",
    headers={
        "Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}",
        "Blujay-Workspace": "workspace_abc123",
    },
    json={"area_code": "602"},
    timeout=60,
)
number = response.json()["data"]
print(number["phone_number_id"], number["display_number"])

201 Created (shortened)

{
  "status": "success",
  "data": {
    "phone_number_id": "phone_abc123",
    "display_number": "+15555550100",
    "status": "active",
    "access_type": "dedicated",
    "send_status": { "allowed": true }
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-28T17:00:00.000Z"
}

The number is ready to send. The full response also has its limits, health and capabilities, like GET /v1/phone-numbers. Full reference: Assign a phone number. The area code is matched exactly, never swapped for a nearby one. If none is free, 409 AREA_CODE_UNAVAILABLE lists the area codes that are in error.details[0].available_area_codes.

See a customer’s numbers

curl

curl https://api.blujay.io/v1/phone-numbers \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Blujay-Workspace: workspace_abc123"

Each number shows whether it can send right now, its limits and its health. See Phone numbers and limits.

Release a number

curl -X DELETE https://api.blujay.io/v1/phone-numbers/phone_abc123 \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Blujay-Workspace: workspace_abc123"

const response = await fetch("https://api.blujay.io/v1/phone-numbers/phone_abc123", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.BLUJAY_API_KEY}`,
    "Blujay-Workspace": "workspace_abc123",
  },
});
const released = (await response.json()).data;
console.log(released.quiet_until);

import os
import requests

response = requests.delete(
    "https://api.blujay.io/v1/phone-numbers/phone_abc123",
    headers={
        "Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}",
        "Blujay-Workspace": "workspace_abc123",
    },
    timeout=60,
)
print(response.json()["data"]["quiet_until"])

The response is the number with released_at and quiet_until. Until quiet_until the customer keeps the history and still receives texts on the number, but can’t send from it. Then the number retires for good. Full reference: Release a phone number.

Limits

Limit	Default
New numbers per UTC day	3
New numbers per calendar month	10
Quiet period after a release	30 days

Over a daily or monthly limit, assigning returns 429 with error.details[0].scope partner. Need more? Ask Blujay support.

Confirm with webhooks

Event	When
`phone_number.assigned`	The customer got a number.
`phone_number.released`	You released a number.
`phone_number.status_updated`	A number’s ability to send changed.

See the payloads on Webhook events.

Good to know

Retry safely. Send an Idempotency-Key on assign; a repeat returns the number it assigned first.
Queued texts wait. Scheduled and queued texts on a released number don’t send.
Releasing twice is safe. A number that’s already released comes back unchanged.
No numbers free? Assigning returns 409 NO_PHONE_NUMBERS_AVAILABLE; try again later or ask support.

Guides

Partner phone numbers

Assign a number

See a customer’s numbers

Release a number

Limits

Confirm with webhooks

Good to know

Next steps

Partner webhooks

Phone numbers and limits

​Assign a number

​See a customer’s numbers

​Release a number

​Limits

​Confirm with webhooks

​Good to know

​Next steps

Partner webhooks

Phone numbers and limits

Assign a number

See a customer’s numbers

Release a number

Limits

Confirm with webhooks

Good to know

Next steps