> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flunora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar CPF

> Devolve a ficha cadastral de uma pessoa física: identificação, contatos e endereços.

O dígito verificador é conferido antes de qualquer chamada paga, então um CPF inválido volta `400` sem custo. O mesmo CPF consultado nos últimos 30 dias volta do histórico, com `cache: true`, sem custo e sem consumir o teto da chave.


Ficha cadastral de uma pessoa física: identificação, contatos e endereços. Equivale ao
produto `search-pf` da rota por produto.

<Card title="Custa uma consulta" horizontal>
  A menos que o mesmo CPF já tenha sido consultado nos últimos 30 dias, caso em que a
  resposta vem do histórico com `cache: true`, sem custo e sem consumir o teto da chave.
</Card>

O dígito verificador é conferido aqui antes de qualquer chamada paga, então CPF digitado
errado volta `400` de graça. Isso não é só economia: o bureau não valida entrada e chega
a devolver a ficha de outra pessoa para um CPF com dígito errado.

**Forçar dado novo:**

```
GET /api/v1/cpf/12345678909?atualizar=true
```

**Resposta:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "consulta": {
    "id": "cmtsr515m1uxzjn04ta469e3q",
    "produto": "search-pf",
    "documento": "12345678909",
    "cache": false,
    "consultadoEm": "2026-09-08T14:15:35.207Z",
    "duracaoMs": 609
  },
  "pessoa": {
    "cpf": "12345678909",
    "nome": "MARIA APARECIDA DA SILVA",
    "nomeMae": "JOANA DA SILVA",
    "nascimento": "1984-03-11T00:00:00",
    "idade": 42,
    "sexo": "F",
    "escolaridade": "Superior completo",
    "rendaPresumida": "De R$ 5.000 a R$ 10.000",
    "situacaoCadastral": "REGULAR",
    "obito": false,
    "telefones": [
      { "numero": "11987654321", "ddd": "11", "tipo": "TELEFONE MÓVEL", "whatsapp": null, "ranking": 1 }
    ],
    "emails": ["maria@exemplo.com.br"],
    "enderecos": [
      {
        "logradouro": "RUA DAS ACACIAS",
        "numero": "204",
        "complemento": null,
        "bairro": "VILA MARIANA",
        "cidade": "SAO PAULO",
        "uf": "SP",
        "cep": "04101000"
      }
    ]
  },
  "bruto": {}
}
```


## OpenAPI

````yaml openapi.yaml GET /api/v1/cpf/{cpf}
openapi: 3.1.0
info:
  title: API da Flunora
  description: >
    Superfície pública da Flunora. Duas capacidades: colocar contatos no funil a
    partir de qualquer sistema, e consultar CPF e CNPJ num bureau de dados
    brasileiro.


    A URL base é o endereço da **sua instância**, não um domínio compartilhado
    da plataforma. Troque `crm.suaempresa.com` pelo seu.
  version: 1.0.0
  contact:
    name: Suporte da Flunora
    email: contato@flunora.com.br
    url: https://docs.flunora.com
servers:
  - url: https://{instancia}
    description: A sua instância da Flunora.
    variables:
      instancia:
        default: crm.suaempresa.com
        description: O domínio da sua instância.
security:
  - chaveDeApi: []
tags:
  - name: Consultas
    description: Ficha cadastral de pessoa e de empresa. Cada consulta é cobrada.
  - name: Entrada de contatos
    description: Criar contato no funil a partir de um sistema externo.
paths:
  /api/v1/cpf/{cpf}:
    get:
      tags:
        - Consultas
      summary: Consultar CPF
      description: >
        Devolve a ficha cadastral de uma pessoa física: identificação, contatos
        e endereços.


        O dígito verificador é conferido antes de qualquer chamada paga, então
        um CPF inválido volta `400` sem custo. O mesmo CPF consultado nos
        últimos 30 dias volta do histórico, com `cache: true`, sem custo e sem
        consumir o teto da chave.
      operationId: consultarCpf
      parameters:
        - name: cpf
          in: path
          required: true
          description: CPF com 11 dígitos. Pontuação é aceita e ignorada.
          schema:
            type: string
            example: '12345678909'
        - name: atualizar
          in: query
          required: false
          description: Ignora o histórico e paga uma consulta nova.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Ficha encontrada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  consulta:
                    $ref: '#/components/schemas/Consulta'
                  pessoa:
                    $ref: '#/components/schemas/Pessoa'
                  bruto:
                    $ref: '#/components/schemas/Bruto'
        '400':
          $ref: '#/components/responses/DocumentoInvalido'
        '401':
          $ref: '#/components/responses/NaoAutenticado'
        '403':
          $ref: '#/components/responses/SemEscopo'
        '404':
          $ref: '#/components/responses/NaoEncontrado'
        '429':
          $ref: '#/components/responses/LimiteAtingido'
        '502':
          $ref: '#/components/responses/BureauIndisponivel'
components:
  schemas:
    Consulta:
      type: object
      description: Metadados da chamada.
      properties:
        id:
          type: string
          description: Identificador da consulta, para citar em suporte.
          example: cmtsr515m1uxzjn04ta469e3q
        produto:
          type: string
          example: search-pf
        documento:
          type: string
          description: O documento normalizado.
          example: '12345678909'
        cache:
          type: boolean
          description: >
            `true` quando veio do histórico. Não custou nada e não consumiu o
            teto da chave.
          example: false
        consultadoEm:
          type: string
          format: date-time
        duracaoMs:
          type:
            - integer
            - 'null'
          example: 609
    Pessoa:
      type:
        - object
        - 'null'
      description: >
        A ficha em campos estáveis. Campo que o bureau não tem vem `null`, nunca
        preenchido por dedução.
      properties:
        cpf:
          type: string
        nome:
          type:
            - string
            - 'null'
        nomeMae:
          type:
            - string
            - 'null'
        nascimento:
          type:
            - string
            - 'null'
        idade:
          type:
            - integer
            - 'null'
        sexo:
          type:
            - string
            - 'null'
        escolaridade:
          type:
            - string
            - 'null'
        rendaPresumida:
          type:
            - string
            - 'null'
          description: Faixa, não valor exato.
        situacaoCadastral:
          type:
            - string
            - 'null'
        obito:
          type:
            - boolean
            - 'null'
        telefones:
          type: array
          items:
            $ref: '#/components/schemas/Telefone'
        emails:
          type: array
          items:
            type: string
        enderecos:
          type: array
          items:
            $ref: '#/components/schemas/Endereco'
    Bruto:
      type: object
      description: >
        A resposta original do bureau, sem tratamento. Existe para você não
        ficar sem informação que já foi paga, e é onde estão as coisas que ainda
        não têm campo próprio, como latitude do endereço, operadora do telefone
        e CBO do sócio. Programe contra os campos nomeados, que são o contrato.
    Telefone:
      type: object
      properties:
        numero:
          type: string
          example: '11987654321'
        ddd:
          type:
            - string
            - 'null'
          example: '11'
        tipo:
          type:
            - string
            - 'null'
          example: TELEFONE MÓVEL
        whatsapp:
          type:
            - boolean
            - 'null'
          description: >
            `null` quer dizer que o bureau não informou, e não que o número não
            tem WhatsApp.
        ranking:
          type:
            - integer
            - 'null'
          description: Ordenação de confiabilidade que o bureau devolve.
          example: 1
    Endereco:
      type: object
      properties:
        logradouro:
          type:
            - string
            - 'null'
        numero:
          type:
            - string
            - 'null'
        complemento:
          type:
            - string
            - 'null'
        bairro:
          type:
            - string
            - 'null'
        cidade:
          type:
            - string
            - 'null'
        uf:
          type:
            - string
            - 'null'
        cep:
          type:
            - string
            - 'null'
    Erro:
      type: object
      description: >
        O `codigo` é uma string estável nossa, não o número que o bureau
        devolveu. Trate por ele, para o seu `if` continuar valendo se o
        fornecedor mudar.
      properties:
        erro:
          type: object
          properties:
            codigo:
              type: string
              example: nao_encontrado
            mensagem:
              type: string
              example: Documento não localizado.
            detalhe:
              type: object
  responses:
    DocumentoInvalido:
      description: >
        Dígito verificador, formato ou sintaxe. Não custa nada: a conferência é
        local e acontece antes de qualquer chamada paga.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
    NaoAutenticado:
      description: Chave ausente, inválida, revogada, expirada ou desativada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
    SemEscopo:
      description: A chave não cobre esse tipo de documento, ou a conta está bloqueada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
    NaoEncontrado:
      description: >
        O bureau não tem o documento, ou a instância não tem a consulta
        habilitada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
    LimiteAtingido:
      description: >
        Teto por minuto, diário ou mensal da chave. O cabeçalho `Retry-After`
        acompanha quando faz sentido esperar.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
    BureauIndisponivel:
      description: Fornecedor fora do ar, timeout, ou credencial recusada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
  securitySchemes:
    chaveDeApi:
      type: http
      scheme: bearer
      description: >
        Chave de API criada em Configurações, Integrações, Chaves de API. Começa
        com `sk_live_` e aparece uma vez só. O cabeçalho `X-API-Key` também é
        aceito, com o mesmo valor.

````