Engage / API v1
Quickstart

Primeira requisição

Em três passos você vai buscar um cliente, criar um novo e confirmar que ele existe — usando apenas cURL. Copie os exemplos, troque os valores de exemplo pelos seus e rode direto no terminal.

Antes de começar

Você vai precisar de uma chave de API

Todos os endpoints /v1 são autenticados pelo header x-api-key. Se ainda não tem uma chave, gere pelo painel antes de continuar.

Como gerar uma chave →
Exporte a chave para uma variável de ambiente
Os exemplos usam $ENGAGE_API_KEY. No seu terminal, rode export ENGAGE_API_KEY="sk_live_..." antes de executar os comandos.
01

Buscar um cliente existente

Primeiro, veja como a API devolve os dados de um cliente. Faça GET /v1/customers/id/:id passando o ID de qualquer cliente cadastrado na sua conta.

Requisição
bash
curl https://api.engage.app/v1/customers/id/c3a1b2d4-9f5e-4a8b-9c0d-1e2f3a4b5c6d \
  -H "x-api-key: $ENGAGE_API_KEY"
Resposta · 200 OK
json
{
  "id": "c3a1b2d4-9f5e-4a8b-9c0d-1e2f3a4b5c6d",
  "name": "Ana Souza",
  "email": "ana@exemplo.com",
  "phone": "+5511988887777",
  "status": "active",
  "preferredChannel": "whatsapp",
  "tags": ["recorrente"],
  "location": "Curitiba, PR",
  "company": "Acme Ltda.",
  "birthDate": "1988-03-22T00:00:00.000Z",
  "createdAt": "2025-11-02T14:20:00.000Z",
  "customFields": {
    "loyalty_tier": "silver",
    "source": "indicacao"
  }
}

O payload de retorno inclui os dados principais do cliente e o bloco customFields, que traz os campos customizados configurados para a entidade Cliente.

02

Criar um novo cliente

Agora crie um cliente enviando um POST /v1/customers com um body JSON. Apenas name e email são obrigatórios — os demais campos são opcionais.

Requisição
bash
curl -X POST https://api.engage.app/v1/customers \
  -H "x-api-key: $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "phone": "+5511999990000",
    "status": "active",
    "preferredChannel": "whatsapp",
    "tags": ["vip", "recorrente"],
    "location": "São Paulo, SP",
    "birthDate": "1990-05-15"
  }'
Resposta · 201 Created
json
{
  "id": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "+5511999990000",
  "status": "active",
  "preferredChannel": "whatsapp",
  "tags": ["vip", "recorrente"],
  "location": "São Paulo, SP",
  "company": null,
  "birthDate": "1990-05-15T00:00:00.000Z",
  "createdAt": "2026-04-24T12:34:56.000Z"
}

A resposta devolve o cliente criado com id e createdAt gerados pelo servidor. Copie o id retornado — você vai usá-lo no próximo passo.

Valores aceitos nos enums
status aceita active, inactive, vip ou churned. preferredChannel aceita email, whatsapp, sms ou phone. Enviar qualquer outro valor retorna 400 Bad Request.
03

Confirmar que o cliente foi criado

Use o mesmo endpoint do passo 1 com o id recebido na resposta do passo 2. Se tudo certo, você verá o cliente que acabou de criar.

Requisição
bash
curl https://api.engage.app/v1/customers/id/f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f \
  -H "x-api-key: $ENGAGE_API_KEY"
Resposta · 200 OK
json
{
  "id": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "+5511999990000",
  "status": "active",
  "preferredChannel": "whatsapp",
  "tags": ["vip", "recorrente"],
  "location": "São Paulo, SP",
  "company": null,
  "birthDate": "1990-05-15T00:00:00.000Z",
  "createdAt": "2026-04-24T12:34:56.000Z",
  "customFields": {}
}

O cliente criado no passo 2 aparece exatamente como enviado. customFields vem vazio porque ainda não definimos nenhum — veja campos customizados para aprender como estender a entidade.

Próximos passos

Continue a integração