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 from both Elasticsearch and PostgreSQL. Includes AI-generated summaries, risk timelines with source citations, relationship graphs, and extracted metadata.

Core Fields (from Elasticsearch)

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

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_id (string UUID): Source entity ID
  • target_id (string UUID): Target entity ID
  • relation_type (string): Relationship type (e.g., associated_with, employed_by)
  • relation_description (string): Human-readable description
{
  "id": "eb83d4c4-9ecf-463e-acdb-64e1978ce107",
  "name": "JOHN MICHAEL DOE",
  "entity_type": "person",
  "aliases": ["John Doe", "J.M. Doe", "Johnny Doe"],
  "name_variants": ["Jon Doe", "John M. Doe"],
  "countries": ["US", "GB"],
  "risk": ["Money Laundering", "Fraud"],
  "data_source": "admedia",
  "birth_information": "1975-05-15 - 1975",
  "original_name": "João Miguel Silva",
  "summary": "High-risk individual with documented history of financial fraud...",
  "risk_timeline": [
    {
      "occurred_at": "2022-03-15",
      "risk_status": "convicted",
      "summary": "Convicted of wire fraud in federal court",
      "provenance": [
        {
          "url": "https://news.example.com/john-doe-convicted",
          "publisher": "Financial Times",
          "snippet": "John Doe convicted of wire fraud...",
          "publishdate": "2022-03-15"
        }
      ]
    }
  ],
  "notes": {
    "occupation": "Financial Consultant",
    "education": "MBA from Harvard Business School"
  },
  "graph": [
    {
      "source_id": "eb83d4c4-9ecf-463e-acdb-64e1978ce107",
      "target_id": "660f9500-f30c-52e5-b827-557766551111",
      "relation_type": "associated_with",
      "relation_description": "Business partner at shell company"
    }
  ]
}

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