Create Sub-Account

Create a client sub-account under your agency, with its admin user and channel quotas.

POST /api/webhooks/agency/:agency_key/sub-accounts

Authentication

Requires a Bearer token with the sub_account.create scope. See Agency Inbound API.

Headers

Header	Required	Description
Authorization	Yes	Bearer <your token>
Idempotency-Key	Recommended	Unique per call. Prevents a retry from creating a second sub-account.

Request Body

Field	Type	Required	Description
name	string	Yes	Client name
admin_email	string	Yes	Email of the admin user. Must not exist anywhere in GetRaze.
admin_name	string	No	Admin's display name. Defaults to the email.
external_ref	string	No	Your own ID for this client, up to 120 characters. Lets you address the sub-account as ext:<value> later.
channels	object	No	Channel quotas. Omitted means no channels — and no charge.
include_credentials	boolean	No	Return the admin's temporary password. Requires the sub_account.credentials scope.

channels Object

Field	Type	Description
linkedin	number	LinkedIn accounts allowed (0–100)
whatsapp	number	WhatsApp numbers allowed (0–100)
instagram	number	Instagram accounts allowed (0–100)
email_marketing	number	Email sending domains allowed (0–100)

Any channel you omit is created disabled. Billable channels are charged to your agency pro-rata on creation.

Response

{
  "ok": true,
  "event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83",
  "data": {
    "id": "a1b2c3d4-5678-4e9f-a0b1-c2d3e4f5a6b7",
    "name": "Acme Marketing",
    "slug": "acme-marketing-9f2c1a",
    "external_ref": "client-42",
    "created_at": "2026-07-28T14:22:00Z",
    "admin": {
      "id": "b7c8d9e0-1234-4f5a-b6c7-d8e9f0a1b2c3",
      "email": "admin@acme.com"
    },
    "channels": {
      "linkedin": 2,
      "whatsapp": 1,
      "instagram": 0,
      "email_marketing": 0
    },
    "billing": {
      "invoiceStatus": "paid",
      "totalCents": 24900,
      "currency": "BRL",
      "periodEnd": "2026-08-15T00:00:00Z",
      "items": [
        { "channelType": "linkedin", "count": 2 },
        { "channelType": "whatsapp", "count": 1 }
      ]
    },
    "trial": null
  }
}

With include_credentials: true, the response also carries temporary_password. The admin is required to change it on first login.

WARNING

temporary_password is never stored. It appears only in this first response — a replay of the same Idempotency-Key will not contain it.

Example

cURL

curl --request POST \
  --url "https://api.getraze.co/api/webhooks/agency/AGENCY_KEY/sub-accounts" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "name": "Acme Marketing",
    "admin_email": "admin@acme.com",
    "admin_name": "Jamie Rivera",
    "external_ref": "client-42",
    "channels": { "linkedin": 2, "whatsapp": 1 }
  }'

JavaScript

const response = await fetch(
  `https://api.getraze.co/api/webhooks/agency/${agencyKey}/sub-accounts`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      name: 'Acme Marketing',
      admin_email: 'admin@acme.com',
      admin_name: 'Jamie Rivera',
      external_ref: 'client-42',
      channels: { linkedin: 2, whatsapp: 1 }
    })
  }
);
const data = await response.json();

Python

import requests, uuid

response = requests.post(
    f'https://api.getraze.co/api/webhooks/agency/{agency_key}/sub-accounts',
    headers={
        'Authorization': f'Bearer {token}',
        'Idempotency-Key': str(uuid.uuid4())
    },
    json={
        'name': 'Acme Marketing',
        'admin_email': 'admin@acme.com',
        'admin_name': 'Jamie Rivera',
        'external_ref': 'client-42',
        'channels': {'linkedin': 2, 'whatsapp': 1}
    }
)
data = response.json()

Errors

Status	Code	Description
400	MISSING_FIELDS	name or admin_email is missing
400	INVALID_CHANNELS	Unknown channel, or a value outside 0–100
400	INVALID_EXTERNAL_REF	external_ref is not a string of up to 120 characters
401	UNAUTHORIZED	Missing, unknown or revoked token
402	NO_PAYMENT_METHOD	The agency has no card on file
403	INVALID_SCOPE	Token lacks sub_account.create, or sub_account.credentials for include_credentials
409	EMAIL_ALREADY_REGISTERED	admin_email is already in use
409	EXTERNAL_REF_ALREADY_USED	Another live sub-account already uses that external_ref
429	RATE_LIMIT_SUBACCOUNT_CREATE	More than 5 sub-accounts in one hour