Skip to main content
GET
/
api
/
v1
/
entity
/
{entity_type}
/
{entity_id}
Get Entity Details
curl --request GET \
  --url https://api.example.com/api/v1/entity/{entity_type}/{entity_id}
{
  "id": "<string>",
  "type": "<string>",
  "entity_label": "<string>",
  "identity_quality": "<string>",
  "properties": {},
  "sources": [
    {
      "database": "<string>",
      "record_id": "<string>",
      "extracted_at": "<string>"
    }
  ],
  "is_pep": true,
  "exposure_tier": "<string>"
}
Retrieve detailed information about a specific entity using its CPF, CNPJ, or internal element ID.

​
Authentication

This endpoint requires authentication via:
  • Bearer token: Include Authorization: Bearer <token> header
  • Session cookie: Automatically sent by browser after login
Entity lookup must be enabled via the ENTITY_LOOKUP_ENABLED configuration.

​
Endpoints

​
Get Entity by CPF or CNPJ

GET /api/v1/entity/{cpf_or_cnpj} Lookup an entity using its Brazilian tax identifier (CPF for individuals, CNPJ for companies).
​
cpf_or_cnpj
string
required
CPF (11 digits) or CNPJ (14 digits). Formatting characters (dots, dashes, slashes) are automatically removed.Examples:
  • CPF: 12345678900 or 123.456.789-00
  • CNPJ: 12345678000100 or 12.345.678/0001-00

​
Get Entity by Element ID

GET /api/v1/entity/by-element-id/{element_id} Lookup an entity using its internal Neo4j element ID.
​
element_id
string
required
Neo4j element ID (e.g., 4:abc123:1)

​
Response

​
id
string
Unique element ID for the entity in Neo4j graph database
​
type
string
Entity type in lowercase (e.g., “person”, “company”, “contract”)
​
entity_label
string
Primary Neo4j label (e.g., “Person”, “Company”)
​
identity_quality
string
Identity verification confidence level:
  • strong - Person with valid formatted CPF
  • partial - Partner with incomplete identification
  • unknown - Person without valid CPF
  • null - Not applicable for non-person entities
​
properties
object
Key-value pairs of entity properties. Common fields include:
  • Person: name, cpf, birth_date, mother_name
  • Company: razao_social, nome_fantasia, cnpj, uf
  • Contract: object, value, date, contractor
  • Sanction: type, date, sanctioning_body
Sensitive properties are sanitized before public exposure.
​
sources
array
Data provenance information
​
database
string
Source database name (e.g., “receita_federal”, “compras_gov”, “tce_data”)
​
record_id
string
Original record identifier in source system
​
extracted_at
string
ISO 8601 timestamp of data extraction
​
is_pep
boolean
default:"false"
Politically Exposed Person flag. True if the entity holds or held a public office matching PEP criteria.
​
exposure_tier
string
default:"public_safe"
Data sensitivity classification based on entity labels

​
Example Request

# By CPF
curl -X GET "https://api.br-acc.com/api/v1/entity/12345678900" \
  -H "Authorization: Bearer YOUR_TOKEN"

# By CNPJ with formatting
curl -X GET "https://api.br-acc.com/api/v1/entity/12.345.678/0001-00" \
  -H "Authorization: Bearer YOUR_TOKEN"

# By element ID
curl -X GET "https://api.br-acc.com/api/v1/entity/by-element-id/4:abc123:1" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "id": "4:abc123:1",
  "type": "company",
  "entity_label": "Company",
  "identity_quality": null,
  "properties": {
    "razao_social": "Acme Construções LTDA",
    "nome_fantasia": "Acme",
    "cnpj": "12.345.678/0001-00",
    "uf": "SP",
    "capital_social": 500000.0,
    "natureza_juridica": "Sociedade Empresária Limitada"
  },
  "sources": [
    {
      "database": "receita_federal",
      "record_id": "cnpj_12345678000100",
      "extracted_at": "2024-01-15T10:30:00Z"
    }
  ],
  "is_pep": false,
  "exposure_tier": "public_safe"
}

​
Get Entity Timeline

GET /api/v1/entity/{entity_id}/timeline Retrieve chronological events related to an entity.
​
cursor
string
Pagination cursor (ISO date string) for fetching next page
​
limit
integer
default:"50"
Maximum events per page (min: 1, max: 100)

​
Get Entity Connections

GET /api/v1/entity/{entity_id}/connections Retrieve entities connected to this entity via relationships.
​
depth
integer
default:"2"
Graph traversal depth (min: 1, max: 4)
​
types
string
Comma-separated list of entity types to include (e.g., “company,person”)
​
include_probable
boolean
default:"false"
Include relationships with confidence < 1.0

​
Get Entity Exposure

GET /api/v1/entity/{entity_id}/exposure Calculate risk exposure index based on graph connections and attributes.

​
Error Responses

​
400 Bad Request
Invalid CPF or CNPJ format
​
401 Unauthorized
Missing or invalid authentication token
​
403 Forbidden
Person entity access denied (when HIDE_PERSON_ENTITIES is enabled)
​
404 Not Found
Entity not found in database

​
Privacy Controls

When the HIDE_PERSON_ENTITIES environment variable is enabled:
  • Direct access to Person entities returns 403 Forbidden
  • Only non-person entities can be retrieved
  • This protects individual privacy in public deployments

​
Implementation Details

From entity.py:99-144:
  • Validates CPF/CNPJ format using regex patterns
  • Automatically formats identifiers (adds dots, dashes)
  • Queries Neo4j using both raw and formatted identifiers
  • Enforces access policies for person entities
  • Infers identity quality from labels and CPF format
  • Detects PEP status by matching role keywords

Build docs developers (and LLMs) love

Get started for freeTalk to us