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

# Identidade

> Dados cadastrais da pessoa física. Só CPF.

Dados cadastrais da pessoa física consultada. Retorna um item com nome, filiação, contatos, endereço principal, nascimento e situação do CPF; raça e cor nunca vêm. Só existe para CPF: com CNPJ responde `422` (`identidade_exige_cpf`). A chave precisa do escopo `dados:identidade`.


## OpenAPI

````yaml dados/ref/identidade.openapi.yaml POST /dados/consultar
openapi: 3.1.0
info:
  description: API de dados por documento (CPF/CNPJ).
  title: NL Labs API de Dados
  version: 0.1.0
servers:
  - url: https://api.nlbs.ai
security: []
paths:
  /dados/consultar:
    post:
      tags:
        - dados
      summary: Consultar Identidade
      operationId: consultar_dados_consultar_post
      parameters:
        - description: >-
            Opcional. Mesma chave em 24 h a partir da primeira chamada devolve a
            mesma resposta, sem repetir a leitura.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - maxLength: 255
                minLength: 1
                pattern: ^[A-Za-z0-9._\-]+$
                type: string
              - type: 'null'
            description: >-
              Opcional. Mesma chave em 24 h a partir da primeira chamada devolve
              a mesma resposta, sem repetir a leitura.
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            example:
              datasets:
                - identidade
              documento: '52998224725'
            schema:
              $ref: '#/components/schemas/ConsultaRequisicao'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                com_dados:
                  summary: Com dados
                  value:
                    consultado_em: '2026-01-15T12:00:00Z'
                    datasets:
                      identidade:
                        encontrado: true
                        itens:
                          - cpf: '52998224725'
                            data_nascimento: '1980-03-15'
                            data_obito: null
                            emails:
                              - fulana@exemplo.com
                            endereco:
                              cep: '01001000'
                              completo: Praca da Se, 1, Se, Sao Paulo, SP
                              municipio: Sao Paulo
                              uf: SP
                            escolaridade: higher_education
                            estado_civil: married
                            nome: Fulana de Tal
                            nome_mae: Mae Exemplo
                            nome_pai: Pai Exemplo
                            situacao_cadastral: regular
                            telefones:
                              - '11999990000'
                    documento: '52998224725'
                    encontrado: true
                    tipo: cpf
                sem_dados:
                  summary: Sem dados
                  value:
                    consultado_em: '2026-01-15T12:00:00Z'
                    datasets:
                      identidade:
                        encontrado: false
                        itens: []
                    documento: '52998224725'
                    encontrado: false
                    tipo: cpf
              schema:
                $ref: '#/components/schemas/ConsultaResposta'
          description: Um bloco por dataset pedido.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
          description: Chave invalida
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
          description: Escopo insuficiente ou sem acesso
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
          description: Entrada invalida, ubo com CPF ou identidade com CNPJ
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
          description: Cota esgotada
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
          description: Indisponivel
      security:
        - APIKeyHeader: []
components:
  schemas:
    ConsultaRequisicao:
      additionalProperties: false
      properties:
        datasets:
          default:
            - identidade
          description: Sempre ["identidade"] nesta página.
          items:
            enum:
              - identidade
            type: string
          maxItems: 1
          minItems: 1
          title: Datasets
          type: array
        documento:
          description: CPF ou CNPJ, com ou sem pontuacao.
          title: Documento
          type: string
      required:
        - documento
        - datasets
      title: ConsultaRequisicao
      type: object
    ConsultaResposta:
      properties:
        consultado_em:
          description: Instante da consulta, ISO 8601 em UTC (sufixo Z).
          examples:
            - '2026-01-15T12:00:00Z'
          format: date-time
          title: Consultado Em
          type: string
        datasets:
          properties:
            identidade:
              $ref: '#/components/schemas/DatasetIdentidade'
          required:
            - identidade
          title: Datasets
          type: object
        documento:
          title: Documento
          type: string
        encontrado:
          title: Encontrado
          type: boolean
        tipo:
          enum:
            - cpf
            - cnpj
          title: Tipo
          type: string
      required:
        - documento
        - tipo
        - encontrado
        - consultado_em
        - datasets
      title: ConsultaResposta
      type: object
    ErroResposta:
      properties:
        erro:
          $ref: '#/components/schemas/ErroDetalhe'
      required:
        - erro
      title: ErroResposta
      type: object
    DatasetIdentidade:
      properties:
        encontrado:
          title: Encontrado
          type: boolean
        itens:
          description: A pessoa consultada (um item). So para CPF.
          items:
            $ref: '#/components/schemas/ItemIdentidade'
          title: Itens
          type: array
      required:
        - encontrado
        - itens
      title: DatasetIdentidade
      type: object
    ErroDetalhe:
      properties:
        codigo:
          title: Codigo
          type: string
        mensagem:
          title: Mensagem
          type: string
      required:
        - codigo
        - mensagem
      title: ErroDetalhe
      type: object
    ItemIdentidade:
      properties:
        cpf:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            CPF do consultado completo; CPF diferente do consultado vem
            mascarado.
          title: Cpf
        data_nascimento:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Data Nascimento
        data_obito:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Data Obito
        emails:
          description: Todos os emails, o principal primeiro (ate 50).
          items:
            type: string
          title: Emails
          type: array
        endereco:
          anyOf:
            - $ref: '#/components/schemas/EnderecoIdentidade'
            - type: 'null'
        escolaridade:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Nivel de escolaridade (ex.: higher_education).'
          title: Escolaridade
        estado_civil:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Estado civil (ex.: married).'
          title: Estado Civil
        nome:
          anyOf:
            - type: string
            - type: 'null'
          title: Nome
        nome_mae:
          anyOf:
            - type: string
            - type: 'null'
          title: Nome Mae
        nome_pai:
          anyOf:
            - type: string
            - type: 'null'
          title: Nome Pai
        situacao_cadastral:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Situacao cadastral do CPF na Receita (ex.: regular, suspended).'
          title: Situacao Cadastral
        telefones:
          description: Todos os telefones, o principal primeiro (ate 50).
          items:
            type: string
          title: Telefones
          type: array
      required:
        - nome
        - cpf
        - nome_mae
        - nome_pai
        - escolaridade
        - estado_civil
        - emails
        - telefones
        - endereco
        - data_nascimento
        - situacao_cadastral
        - data_obito
      title: ItemIdentidade
      type: object
    EnderecoIdentidade:
      properties:
        cep:
          anyOf:
            - type: string
            - type: 'null'
          title: Cep
        completo:
          anyOf:
            - type: string
            - type: 'null'
          description: Endereco completo como na fonte, em texto unico.
          title: Completo
        municipio:
          anyOf:
            - type: string
            - type: 'null'
          title: Municipio
        uf:
          anyOf:
            - type: string
            - type: 'null'
          title: Uf
      required:
        - completo
        - municipio
        - uf
        - cep
      title: EnderecoIdentidade
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.