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/v2/risk-profiles/{risk_profile_id}/

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

Path Parameters

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

Response Fields

Field Type Description
idUUIDUnique identifier for this risk profile
alert_idUUIDParent alert this profile belongs to
namestringName of the matched individual/entity
entity_typestringType: individual or company
statusstringReview status (see status table above)
matching_scorefloatConfidence score (0.0–1.0). Higher = stronger match. Values above 0.8 indicate high confidence.
matching_namestringName from the watchlist/database that triggered the match
match_typearrayHow the match was determined.
aml_typesarrayRisk categories such as sanctions, PEP, or adverse media.
dates_of_birtharrayKnown dates of birth for the match
also_known_asarrayAlternative names, aliases, and variations
all_related_countriesarrayCountry codes associated with this profile
peparrayArray of PEP entries
sanctionsarraySanctions details if applicable
mediaarrayAdverse media articles with titles, snippets, URLs, and publication dates
watchlistsarrayWatchlist entries
created_atISO 8601When this risk profile was created
Unicode Characters in Data

Risk profile data may contain Unicode characters for international names and content. These are decoded automatically by JSON parsers.

Get Risk Profile

curl -X GET \
  'https://api.kycgenie.com/api/v1/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/' \
  -H 'Authorization: Bearer YOUR_API_KEY'
curl -X GET \
  'https://api.kycgenie.com/api/v2/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/' \
  -H 'Authorization: Bearer YOUR_API_KEY'
import requests

response = requests.get(
    'https://api.kycgenie.com/api/v2/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

risk_profile = response.json()
print(f"Match: {risk_profile['name']}")
print(f"Score: {risk_profile['matching_score']}")
print(f"Has PEP: {bool(risk_profile['pep'])}")
print(f"Has Sanctions: {bool(risk_profile['sanctions'])}")
from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

risk_profile = client.risk_profiles.get_details(
    risk_profile_id="f67f165d-0d1e-4eb7-81e6-3494a260dcd4"
)
print(f"Match: {risk_profile.name}")
print(f"Score: {risk_profile.matching_score}")
const response = await fetch(
  'https://api.kycgenie.com/api/v1/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

const riskProfile = await response.json();
console.log(`Match: ${riskProfile.name}`);
console.log(`Score: ${riskProfile.matching_score}`);
const response = await fetch(
  'https://api.kycgenie.com/api/v2/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

const riskProfile = await response.json();
console.log(`Match: ${riskProfile.name}`);
console.log(`Score: ${riskProfile.matching_score}`);

Response Example

{
    "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
    "name": "Jane Smith - PEP, Sanctions",
    "status": "not_reviewed",
    "matching_score": 0.92,
    "aml_types": ['sanction', 'pep', 'pep-class-1', 'adverse-media', 'adverse-media-v2-financial-aml-cft', 'fitness-probity'],
    "has_pep": true,
    "has_sanctions": true,
    "has_adverse_media": false,
    "has_watchlists": false,
    "pep": [
        {
        "name": "Example PEP - John Doe",
        "aml_types": ["pep", "pep-class-1"],
        "country_codes": ["GB"],
        "political_positions": ["Member of Parliament"],
        "listing_started_utc": "2019-01-01T00:00:00Z",
        "listing_ended_utc": null,
        "fields": [
            { "name": "Date of Birth", "tag": "date_of_birth", "value": "1975-03-22" },
            { "name": "Country", "tag": null, "value": "United Kingdom" }
        ]
        }
    ],
    "sanctions": [
        {
        "name": "OFAC SDN List",
        "aml_types": ["sanction"],
        "country_codes": ["GB"],
        "listing_started_utc": "2023-06-15T00:00:00Z",
        "listing_ended_utc": null,
        "fields": [
            { "name": "Designation Date", "tag": null, "value": "2023-06-15" },
            { "name": "Program", "tag": null, "value": "RUSSIA-EO14024" },
            { "name": "Sanction Type", "tag": null, "value": "Block" }
        ]
        }
    ],
    "media": [
        {
        "title": "MP faces corruption inquiry over undisclosed payments",
        "snippet": "An investigation has been launched following allegations of undisclosed payments...",
        "url": "https://news.example.com/article/12345",
        "publishing_date": "2024-11-08T00:00:00Z"
        }
    ],
    "watchlists": [
        {
        "name": "UK Companies House Disqualified Directors",
        "aml_types": ["fitness-probity"],
        "listing_started_utc": "2024-01-10T00:00:00Z",
        "listing_ended_utc": null,
        "fields": [
            { "name": "Enforcement Agency", "tag": null, "value": "United Kingdom Companies House" }
        ]
        }
    ]
}

Update Risk Profile Status

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

Update the review status of a risk profile as you investigate whether it is 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, or true_positive

Update Status

curl -X PATCH \
  'https://api.kycgenie.com/api/v1/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/status/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-12345' \
  -d '{
    "status": "false_positive"
  }'
curl -X PATCH \
  'https://api.kycgenie.com/api/v2/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-12345' \
  -d '{
    "status": "false_positive"
  }'
import requests

response = requests.patch(
    'https://api.kycgenie.com/api/v2/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Idempotency-Key': 'unique-key-12345'
    },
    json={'status': 'false_positive'}
)

updated = response.json()
print(f"Status updated to: {updated['status']}")
from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

result = client.risk_profiles.update_status(
    risk_profile_id="f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
    status="false_positive"
)
print(f"Status updated to: {result.status}")
const response = await fetch(
  'https://api.kycgenie.com/api/v1/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/status/',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'unique-key-12345'
    },
    body: JSON.stringify({ status: 'false_positive' })
  }
);

const updated = await response.json();
console.log(`Status updated to: ${updated.status}`);
const response = await fetch(
  'https://api.kycgenie.com/api/v2/risk-profiles/f67f165d-0d1e-4eb7-81e6-3494a260dcd4/',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'unique-key-12345'
    },
    body: JSON.stringify({ status: 'false_positive' })
  }
);

const updated = await response.json();
console.log(`Status updated to: ${updated.status}`);
↑ ↓ to navigate • Enter to select • Esc to close