Contatos

Módulo

Cadastre, consulte e mova contatos dentro do funil do CRM.

GETListar contatos/contacts GETConsultar contato/contacts/:id POSTCriar ou atualizar contato/contacts PATCHAtualizar contato/contacts/:id

GET/contactsEscopo: readOficial + Básico

Lista contatos da conta autenticada.

Use para alimentar CRMs externos, sincronizar bases e buscar contatos por etapa.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`stage_id`opcional	uuid	Filtra contatos por uma etapa do funil.
`connection_id`opcional	uuid	Filtra pela conexão WhatsApp dona da identidade.
`phone`opcional	string	Filtra por telefone com DDI (somente dígitos são considerados).
`username`opcional	string	Filtra pelo identificador externo persistido no contato.
`business_scoped_user_id`opcional	string	Filtra pela identidade BSUID recebida da Meta.
`parent_business_scoped_user_id`opcional	string	Filtra pelo parent BSUID recebido da Meta.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Lista retornada com paginação.
401	Chave ausente ou inválida.
403	A chave não possui escopo read.

Exemplo de resposta

{
  "data": [
    {
      "id": "<CONTACT_ID>",
      "name": "Maria Silva",
      "phone": "5511999998888",
      "username": "maria",
      "stage_id": "<STAGE_ID>",
      "created_at": "2026-06-15T12:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 134,
    "next_offset": 20
  }
}

GET/contacts/:idEscopo: readOficial + Básico

Consulta um contato com jornada e vendas.

Retorna dados do contato, sessões de origem Signal e vendas relacionadas às conversas desse contato.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID do contato.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Contato encontrado.
404	Contato não encontrado nesta conta.

Exemplo de resposta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Maria Silva",
    "phone": "5511999998888",
    "username": "maria",
    "stage_id": "<STAGE_ID>",
    "sessions": [
      {
        "channel": "meta",
        "utm_source": "facebook",
        "utm_campaign": "campanha-principal",
        "ad_id": "23800000000000000",
        "landing_url": "https://sua-pagina.com/oferta"
      }
    ],
    "sales": [
      {
        "id": "91c9fd84-b47f-44ee-9b5e-4e93fc35b912",
        "status": "paid",
        "gross_cents": 19700,
        "currency": "BRL",
        "product_name": "Produto principal"
      }
    ]
  }
}

POST/contactsEscopo: writeOficial + Básico

Cria ou atualiza contato por identidade.

Informe ao menos uma identidade: phone, username, business_scoped_user_id ou parent_business_scoped_user_id. O telefone é normalizado apenas com dígitos. Identidades Meta (username/BSUID) exigem connection_id. Se a identidade já existir, a API atualiza os campos enviados.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`phone`opcional	string	Telefone com DDI, somente números. Obrigatório quando nenhuma outra identidade for enviada.
`connection_id`opcional	uuid	Conexão dona da identidade. Obrigatório com username, BSUID ou parent BSUID.
`name`opcional	string	Nome exibido no CRM, até 120 caracteres.
`username`opcional	string	Identificador externo ou usuário social.
`business_scoped_user_id`opcional	string	BSUID recebido da Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID recebido da Meta.
`stage_id`opcional	uuid	Etapa inicial do funil. Precisa pertencer à conta.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/contacts" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "phone": "5511999998888",
  "name": "Joao Silva",
  "username": "joao",
  "stage_id": "<STAGE_ID>"
}'

Respostas

201	Contato criado.
200	Contato existente atualizado.
422	phone ausente ou stage_id inválido.

Exemplo de resposta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  },
  "created": true
}

PATCH/contacts/:idEscopo: writeOficial + Básico

Atualiza dados ou move o contato de etapa.

Envie somente os campos que deseja alterar. stage_id é validado contra as etapas da conta. As identidades WhatsApp (phone, BSUID, parent BSUID) também podem ser completadas por aqui.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID do contato.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`name`opcional	string	Novo nome do contato.
`phone`opcional	string	Novo telefone com DDI (somente dígitos).
`username`opcional	string	Novo identificador externo.
`business_scoped_user_id`opcional	string	BSUID recebido da Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID recebido da Meta.
`stage_id`opcional	uuid	Nova etapa do funil.

Exemplos prontos

curl -X PATCH "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "stage_id": "<STAGE_ID>",
  "name": "Joao Silva"
}'

Respostas

200	Contato atualizado.
404	Contato não encontrado.
422	stage_id não pertence à conta.

Exemplo de resposta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  }
}