Agency Inbound API

Provision sub-accounts from your own system. Create a client, change which channels they can use, and remove them — without opening the GetRaze agency panel.

This API is for whitelabel agencies. Each agency gets its own endpoint and its own tokens.

Different from the rest of this reference

The Agency Inbound API does not use X-API-Key or the https://app.getraze.com/external/v1 base URL. It has its own base URL, its own Bearer token and its own permission scopes, all described below.

Base URL

https://api.getraze.co/api/webhooks/agency/<agency_key>

agency_key identifies your agency. It is public — not a secret — and it never changes, so an integration you publish today keeps working after you rename your agency or change your subdomain.

Find your endpoint and manage your tokens in the agency panel, under API & Webhooks.

Authentication

Send your token in the Authorization header. Never put it in the URL — URLs end up in proxy and CDN logs.

Authorization: Bearer raz_ag_live_xxxxxxxxxxxxxxxx

A token only works on the endpoint of the agency that owns it. Using it on another agency's URL returns 401.

Scopes

Each token carries a set of scopes. Calling an operation without its scope returns 403 INVALID_SCOPE.

Scope	Allows	Granted by default
sub_account.create	Create sub-accounts	Yes
sub_account.channels	Change channel quotas	Yes
sub_account.delete	Delete sub-accounts	Yes
sub_account.credentials	Receive the admin's temporary password in the response	No

Grant sub_account.credentials only if your system really needs the password. Without it, the new admin receives a welcome email with their access instead.

Idempotency

Send a unique Idempotency-Key header on every write. If the same key arrives twice for the same agency, we return the result of the first execution instead of running the operation again.

Idempotency-Key: 8f14e45f-ea4d-4a2c-9f34-1c7b0a2e5d31

Without the key, every call is a brand-new operation — retrying a request that timed out could create a second sub-account.

A replayed call responds with replayed: true:

{
  "ok": true,
  "replayed": true,
  "event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83",
  "data": { "id": "a1b2c3d4-5678-4e9f-a0b1-c2d3e4f5a6b7" }
}

TIP

A replay returns the stored result. The admin's temporary password is never stored, so it is not present on a replay — only on the first response.

Identifying a sub-account

Routes that act on an existing sub-account accept two forms:

Form	Example	Notes
Our UUID	a1b2c3d4-5678-4e9f-a0b1-c2d3e4f5a6b7	Returned when you create it
Your own ID	ext:client-42	Requires external_ref sent at creation

ext: lets your CRM keep using its own identifier. external_ref is unique per agency among live sub-accounts — deleting one frees the reference for reuse.

Channels

Channel quotas are expressed as a plain object:

{ "linkedin": 2, "whatsapp": 1 }

Channel	Meaning
linkedin	LinkedIn accounts the client can connect
whatsapp	WhatsApp numbers
instagram	Instagram accounts
email_marketing	Email sending domains

Values are integers from 0 to 100.

The object is declarative

channels describes the final state, not a delta. A channel you omit goes to zero. To keep WhatsApp while raising LinkedIn, send both.

Adding billable channels charges your agency immediately on the card on file, pro-rata to the end of the current cycle. Removing them does not generate a credit.

Response format

Every response carries ok and, for writes, the event_id of the recorded call.

Success

{
  "ok": true,
  "event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83",
  "data": { }
}

Error

{
  "ok": false,
  "code": "EMAIL_ALREADY_REGISTERED",
  "message": "This email is already registered to another account.",
  "event_id": "3f7b1c2e-9a44-4d1b-8f2e-6c5a1b0d9e83"
}

Use event_id to look the call up later — see Retrieve an event — or to find it in the Events tab of the agency panel.

Retries

A call that fails for a transient reason (a database or payment-gateway timeout) is retried automatically in the background, up to five attempts with exponential backoff. Those respond 500 INTERNAL and stay visible as pending until they settle.

Business errors — a duplicate email, a declined card, a missing field — are not retried. Fix the cause and either send a new call with a new Idempotency-Key, or press Reprocess on the event in the agency panel.

Rate limits

Limit	Scope	Response
300 requests/minute	Per IP address	429 RATE_LIMIT_IP
60 requests/minute	Per token	429 RATE_LIMIT_API
5 sub-accounts/hour	Per agency	429 RATE_LIMIT_SUBACCOUNT_CREATE

Request bodies are capped at 64 KB.

Tokens can optionally be restricted to a list of IP addresses. Calls from anywhere else return 403 IP_NOT_ALLOWED.

Using no-code tools

Make, n8n, Zapier and similar tools often cannot send DELETE or a PUT with a body. Every operation has a POST alias:

Operation	Canonical	POST alias
Update channels	PUT /sub-accounts/:ref/channels	POST /sub-accounts/:ref/channels
Delete sub-account	DELETE /sub-accounts/:ref	POST /sub-accounts/:ref/delete

Both forms behave identically and require the same scope.

Errors

Status	Code	Description
400	MISSING_FIELDS	A required field is absent
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
400	CONFIRMATION_REQUIRED	Deletion without "confirm": true
401	UNAUTHORIZED	Missing, unknown, revoked or wrong-agency token
402	NO_PAYMENT_METHOD	The agency has no card on file
402	SEAT_CHARGE_FAILED	The pro-rata charge was declined
403	INVALID_SCOPE	The token lacks the scope for this operation
403	IP_NOT_ALLOWED	Caller IP is not in the token's allowlist
403	AGENCY_NOT_APPROVED	The agency has not been approved yet
403	AGENCY_SUSPENDED	The agency is suspended for non-payment
403	AGENCY_CANCELLED	The agency has been cancelled
403	AGENCY_INACTIVE	The account is not an active agency
403	SUB_ACCOUNT_FORBIDDEN	The sub-account belongs to another agency
404	SUB_ACCOUNT_NOT_FOUND	No live sub-account for that reference
404	EVENT_NOT_FOUND	No event with that id for this agency
409	EMAIL_ALREADY_REGISTERED	The admin email is already in use
409	EXTERNAL_REF_ALREADY_USED	Another live sub-account already uses that external_ref
409	IN_PROGRESS	A call with this Idempotency-Key is still running
429	RATE_LIMIT_IP	Too many requests from this IP
429	RATE_LIMIT_API	Too many requests for this token
429	RATE_LIMIT_SUBACCOUNT_CREATE	More than 5 sub-accounts in one hour
500	INTERNAL	Transient failure; the call will be retried automatically