Consultar usuário

Depois de cadastrar ou atualizar usuários, a sua integração precisa conferir o que foi gravado. Este artigo mostra como consultar um usuário específico ou listar os usuários da instância — e os dois detalhes que mais confundem: paginação e o retorno quando nada é encontrado.

Antes de começar

• As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage, e um token gerado em Passo 2 — Obtendo o access_token (POST /auth).
• Estes endpoints não exigem permissão específica — basta estar autenticado.
• Teste em homologação: https://sandbox.engage.bz/api/v1.

Consultar um usuário

GET https://sandbox.engage.bz/api/v1/{customer_id}/users/{user_id}
Authorization: Bearer {access_token}

O user_id é o ID do usuário na Engage — o mesmo que volta no campo object_id quando você cadastra o usuário.

Resposta da consulta de um usuário de teste no Postman: ID, nome, e-mail, login e situação

A resposta vem dentro de result (valores ilustrativos):

{
  "result": {
    "user_id": 415322,
    "name": "João da Silva",
    "email": "joao.silva@suaempresa.com",
    "login": "joao.silva",
    "external_code": "mat-0001",
    "status": true,
    "blocked": false,
    "groups": [
      {
        "group_id": 9518,
        "name": "Departamento de Vendas",
        "external_code": "depto-vendas",
        "status": true,
        "competition_groups": [ { "competition_id": 21439, "group_id": 9518 } ]
      }
    ]
  }
}

Cada item de groups é um grupo do usuário. Dentro dele, competition_groups lista os ambientes ligados àquele grupo.

Listar usuários

GET https://sandbox.engage.bz/api/v1/{customer_id}/users?skip=0&take=20&status=active&search=joao
Authorization: Bearer {access_token}

Parâmetros da listagem de usuários no Postman: skip, take, status e search

Quando nada é encontrado

A consulta sem resultado responde HTTP 404 com "error_code": "not_found" — não HTTP 200 com lista vazia. Trate esse 404 como "nenhum resultado", e não como falha da integração.

Boas práticas

• Guarde o user_id. Ele volta no object_id do cadastro e evita buscas por texto depois.
• Tem só o seu código de usuário? Use o external_code no search da listagem.
• Precisa da base inteira? A listagem paginada não é o melhor caminho para extrações em massa. Use o relatório de usuários, descrito em API - Relatórios.

Problemas comuns