Risk Profile API

Risk profiles represent individual matches from sanctions lists, PEP databases, watchlists, or adverse media. Each risk profile contains detailed information about a potential match including biographical data, risk indicators, and source documents.

Risk Profile Workflow

Risk profiles are created automatically when a screening finds potential matches:

1. Match Found
Screening creates Case
Alert generated for review
→
2. Risk Profiles
GET /risk-profiles/{id}/
Review each match detail
→
3. Mark Status
PATCH /risk-profiles/{id}/
True/False positive decision

Review Status Values

Status Meaning When to Use
not_reviewed Default state Profile created but not yet examined
in_review Under investigation Assigned to analyst, awaiting decision
false_positive Not the same person/entity Similar name but different individual (check DOB, nationality)
true_positive Confirmed match Same individual with sanctions/PEP/adverse media

Get Risk Profile Details

GET /api/v1/risk-profiles/{risk_profile_id}/

Retrieve full details for a specific risk profile including all sensitive data (PEP details, sanctions info, adverse media articles, watchlist entries).

Path Parameters

Parameter Type Description
risk_profile_id UUID The unique identifier for the risk profile

Response (200 OK)

{
  "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
  "alert_id": "5bc52924-8a4f-48ae-acaa-13027deae060",
  "name": "John Smith - Adverse Media, PEP",
  "entity_type": "individual",
  "status": "not_reviewed",
  "matching_score": 75.5,
  "matching_name": "Smith, John",
  "match_type": ["name_exact", "name_variations_removal"],
  "aml_types": ["pep-class-1", "adverse-media", "adverse-media-v2-other-minor"],
  "dates_of_birth": ["1975"],
  "also_known_as": ["John Smith"],
  "all_related_countries": ["US", "GB"],
  "pep": [
    {
      "aml_types": ["pep-class-1"],
      "active_end_dates": [],
      "active_start_dates": [],
      "country_codes": [],
      "fields": [],
      "identifier": "S:ABC123",
      "listing_ended_utc": null,
      "listing_started_utc": null,
      "name": "PEP Data",
      "political_parties": [],
      "political_positions": [],
      "political_regions": [],
      "related_urls": [],
      "url": null
    },
    {
      "aml_types": ["pep-class-1"],
      "active_end_dates": [],
      "active_start_dates": ["2020-10-01"],
      "country_codes": ["GB"],
      "fields": [
        {"name": "Country", "tag": null, "value": "United Kingdom"},
        {"name": "Chamber", "tag": null, "value": "Office for Budget Responsibility"},
        {"name": "Function", "tag": null, "value": "Chair"},
        {"name": "Institution Type", "tag": null, "value": "Agency under Ministry"},
        {"name": "Active Start Date", "tag": "active_start_date", "value": "2020-10-01"},
        {"name": "Political Position", "tag": "political_position", "value": "Senior Government Official"},
        {"name": "Picture URL", "tag": "picture_url", "value": "https://example.gov.uk/person-photo.jpg"}
      ],
      "identifier": "S:XYZ789",
      "listing_ended_utc": null,
      "listing_started_utc": null,
      "name": "United Kingdom Office for Budget Responsibility Leadership",
      "political_parties": [],
      "political_positions": ["Senior Government Official"],
      "political_regions": [],
      "related_urls": [],
      "url": "https://example.gov.uk/about/"
    }
  ],
  "sanctions": [
    {
      "aml_types": [
        "sanction"
      ],
      "country_codes": [
        "CO"
      ],
      "fields": [
        {
          "name": "Designation Date",
          "tag": null,
          "value": "2013-07-09"
        },
        {
          "name": "Sanction Type",
          "tag": null,
          "value": "Block"
        }
      ],
      "identifier": "S:UKNREN",
      "listing_ended_utc": null,
      "listing_started_utc": "2013-07-09T00:00:00Z",
      "name": "OFAC SDN List",
      "related_urls": [],
      "url": "http://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx"
    },
    {
      "aml_types": [
        "sanction"
      ],
      "country_codes": [],
      "fields": [
        {
          "name": "Other Info",
          "tag": null,
          "value": "G&G INTERNACIONAL. is related to Ceballos Bueno Johanna Patricia who is a sanctioned entity listed on OFAC SDN List"
        },

        {
          "name": "Related URL",
          "tag": "related_url",
          "value": "https://ofac.treasury.gov/specially-designated-nationals-list-data-formats-data-schemas"
        }
      ],
      "identifier": "S:JEPFGR",
      "listing_ended_utc": null,
      "listing_started_utc": "2024-01-30T00:00:00Z",
      "name": "Sanction Related Entities",
      "related_urls": [
        "https://ofac.treasury.gov/specially-designated-nationals-list-data-formats-data-schemas"
      ],
      "url": "https://example.com/sanction-related-entities"   
    }
  ],
  "media": [
    {
      "identifier": null,
      "publishing_date": "2021-10-06T00:00:00Z",
      "snippet": "John Smith, 47, was charged with driving without a valid license and released on bond.",
      "title": "Local man charged with license violation",
      "url": "https://news.example.com/article-123"
    },
    {
      "identifier": null,
      "publishing_date": "2021-10-13T00:00:00Z",
      "snippet": "John Smith was involved in a minor traffic incident last week.",
      "title": "Traffic incident reported",
      "url": "https://news.example.com/article-456"
    }
  ],
  "watchlists": [
    {
      "aml_types": [
        "fitness-probity"
      ],
      "country_codes": [],
      "fields": [
        {
          "name": "Activation Date",
          "tag": null,
          "value": "04/06/2019"
        },
        {
          "name": "Enforcement Agency",
          "tag": null,
          "value": "Peru National Contractors Register Disqualifications and Fines"
        },
        {
          "name": "Enforcement Type",
          "tag": null,
          "value": "Disqualification"
        },
      ],
      "identifier": "S:7XRN2P",
      "listing_ended_utc": null,
      "listing_started_utc": "2019-08-20T00:00:00Z",
      "name": "Peru National Contractors Register Disqualifications and Fines",
      "related_urls": [],
      "url": "http://www.osce.gob.pe/consultasenlinea/inhabilitados/inhabil_publi_mes.asp"
    }
  ],
  "created_at": "2026-01-07T14:35:40.123456+00:00"
}

