Partner Accounts - Blujay API

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.

Partner accounts only. Ask Blujay support to make your workspace a partner and issue your partner keys.

Your first customer in three calls

1. Create the customer

curl

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" }'

201 Created

{
  "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

curl

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.

3. Send as the customer

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

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." }] } }'

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);

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. Then subscribe to 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.

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

Rate limits

Each customer gets the normal rate limits. 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

Customers and teammates

Create and list customers, and add the people who text.

Phone numbers

Give a customer a dedicated number, and release it.

Partner webhooks

One endpoint for every customer’s events.

Embedded view

Show a customer’s texts inside your product.

​Your first customer in three calls

​1. Create the customer

​2. Give it a number

​3. Send as the customer

​The Blujay-Workspace header

​Key roles

​Rate limits

​Good to know

​Partner guides

Customers and teammates

Phone numbers

Partner webhooks

Embedded view

Your first customer in three calls

1. Create the customer

2. Give it a number

3. Send as the customer

The `Blujay-Workspace` header

Key roles

Rate limits

Good to know

Partner guides