Registration Data by CPF, CNPJ or Name

New CNPJ format (IN 2229/24)Judit already accepts the new alphanumeric CNPJ format in compliance with the Brazilian Federal Revenue Normative Instruction No. 2229/2024.

Zero effort: no changes are required in your integration.
Test environment: use the document A1B2C3D4/E5F6-68 to validate the flow and receive a mock lawsuit in response.

The Registration Data Query returns identity information for an individual or company: name/corporate name, registration status, addresses, contacts, partners and relationships. The whole call is synchronous and can read from Judit’s datalake (fast and cheap) or directly from the Brazilian Federal Revenue in real time (on_demand: true).

🤖 Endpoint: POST https://lawsuits.production.judit.io/entities. search_type accepts cpf, cnpj or name. response_type is always entity. For real-time response (Receita Federal), send on_demand: true in the payload.

When to use

Onboarding and KYC

Validate name, registration status and address during customer onboarding without extra friction.

Database enrichment

Update CRM/ERP records with consolidated data by CPF/CNPJ.

Anti-fraud

Cross-check user-supplied data against the official source in seconds.

Corporate group mapping

Use the response to discover branches and corporate relationships linked to a CNPJ.

Datalake vs. On-Demand (Federal Revenue)

Trait	Datalake (default)	On-Demand (`on_demand: true`)
Latency	ms	seconds
Source	Judit cache	Brazilian Federal Revenue (live)
Freshness	Last Judit collection	Current Receita state
Cost	Lower	Higher
Best for	Fast onboarding, mass enrichment	Critical compliance, high-risk decisions

Step 1: Create the query (POST)

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

Examples by document type

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

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

{
    "search": {
        "search_type": "name",
        "search_key": "John Smith",
        "response_type": "entity"
    }
}

{
    "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
    }
}

For name queries, homonyms are possible. Whenever possible, prefer CPF or CNPJ for accuracy.

Payload parameters

Parameter	Type	Required	Description
`search.search_type`	string	Yes	`"cpf"`, `"cnpj"` or `"name"`.
`search.search_key`	string	Yes	Document or name to search.
`search.response_type`	string	Yes	Always `"entity"`.
`search.on_demand`	boolean	No	If `true`, forces a live read from the Brazilian Federal Revenue.
`search.reveal_partners_documents`	boolean	No	(CNPJ) Returns unmasked partner documents.

Request example (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",
      "response_type": "entity"
    }
  }'

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
    }
  }'

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());

<?php
$ch = curl_init('https://lawsuits.production.judit.io/entities');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'api-key: ' . getenv('JUDIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'search' => [
            'search_type'   => 'cpf',
            'search_key'    => '999.999.999-99',
            'response_type' => 'entity',
        ],
    ]),
]);
$response = curl_exec($ch);
echo $response;

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())

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))
}

Step 2: Read the response

The response comes in the same POST body. Main fields:

Field	Type	Description
`request_id`	string	Unique query identifier.
`response_data`	array	List of found entities (follows the Entity Schema).
`response_data[].entity_type`	string	`"person"` (PF) or `"company"` (PJ).
`response_data[].main_document`	string	CPF or CNPJ.
`response_data[].addresses`	array	Associated addresses.
`response_data[].contacts`	array	Phones and emails.
`response_data[].partners`	array	(PJ) Partners and administrators.

Response examples

{
    "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_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",
                    "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": "BOARD MEMBER",
                    "tags": {
                        "age_group": "61-70",
                        "start_date": "2018-09-25T00:00:00.000Z"
                    }
                }
            ],
            "branch_activities": [
                {
                    "code": "9999999",
                    "name": "CUSTOMER SUPPORT - SAC",
                    "active": true,
                    "main_activity": true
                }
            ],
            "tags": { "revenue_update_date": "2005-11-03T00:00:00.000Z" },
            "size": "OTHER",
            "legal_nature": {
                "code": "2046",
                "name": "PUBLIC CORPORATION",
                "active": true
            },
            "head_office": true,
            "revenue_service_active": true,
            "special_status": "JUDICIAL RECOVERY",
            "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": "Test User",
            "parents": [
                { "name": "Mother Name", "kinship": "mother" }
            ],
            "tags": {},
            "nationality": "BRASILEIRA",
            "birth_date": "1989-12-25T00:00:00.000Z",
            "gender": "male"
        }
    ]
}

Full structure of each item: see Entity Schema. Field glossary: Glossary.

When querying by CNPJ with reveal_partners_documents: true, partner CPFs/CNPJs are returned without masking. Only use it when you have a clear legal basis (KYC, AML, due diligence) — and never persist the unmasked values longer than necessary.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking