Criar Sub-Conta

Cria uma sub-conta de cliente sob a sua agencia, com o usuario admin e as cotas de canais.

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

Autenticacao

Requer token Bearer com o escopo sub_account.create. Veja API de Entrada da Agencia.

Cabecalhos

Cabecalho	Obrigatorio	Descricao
Authorization	Sim	Bearer <seu token>
Idempotency-Key	Recomendado	Unico por chamada. Impede que uma retentativa crie uma segunda sub-conta.

Corpo da Requisicao

Campo	Tipo	Obrigatorio	Descricao
name	string	Sim	Nome do cliente
admin_email	string	Sim	E-mail do usuario admin. Nao pode existir em nenhuma conta da GetRaze.
admin_name	string	Nao	Nome de exibicao do admin. Padrao: o proprio e-mail.
external_ref	string	Nao	O seu ID para este cliente, ate 120 caracteres. Permite enderecar a sub-conta como ext:<valor> depois.
channels	object	Nao	Cotas de canais. Omitido significa nenhum canal — e nenhuma cobranca.
include_credentials	boolean	Nao	Devolve a senha temporaria do admin. Requer o escopo sub_account.credentials.

Objeto channels

Campo	Tipo	Descricao
linkedin	number	Contas de LinkedIn permitidas (0–100)
whatsapp	number	Numeros de WhatsApp permitidos (0–100)
instagram	number	Contas de Instagram permitidas (0–100)
email_marketing	number	Dominios de envio permitidos (0–100)

Todo canal omitido nasce desabilitado. Canais cobraveis sao cobrados da sua agencia pro-rata na criacao.

Resposta

{
  "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": "cliente-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
  }
}

Com include_credentials: true, a resposta traz tambem temporary_password. O admin e obrigado a troca-la no primeiro login.

WARNING

temporary_password nunca e armazenada. Ela aparece apenas nesta primeira resposta — uma repeticao da mesma Idempotency-Key nao a contera.

Exemplo

cURL

curl --request POST \
  --url "https://api.getraze.co/api/webhooks/agency/AGENCY_KEY/sub-accounts" \
  --header "Authorization: Bearer SEU_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": "cliente-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: 'cliente-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': 'cliente-42',
        'channels': {'linkedin': 2, 'whatsapp': 1}
    }
)
data = response.json()

Erros

Status	Codigo	Descricao
400	MISSING_FIELDS	name ou admin_email esta ausente
400	INVALID_CHANNELS	Canal desconhecido, ou valor fora de 0–100
400	INVALID_EXTERNAL_REF	external_ref nao e string de ate 120 caracteres
401	UNAUTHORIZED	Token ausente, desconhecido ou revogado
402	NO_PAYMENT_METHOD	A agencia nao tem cartao cadastrado
403	INVALID_SCOPE	Falta sub_account.create, ou sub_account.credentials para include_credentials
409	EMAIL_ALREADY_REGISTERED	admin_email ja esta em uso
409	EXTERNAL_REF_ALREADY_USED	Outra sub-conta viva ja usa esse external_ref
429	RATE_LIMIT_SUBACCOUNT_CREATE	Mais de 5 sub-contas em uma hora