Get Entity Details

GET /api/v1/entity/{entity_type}/{entity_id}

Get Entity Details

cURL

curl --request GET \
  --url https://api.example.com/api/v1/entity/{entity_type}/{entity_id}

200

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

Related Endpoints

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