> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner phone numbers

> Assign a dedicated number to a customer, and release it when you're done.

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.

> [!NOTE]
>
> **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.

```bash curl theme={null}
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" }'
```

```javascript Node.js theme={null}
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);
```

```python Python theme={null}
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"])
```

```json 201 Created (shortened) theme={null}
{
  "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`](https://docs.blujay.io/phone-numbers). Full reference: [Assign a phone number](https://docs.blujay.io/api-reference/phone-numbers/assign-a-phone-number-reseller-partners).

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

```bash curl theme={null}
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](https://docs.blujay.io/phone-numbers.md).

## Release a number

```bash curl theme={null}
curl -X DELETE https://api.blujay.io/v1/phone-numbers/phone_abc123 \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Blujay-Workspace: workspace_abc123"
```

```javascript Node.js theme={null}
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);
```

```python Python theme={null}
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](https://docs.blujay.io/api-reference/phone-numbers/release-a-phone-number-reseller-partners).

## 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](https://docs.blujay.io/support.md).

## 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](https://docs.blujay.io/webhooks/events.md).

## 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.

## Next steps

> [card] [Partner webhooks](https://docs.blujay.io/partners/webhooks)
>
> One endpoint for every customer's events.

> [card] [Phone numbers and limits](https://docs.blujay.io/phone-numbers.md)
>
> Sending limits and health for each number.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.