Dados Cadastrais por CPF, CNPJ ou Nome

Novo CNPJ (IN 2229/24)A Judit já aceita o novo formato de CNPJ alfanumérico em conformidade com a Instrução Normativa RFB nº 2229/2024.

Zero esforço: nenhuma alteração é necessária na sua integração.
Ambiente de teste: utilize o documento A1B2C3D4/E5F6-68 para validar o fluxo e receber um processo fictício de resposta.

A Consulta por Dados Cadastrais retorna informações de identificação de uma Pessoa Física ou Jurídica: nome/razão social, situação cadastral, endereços, contatos, sócios e relacionamentos. Toda a chamada é síncrona e pode ler do datalake da Judit (rápido e barato) ou direto da Receita Federal em tempo real (on_demand: true).

🤖 Endpoint: POST https://lawsuits.production.judit.io/entities. search_type aceita cpf, cnpj ou name. response_type é sempre entity. Para resposta em tempo real (Receita), envie on_demand: true no payload.

Quando usar

Onboarding e KYC

Valide nome, situação cadastral e endereço durante o cadastro do cliente sem fricção adicional.

Enriquecimento de base

Atualize seu CRM/ERP com dados consolidados por CPF/CNPJ.

Anti-fraude

Confronte dados informados pelo usuário com a versão oficial em segundos.

Mapeamento de grupo econômico

Use a resposta para descobrir filiais e relacionamentos societários ligados a um CNPJ.

Datalake vs. On-Demand (Receita Federal)

Característica	Datalake (padrão)	On-Demand (`on_demand: true`)
Latência	ms	segundos
Fonte	Cache JUDIT	Receita Federal em tempo real
Atualidade	Última coleta JUDIT	Estado atual da Receita
Custo	Mais barato	Mais caro
Caso ideal	Onboarding rápido, enriquecimento em massa	Compliance crítico, decisões de alto risco

Passo 1: Criar a Consulta (POST)

POST https://lawsuits.production.judit.io/entities

Exemplos por tipo de documento

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
    }
}

{
    "search": {
        "search_type": "cnpj",
        "search_key": "99.999.999/9999-99"
    }
}

{
    "search": {
        "search_type": "name",
        "search_key": "Nome teste"
    }
}

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "on_demand": true
    }
}

{
    "search": {
        "search_type": "cnpj",
        "search_key": "99.999.999/9999-99",
        "reveal_partners_documents": true
    }
}

Ao realizar consultas por nome, é possível que existam homônimos (pessoas ou empresas com o mesmo nome). Sempre que possível, prefira CPF ou CNPJ para garantir maior precisão.

Parâmetros do Payload

Parâmetro	Tipo	Obrigatório	Descrição
`search.search_type`	string	Sim	`"cpf"`, `"cnpj"` ou `"name"`.
`search.search_key`	string	Sim	Documento ou nome a buscar.
`search.response_type`	string	Sim	Sempre `"entity"`.
`search.on_demand`	boolean	Não	Se `true`, força leitura em tempo real na Receita Federal.
`search.reveal_partners_documents`	boolean	Não	(CNPJ) Retorna documentos não mascarados dos sócios.

Exemplo de Requisição (POST)

curl --location 'https://lawsuits.production.judit.io/entities' \
  --header 'api-key: '"$JUDIT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "search": {
      "search_type": "cpf",
      "search_key": "999.999.999-99"
    }
  }'

curl --location 'https://lawsuits.production.judit.io/entities' \
  --header 'api-key: '"$JUDIT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "search": {
      "search_type": "cnpj",
      "search_key": "99.999.999/9999-99",
      "on_demand": true
    }
  }'

import os, requests

