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

> Run many Blujay customers through one integration with one key.

Resell Blujay inside your own product. Each of your customers gets its own Blujay workspace, with its own numbers, contacts, opt-outs, limits and teammates. You run all of them with one partner key, one webhook endpoint and one invoice.

> [!NOTE]
>
> **Partner accounts only.** Ask [Blujay support](https://docs.blujay.io/support.md) to make your workspace a partner and issue your partner keys.

## Your first customer in three calls

### 1. Create the customer

```bash curl theme={null}
curl -X POST https://api.blujay.io/v1/partner/customers \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Co", "external_reference": "crm-4411" }'
```

```json 201 Created theme={null}
{
  "status": "success",
  "data": {
    "id": "workspace_abc123",
    "name": "Acme Co",
    "email": null,
    "external_reference": "crm-4411",
    "status": "active",
    "is_development": false,
    "created_at": "2026-10-28T17:00:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-28T17:00:00.000Z"
}
```

Keep `data.id`. It's the customer ID you send in the `Blujay-Workspace` header from now on.

### 2. Give it a 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" }'
```

The response is the new number, with `phone_number_id` and `display_number`. It's ready to send right away. See [Phone numbers](https://docs.blujay.io/partners/phone-numbers).

### 3. Send as the customer

The same request any Blujay customer makes, plus the header.

```bash curl theme={null}
curl -X POST https://api.blujay.io/v1/chats \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Blujay-Workspace: workspace_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "to": ["+15555550101"], "message": { "parts": [{ "type": "text", "text": "Hi Ava, your appointment is confirmed." }] } }'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.blujay.io/v1/chats", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLUJAY_API_KEY}`,
    "Blujay-Workspace": "workspace_abc123",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["+15555550101"],
    message: { parts: [{ type: "text", text: "Hi Ava, your appointment is confirmed." }] },
  }),
});
console.log(response.status, (await response.json()).data);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.blujay.io/v1/chats",
    headers={
        "Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}",
        "Blujay-Workspace": "workspace_abc123",
    },
    json={
        "to": ["+15555550101"],
        "message": {"parts": [{"type": "text", "text": "Hi Ava, your appointment is confirmed."}]},
    },
    timeout=60,
)
print(response.status_code, response.json()["data"])
```

Blujay answers `202 Accepted`, the same as [Send messages](https://docs.blujay.io/messaging/send-messages.md). Then [subscribe to webhooks](https://docs.blujay.io/partners/webhooks) once to get every customer's replies and delivery updates.

## The `Blujay-Workspace` header

With the header, a request runs as that customer, exactly as if it had its own key. Every page in these docs works this way: contacts, chats, attachments, phone numbers. Without the header, a partner key reaches only your partner calls (`/v1/partner/...`) and `/v1/me`.

## Key roles

| Role | Can do |
| - | - |
| `admin` | Everything: create customers, add teammates, assign and release numbers, manage your webhook subscription, and all messaging. |
| `messaging` | Read anything for a customer, and send and change chats, messages, contacts, attachments and contact cards. Open the [embedded view](https://docs.blujay.io/partners/embedded-view). |

Give your app servers a `messaging` key and keep the `admin` key for setup.

## Rate limits

Each customer gets the normal [rate limits](https://docs.blujay.io/rate-limits.md). All your customers together get ten times one customer's limits. A `429` says which you hit in `error.details[0].scope`: `partner_customer` (one customer) or `partner` (your total).

## Good to know

* **One key, not one per customer.** A new customer works the moment you create it; there's no key to issue or store.
* **A customer that isn't yours returns `404`.** So does a malformed ID. Check the header first when you get one.
* **Paused or closing customers are read-only.** Blujay pauses or closes a customer when you ask. Changes then return `409 CUSTOMER_PAUSED` or `CUSTOMER_CLOSING`.
* **Your customers never sign in to Blujay.** No emails or invites go to them or their teammates.
* **Numbers are billed to you,** not to your customers.

## Partner guides

> [card] [Customers and teammates](https://docs.blujay.io/partners/customers)
>
> Create and list customers, and add the people who text.

> [card] [Phone numbers](https://docs.blujay.io/partners/phone-numbers)
>
> Give a customer a dedicated number, and release it.

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

> [card] [Embedded view](https://docs.blujay.io/partners/embedded-view)
>
> Show a customer's texts inside your product.


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