Engage / API v1
Clientes

Criar cliente

Cadastra um novo cliente vinculado à empresa dona da chave de API.

POST/v1/customers

Cria um cliente com os dados informados. Apenas name e email são obrigatórios. Os campos status e preferredChannel aceitam apenas valores específicos dos enums listados abaixo.

Obrigatório

name e email são obrigatórios. Os demais campos do body são opcionais.

Exemplo mínimo

json
{
  "name": "Maria Silva",
  "email": "maria@exemplo.com"
}

Exemplo completo

json
{
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "+5511999990000",
  "status": "vip",
  "preferredChannel": "whatsapp",
  "tags": ["vip", "recorrente"],
  "location": "São Paulo, SP",
  "company": "Acme Ltda.",
  "birthDate": "1990-05-15",
  "customFields": {
    "loyalty_tier": "gold",
    "source": "indicacao"
  }
}

Parâmetros do body

  • namestringobrigatório
    Nome do cliente.
  • emailstringobrigatório
    E-mail válido.
  • phonestringopcional
    Telefone do cliente. Recomendado o formato E.164 (ex.: +5511999999999).
  • statusstringopcional
    Aceita apenas active, inactive, vip ou churned.
  • preferredChannelstringopcional
    Aceita apenas email, whatsapp, sms ou phone.
  • tagsstring[]opcional
    Lista de tags. Cada tag é uma string livre.
  • locationstringopcional
    Cidade ou região do cliente.
  • companystringopcional
    Empresa do cliente.
  • birthDatestring (ISO 8601)opcional
    Data de nascimento. Aceita apenas formato ISO (ex.: 1990-05-15).
  • customFieldsobjectopcional
    Mapa { <nome do campo>: valor } com os campos customizados da entidade Cliente. Chaves desconhecidas retornam 400 Bad Request. Veja campos customizados.

Campos da resposta

  • idstring (uuid)opcional
    Identificador único gerado pelo Engage.
  • namestringopcional
    Nome enviado.
  • emailstringopcional
    E-mail enviado.
  • phonestring | nullopcional
    Telefone enviado, ou null se omitido.
  • statusstringopcional
    Valor enviado.
  • preferredChannelstringopcional
    Valor enviado.
  • tagsstring[]opcional
    Tags enviadas, ou array vazio.
  • locationstring | nullopcional
    Localização enviada, ou null se omitida.
  • companystring | nullopcional
    Empresa enviada, ou null se omitida.
  • birthDatestring (ISO 8601) | nullopcional
    Data de nascimento enviada em ISO completo, ou null.
  • createdAtstring (ISO 8601)opcional
    Data e hora de cadastro.

Possíveis erros

  • 400
    Unknown custom fields: <nomes>Alguma chave do customFields não corresponde a um campo cadastrado para a entidade Cliente.
  • 400
    ValidaçãoBody inválido: name/email ausentes, e-mail mal formatado, status ou preferredChannel fora dos enums, birthDate em formato inválido, etc.
  • 401
    Invalid API keyHeader x-api-key ausente, inválido ou revogado.