Response Fields

Field Type Description
id UUID Unique identifier for this risk profile
alert_id UUID Parent alert this profile belongs to
name string Name of the matched individual/entity
entity_type string Type: individual or company
status string Review status (see status table above)
matching_score float Confidence score (0-100). >80 = high confidence, <50 = likely false positive
matching_name string Name from the watchlist/database that triggered the match
match_type array How the match was determined: name_exact, year_of_birth, dob_match, etc.
aml_types array Risk categories: sanction, pep-class-1, adverse-media-v2-financial-aml-cft, etc.
dates_of_birth array Known dates of birth for the match (various formats: year only, full date)
also_known_as array Alternative names, aliases, and variations
all_related_countries array Country codes (ISO 3166-1 alpha-2) associated with this profile
pep array Array of PEP entries (one person may appear in multiple PEP lists with different positions)
sanctions array Sanctions details if applicable (lists, designation dates, reasons)
media array Adverse media articles with titles, snippets, URLs, and publication dates
watchlists array Watchlist entries (enforcement actions, disqualifications, fitness & probity)
created_at ISO 8601 When this risk profile was created
Unicode Characters in Data

Risk profile data may contain Unicode characters (Cyrillic, Arabic, Chinese, etc.) for international names and content. These appear as escape sequences like \u041f\u0443\u0442\u0456\u043d in raw JSON but are automatically decoded by JSON parsers to display correctly.

Update Risk Profile Status

PATCH /api/v1/risk-profiles/{risk_profile_id}/

Update the review status of a risk profile as you investigate whether it's a true or false positive.

Path Parameters

Parameter Type Description
risk_profile_id UUID The unique identifier for the risk profile

Request Body

Parameter Type Required Description
status string Yes Review status: not_reviewed, in_review, false_positive, true_positive

Response (200 OK)

{
  "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
  "name": "John Smith - Adverse Media, PEP",
  "entity_type": "individual",
  "status": "false_positive",
  "created_at": "2026-01-07T14:35:40.123456+00:00",
  "updated_at": "2026-01-07T15:22:18.987654+00:00"
}
↑ ↓ to navigate • Enter to select • Esc to close