Endpoint responsável por consultar os clientes cadastrados na conta de forma paginada, com possibilidade de aplicação de filtros.

Essa chamada é utilizada principalmente para localização de cadastros existentes, validação de duplicidade e apoio a rotinas de sincronização entre o Asaas e sistemas externos.

Funcionamento da paginação

A listagem de clientes é paginada.

A API retorna os registros em blocos, respeitando os parâmetros de navegação enviados na requisição, garantindo eficiência mesmo em contas com grande volume de dados.

Parâmetros principais da requisição

• offset — Define o ponto inicial da lista
• limit — Define a quantidade máxima de registros (máximo de 100)
• name — Filtra por nome
• email — Filtra por e-mail
• cpfCnpj — Filtra por documento
• groupName — Filtra por grupo
• externalReference — Filtra por identificador do sistema de origem

Casos de uso mais comuns

• validação da existência antes da criação
• localização de clientes por documento ou referência
• sincronização de dados entre sistemas
• exibição em interfaces administrativas

Uso para prevenção de duplicidade

Como a API não impede cadastros duplicados, esse endpoint é uma das principais ferramentas para controle prévio antes da criação.

🚧

Atenção

Recomenda-se realizar a consulta antes da criação para evitar múltiplos registros representando o mesmo cliente.

Uso recomendado em sincronizações

A combinação de externalReference e cpfCnpj tende a gerar resultados mais confiáveis do que buscas apenas por nome.