---
updatedAt: 2025-09-29T22:39:04.000Z
agentTools:
projectIndex: https://docs.bankly.com.br/llms.txt
---
# Consulta do registro do cliente
stable
Este *endpoint* retorna os dados de registro de um cliente pessoa física.
## Requisição (Request)
### Requisição HTTP
```http
GET https://api-mtls.sandbox.bankly.com.br/customers/{documentNumber}?resultLevel={resultLevel}
```
```curl
--request GET \
--url 'https://api-mtls.sandbox.bankly.com.br/customers/47742663023?resultLevel=BASIC' \
--header 'api-version: 1' \
--header 'Authorization: Bearer {{accessToken}}'
```
### Autorização
Para garantir a segurança nas requisições, todos os *endpoints* do Bankly utilizam *[scopes](https://docs.bankly.com.br/docs/scopes)* como parte do seu [fluxo de autorização](https://docs.bankly.com.br/docs/fluxos-autorizacao).
Esta requisição requer o *scope* descrito a seguir:
| Scope | Descrição |
| --------------- | --------------------------------------------------------------------- |
| `customer.read` | Concede acesso para consultar o registro de um cliente pessoa física. |
### Cabeçalhos (Headers)
| Nome | Descrição |
| --------------- | ----------------------------------------------------------------- |
| `api-version` | **Obrigatório**. Versão da API. Atualmente estamos na versão 1.0. |
| `Authorization` | **Obrigatório**. Token de autorização do tipo Bearer. |
### Parâmetros da rota (Path)
No *path* desta requisição envie os seguintes campos:
| Nome | Tipo | Descrição | Especificação |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |
| `documentNumber` | `path` | **Obrigatório**. Número do documento do cliente (CPF). | Informe somente números. |
| `resultLevel` | `query` | Nível de informações a serem exibidas, que pode ser "BASIC", para um resumo, ou "DETAILED", para informações completas. Caso esse campo não seja preenchido, será considerada a opção BASIC. | — |
> 📘 Nota
>
> Lembramos que, para ter acesso à razão da reprovação de registro do cliente, é necessário realizar a consulta com o campo `resultLevel` = DETAILED.
### Corpo da requisição (Body)
Não é necessário enviar campos no *body* desta requisição.
## Resposta (Response)
O *status code 200* indicará sucesso na requisição.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document` | `object` | Objeto que contém informações sobre o documento do cliente. |
| `document.value` | `string` | Número do documento. |
| `document.type` | `string` | Tipo do documento. Neste caso, "CPF". |
| `phone` | `object` | Objeto que contém informações sobre o telefone do cliente. |
| `phone.countryCode` | `string` | Código DDI do país. |
| `phone.number` | `string` | Número de telefone incluindo DDD. |
| `address` | `object` | Objeto que contém informações sobre o endereço informado no registro do cliente. |
| `address.zipCode` | `string` | Código postal do endereço. |
| `address.addressLine` | `string` | Logradouro (nome da rua, avenida etc.). |
| `address.buildingNumber` | `string` | Número do imóvel. |
| `address.complement` | `string` | Complemento do endereço. Exemplo: Apto 123, Casa B etc. |
| `address.neighborhood` | `string` | Nome do bairro ou distrito. |
| `address.city` | `string` | Nome da cidade. |
| `address.state` | `string` | Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: SP. |
| `address.country` | `string` | Sigla do país (Brasil) conforme a ISO 3166-2. Exemplo: BR. |
| `email` | `string` | *E-mail* de contato do cliente. |
| `hasBrazilianNationality` | `boolean` | Campo que informa se o cliente é brasileiro. |
| `motherName` | `string` | Nome da mãe informado no registro do cliente. |
| `birthDate` | `string` | Data de nascimento do cliente, no formato ISO 8601 - UTC. |
| `registerName` | `string` | Nome conforme consta no documento de identificação (RG, CNH, RNE, DNI ou CRNM) do cliente. |
| `socialName` | `string` | Nome pelo qual a pessoa gostaria de ser chamada. Saiba mais na documentação [Cartilha do nome social](https://www.mds.gov.br/webarquivos/publicacao/assistencia_social/Folders/cartilha_nome_social.pdf). |
| `status` | `string` | [Status da análise KYC](#status-kyc) realizada no registro do cliente. |
| `profile` | `string` | Perfil do cliente, baseado em seu registro, que pode ser "SIMPLE" (simples) ou "COMPLETE" (completo). |
| `createdAt` | `string` | Data do primeiro registro do cliente, no formato ISO 8601 - UTC. |
| `updatedAt` | `string` | Data da atualização do registro do cliente, no formato ISO 8601 - UTC. |
| `assertedIncome` | `object` | Objeto que contém informações sobre a renda do cliente. |
| `assertedIncome.value` | `number` | Valor em Reais da renda declarada pelo cliente. |
| `assertedIncome.currency` | `string` | Código da moeda com base na ISO - 4217. Exemplo: "BRL". |
| `confirmedIncome` | `string` | Indica se o valor informado da renda foi confirmado no Bureau de informação. O valor padrão desse campo é **null**. |
| `occupation` | `string` | [Código de ocupação do cliente](https://docs.bankly.com.br/docs/codigo-de-ocupacao-cliente). |
| `pep` | `object` | Objeto que contém informações sobre o nível de exposição política do cliente. |
| `pep.level` | `string` | Nível de exposição política do cliente, que pode ser "NONE" (o cliente não é e nem tem vínculo com pessoa exposta politicamente), "SELF"(o cliente é pessoa exposta politicamente) e "RELATED" (o cliente tem vínculo familiar, possui sociedade ou é estreito colaborador de pessoa exposta politicamente). |
| `pep.verified` | `boolean` | Indica se a situação de vínculo com pessoa politicamente exposta foi verificada no bureau de informação. O valor padrão desse campo é false. |
| `documentation` | `object` | Objeto que contém as informações referentes aos documentos enviados para análise. |
| `documentation.selfie` | `string` | *Token* da análise da *selfie*. |
| `documentation.idCardFront` | `string` | *Token* da análise da frente do documento. |
| `documentation.idCardBack` | `string` | *Token* da análise do verso do documento. |
```json Consulta básica
{
"documentNumber": "47742663023",
"document": {
"value": "47742663023",
"type": "CPF"
},
"registerName": "Nísia Floresta",
"socialName": "",
"birthDate": "1790-09-30T00:00:00Z",
"isPoliticallyExposedPerson": false,
"profile": "SIMPLE",
"status": "APPROVED",
"createdAt": "2022-10-12T13:57:58.777Z",
"updatedAt": "2022-10-12T13:57:59.367Z"
}
```
```json Consulta detalhada
{
"documentNumber": "47742663023",
"document": {
"value": "47742663023",
"type": "CPF"
},
"registerName": "Nísia Floresta",
"socialName": "",
"birthDate": "1790-09-30T00:00:00Z",
"motherName": "Dionísia Gonçalves Pinto",
"phone": {
"countryCode": "55",
"number": "23415162342"
},
"email": "nisia.floresta@bankly.com.br",
"hasBrazilianNationality": true,
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"buildingNumber": "2500",
"neighborhood": "Alter do Chão",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"profile": "COMPLETE",
"status": "APPROVED",
"createdAt": "2022-03-25T14:00:38.967Z",
"updatedAt": "2022-07-18T17:47:28.593Z",
"declaredIncome": "LESS_THAN_ONE_THOUSAND",
"assertedIncome": {
"currency": "BRL",
"value": 500000
},
"confirmedIncome":"",
"occupation": "909090",
"pep": {
"level": "NONE",
"verified": false
},
"documentation": {
"selfie": "ce1849509a3f4625867ead5768d5b068",
"idCardFront": "9c1974193d96446e84833742aed1db62",
"idCardBack": "71bb6d35ee7644fe8ef2b8e81eb19f98"
}
}
```
> 🚧 Importante
>
> Indicamos que você verifique o `Cache-Control` no *header* da requisição, pois ele indicará o tempo a ser aguardado para fazer uma nova consulta.
\
**Status da análise KYC**
| Status | Descrição | O que fazer? |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| PENDING\_APPROVAL | O registro do cliente está em análise, aguardando aprovação. | Pedimos que aguarde até a confirmação do resultado da análise. |
| APPROVED | O registro do cliente foi aprovado. Agora estamos criando a sua conta. | Agora você já pode [criar a conta de pagamentos](https://docs.bankly.com.br/docs/onboarding-completo#criando-a-conta-de-pagamentos) do cliente. |
| IN\_ANALYSIS | O registro do cliente foi direcionado para análise manual (exclusivo para parceiros que contrataram o [serviço de derivação de mesa](https://docs.bankly.com.br/docs/derivacao-mesa)). | Pedimos que aguarde até a confirmação do resultado da análise. |
| REPROVED | O registro do cliente foi reprovado. Junto com esse status dever ser retornado o campo `reasons`. | Pedimos que verifique os [motivos de reprovação](https://docs.bankly.com.br/docs/onboarding-motivos-reprovacao) antes de realizar uma nova tentativa. |
| BLACKLISTED | Junto com esse *status* dever ser retornado o campo **`reasons`** com o valor NOT\_RETRY. | Interrompa as tentativas de cadastro desse CPF. |
| CANCELED | O cadastro do cliente foi cancelado. | Há possibilidade de solicitação de novo registro. |
| REVOKED | O cadastro do cliente foi revogado. | Solicite complemento ou ajuste no registro de seu cliente. |
\
**Faixa de renda declarada**
| Faturamento | Descrição |
| ----------------------------------------- | ------------------- |
| LESS\_THAN\_ONE\_THOUSAND | Inferior a mil. |
| FROM\_ONE\_THOUSAND\_TO\_TWO\_THOUSAND | De mil a dois mil. |
| FROM\_TWO\_THOUSAND\_TO\_THREE\_THOUSAND | De 2 mil a 3 mil. |
| FROM\_THREE\_THOUSAND\_TO\_FIVE\_THOUSAND | De 3 mil a 5 mil. |
| FROM\_FIVE\_THOUSAND\_TO\_TEN\_THOUSAND | De 5 mil a 10 mil. |
| FROM\_TEN\_THOUSAND\_TO\_TWENTY\_THOUSAND | De 10 mil a 20 mil. |
| OVER\_TWENTY\_THOUSAND | Acima de 20 mil. |
> 👍 Dica
>
> Para simular uma requisição nesse *endpoint*, acesse o [API Reference](https://docs.bankly.com.br/reference/getcustomerregistration).
## Erros
Este *endpoint* não retorna erros específicos. Porém, ele poderá retornar alguns [erros comuns](https://docs.bankly.com.br/docs/erros) entre todos os *endpoints*.
## Eventos
Este *endpoint* não possui eventos relacionados a ele.