resp = requests.post(
    "https://lawsuits.production.judit.io/entities",
    headers={
        "api-key": os.environ["JUDIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "search": {
            "search_type": "cpf",
            "search_key": "999.999.999-99",,
        }
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const res = await fetch("https://lawsuits.production.judit.io/entities", {
  method: "POST",
  headers: {
    "api-key": process.env.JUDIT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search: {
      search_type: "cpf",
      search_key: "999.999.999-99",
      response_type: "entity",
    },
  }),
});
console.log(await res.json());

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "net/http"
    "os"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "search": map[string]string{
            "search_type":   "cpf",
            "search_key":    "999.999.999-99",,
        },
    })
    req, _ := http.NewRequest("POST",
        "https://lawsuits.production.judit.io/entities",
        bytes.NewReader(body))
    req.Header.Set("api-key", os.Getenv("JUDIT_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    println(string(out))
}

Passo 2: Ler a Resposta

A resposta vem no corpo do mesmo POST. Os campos principais:

Campo	Tipo	Descrição
`request_id`	string	Identificador único da consulta.
`response_data`	array	Lista de entidades encontradas (segue o Schema Entity).
`response_data[].entity_type`	string	`"person"` (PF) ou `"company"` (PJ).
`response_data[].main_document`	string	CPF ou CNPJ.
`response_data[].addresses`	array	Endereços associados.
`response_data[].contacts`	array	Telefones e e-mails.
`response_data[].partners`	array	(PJ) Sócios e administradores.

Exemplos de Resposta

{
    "has_lawsuits": false,
    "request_id": "5c618521-2ecc-4176-a573-431d2e0edeb2",
    "response_data": [
        {
            "entity_id": "",
            "entity_type": "person",
            "main_document": "999.999.999-99",
            "name": "JOÃO TESTE",
            "addresses": [
                {
                    "street": "RUA RAMOS DE CARVALHO",
                    "number": "999",
                    "neighborhood": "CENTRO",
                    "city": "RIO DE JANEIRO",
                    "state": "RJ",
                    "country": "Brasil",
                    "zip_code": "99999999"
                }
            ],
            "contacts": [
                { "description": "21999999999", "contact_type": "phone" }
            ],
            "parents": [
                { "name": "JANAINA DA SILVA", "kinship": "mother" }
            ],
            "tags": { "revenue_update_date": "2022-05-30T00:00:00.000Z" },
            "nationality": "BRASILEIRA",
            "birth_date": "1981-08-07T00:00:00.000Z",
            "gender": "male",
            "revenue_service_active": true,
            "created_at": "2024-10-12T13:28:59.051Z",
            "updated_at": "2024-10-12T13:28:59.051Z"
        }
    ]
}

{
    "has_lawsuits": false,
    "request_id": "6e5a24f7-f874-4234-8acc-419142e2b066",
    "response_data": [
        {
            "entity_id": "",
            "entity_type": "company",
            "main_document": "99.999.999/0009-99",
            "name": "FINGI - EM RECUPERACAO JUDICIAL",
            "social_name": "FING",
            "addresses": [
                {
                    "street": "RUA DO JOÃO CIRILO",
                    "number": "99",
                    "complement": "ANDAR 9",
                    "neighborhood": "CENTRO",
                    "city": "RIO DE JANEIRO",
                    "state": "RJ",
                    "country": "BRASIL",
                    "zip_code": "99999999"
                }
            ],
            "contacts": [
                { "description": "999999999", "contact_type": "phone" },
                { "description": "ouvidoria@fing.com.br", "contact_type": "email" }
            ],
            "partners": [
                {
                    "entity_type": "company",
                    "main_document": "***999999**",
                    "name": "JOÃO DE OLIVEIRA SOUZA",
                    "position": "CONSELHEIRO DE ADMINISTRAÇÃO",
                    "tags": {
                        "age_group": "Entre 61 a 70 anos",
                        "start_date": "2018-09-25T00:00:00.000Z"
                    }
                }
            ],
            "branch_activities": [
                {
                    "code": "9999999",
                    "name": "SERVIÇOS DE ATENDIMENTO AO CLIENTE - SAC",
                    "active": true,
                    "main_activity": true
                }
            ],
            "tags": { "revenue_update_date": "2005-11-03T00:00:00.000Z" },
            "nationality": "BRASILEIRA",
            "birth_date": "1966-09-26T00:00:00.000Z",
            "size": "DEMAIS",
            "legal_nature": {
                "code": "2046",
                "name": "SOCIEDADE ANÔNIMA ABERTA",
                "active": true
            },
            "head_office": true,
            "revenue_service_active": true,
            "special_status": "RECUPERACAO JUDICIAL",
            "special_status_date": "2016-06-29T00:00:00.000Z",
            "share_capital": 99999999999
        }
    ]
}

{
    "request_id": "223458ec-f3a1-4851-8d2b-19672066565c",
    "response_data": [
        {
            "entity_id": "999.999.999-99",
            "entity_type": "person",
            "main_document": "999.999.999-99",
            "name": "Usuário Teste",
            "parents": [
                { "name": "Usuário teste 1", "kinship": "mother" }
            ],
            "tags": {},
            "nationality": "BRASILEIRA",
            "birth_date": "1989-12-25T00:00:00.000Z",
            "gender": "male",
            "created_at": "2025-04-19T00:14:56.561Z",
            "updated_at": "2025-04-19T00:14:56.561Z"
        }
    ]
}

Estrutura completa de cada item: veja Schema Entity. Glossário de campos: Glossário.

Ao consultar por CNPJ com reveal_partners_documents: true, retornamos os CPFs/CNPJs dos sócios sem mascaramento. Use somente quando há base legal/contratual (LGPD).

Erros comuns

HTTP	Quando acontece	Como tratar
`400`	Documento em formato inválido / `response_type` ausente.	V

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento