API Schema Documentation

Complete reference for our API response structures

Two Response Types: Our API returns different schemas depending on the operation:

EntitySearchResult - Returned when searching for entities (lightweight, optimized for lists)
EntityDetailsResponse - Returned when fetching full entity details (comprehensive, includes enrichment data)

Search EntitySearchResult

Returned by: GET /api/v1/entities?name=... (search endpoint)

Purpose: Lightweight entity records optimized for search results and list views. Contains core identification fields and basic risk information.

id string (UUID)required

Unique entity identifier. Use this to fetch full details via the details endpoint.

name stringrequired

Primary canonical name of the entity (person, organization, vessel, or aircraft).

entity_type stringrequired

Entity classification. Values: person, organization, vessel, aircraft

countries array[string]

ISO 2-letter country codes associated with the entity (e.g., ["US", "GB"]). Combines data from countries, locations, and nationality fields.

risk array[string]

High-level risk categories. Examples: Fraud, Money Laundering, Terrorism, Corruption, Sanctions

data_source string

Source of the data. Values: admedia (Adverse Media), sanctions, pep

match_score number

Search relevance score (0-100). Higher scores indicate better matches to your search query.

birth_information string

Person entities only. Formatted birth date information (e.g., "1975-05-15 - 1975"). Multiple date formats joined by " - ".

original_name string

Person entities only. Original name from source if different from canonical name (e.g., name before anglicization).

imo_number string

Vessel entities only. International Maritime Organization number (e.g., "IMO-9876543").

registration_number string

Vessel/Aircraft/Organization entities. Official registration or identification number.

industry string

Organization entities only. Industry sector (e.g., "Financial Services", "Manufacturing").

{
  "id": "eb83d4c4-9ecf-463e-acdb-64e1978ce107",
  "name": "JOHN MICHAEL DOE",
  "entity_type": "person",
  "countries": ["US", "GB"],
  "risk": ["Money Laundering", "Fraud"],
  "data_source": "admedia",
  "match_score": 95.5,
  "birth_information": "1975-05-15 - 1975",
  "original_name": "João Miguel Silva"
}

Details EntityDetailsResponse

Returned by: GET /api/v1/entities?id=...&include=summary,risk_timeline,notes,graph

Purpose: Comprehensive entity profile with enrichment data. Includes summaries, risk timelines with source citations, relationship graphs, and extracted metadata.

Core Fields

id string (UUID)required

Unique entity identifier

name stringrequired

Primary canonical name

entity_type stringrequired

Entity classification: person, organization, vessel, aircraft

aliases array[string]

Known name variations, spellings, pseudonyms. Omitted if empty.

name_variants array[string]

Additional name variations from source data. Omitted if empty.

countries array[string]

ISO 2-letter country codes

risk array[string]

Risk categories

data_source string

Data source identifier

Enrichment Fields

summary string

AI-generated plain-text summary of the entity's risk profile and key facts. Omitted if no enrichment data available.

risk_timeline array[object]

Chronologically ordered risk events with dates, statuses, and source citations. Each event includes:

occurred_at (string): Event date in ISO 8601 format
risk_status (string): Status label (e.g., arrested, convicted, investigated)
summary (string): Event description
provenance (array[object]): Source citations with url, publisher, snippet, publishdate

notes object

Key-value pairs of extracted facts (e.g., role, occupation, crime_status, location). Dynamic fields based on available data. Omitted if empty.

graph array[object]

Network of entity relationships. Each relationship includes:

source_name (string): Name of the source entity
target_name (string): Name of the related entity
relation_type (string): Relationship type (e.g., PROSECUTING, TRANSPORTED_FROM, VIOLATED_SANCTIONS_BY)
relation_description (string): Human-readable description

{
  "id": "a11bf442-7a95-4470-aa94-41a1863276ed",
  "name": "BELLA 1",
  "entity_type": "vessel",
  "aliases": ["Marinera"],
  "countries": ["BY"],
  "risk": ["Sanctions Connect", "Terrorist Related", "Sanctions violation"],
  "data_source": "admedia",
  "summary": "Oil tanker involved in sanctions evasion activities...",
  "risk_timeline": [
    {
      "occurred_at": "2020-08-14",
      "risk_status": "seized",
      "summary": "Seized by U.S. authorities for sanctions violations",
      "provenance": [
        {
          "url": "https://news.example.com/bella-seized",
          "publisher": "Reuters",
          "snippet": "U.S. seizes Iranian fuel cargo from vessel Bella 1...",
          "publishdate": "2020-08-14"
        }
      ]
    }
  ],
  "notes": {
    "vessel_type": "Oil Tanker",
    "flag": "Belarus"
  },
  "graph": [
    {
      "source_name": "BELLA 1",
      "target_name": "U.S. DEPARTMENT OF JUSTICE",
      "relation_type": "PROSECUTING",
      "relation_description": "Subject of DOJ sanctions enforcement"
    },
    {
      "source_name": "BELLA 1",
      "target_name": "IRAN",
      "relation_type": "TRANSPORTED_FROM",
      "relation_description": "Transported petroleum products from Iran"
    },
    {
      "source_name": "BELLA 1",
      "target_name": "U.S. COAST GUARD",
      "relation_type": "VIOLATED_SANCTIONS_BY",
      "relation_description": "Violated OFAC sanctions regulations"
    }
  ]
}

Note: All optional fields are omitted from the response if they are empty, null, or contain no data. This keeps responses lean and focused on available information.

Book a Demo