List Check - KYC API Documentation

Check entities against KYC watchlists (OFAC, UN, EU, UK, and many more) to identify sanctions, PEPs (Politically Exposed Persons), crypto-related risks, and other risk entities.

Endpoint

POST /kyc

Authentication

Requires kyc:create permission. Include your Bearer token in the Authorization header.

Request Body Parameters

Subject Parameter Details

Required Fields

At least one of the following must be provided:

Field	Required If	Description
`full_name`	No identifiers provided	Full name of the entity
`document_id`	No full_name provided	Government-issued ID
`wallet_address`	No full_name provided	Cryptocurrency wallet
`identifiers`	No full_name provided	Array of identifier objects
`imo_number`	No full_name provided	IMO number for vessels

Entity Types

Type	Description
`individual`	Natural person
`company`	Business or corporation
`organization`	Non-profit, government agency, etc.
`vessel`	Ships, boats (use with `imo_number`)
`aircraft`	Airplanes, helicopters (use with `call_sign`)

Identifiers Array Format

When using the identifiers field, provide an array of objects:

{
  "identifiers": [
    {
      "type": "Ethereum Wallet",
      "value": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    },
    {
      "type": "Bitcoin Address",
      "value": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
    },
    {
      "type": "Passport",
      "value": "AB1234567"
    }
  ]
}

Available Watchlists

Government Sanctions Lists

List Name	Description	Entity Types Supported
`ofac`	OFAC SDN List (US Treasury)	Persons, Organizations, Vessels
`un`	UN Security Council Consolidated List	Persons, Organizations
`eu`	EU Financial Sanctions List	Persons, Organizations
`uk`	UK Sanctions List (OFSI)	Persons, Organizations
`canada`	Canada Consolidated Autonomous Sanctions	Persons, Organizations
`australia`	Australia DFAT Consolidated List	Persons, Organizations
`switzerland`	Switzerland SECO Sanctions	Persons, Organizations

US Export Control Lists

List Name	Description	Entity Types Supported
`us_csl`	US Consolidated Screening List (CSL)	Persons, Organizations
`bis_denied_persons`	BIS Denied Persons List	Persons
`bis_entity_list`	BIS Entity List	Organizations

Regional & Specialized Lists

List Name	Description	Entity Types Supported
`senaclaft_uy`	SENACLAFT Uruguay PEP List	Persons
`world_bank`	World Bank Debarred Firms & Individuals	Persons, Organizations

Cryptocurrency Lists

List Name	Description	Identifier Types
`ransomwhere`	Ransomwhe.re Ransomware Addresses	Bitcoin, Ethereum wallets
`nbctf`	NBCTF Israel Sanctioned Crypto Wallets	Crypto wallets

Search Types

Type	Description	Use Case
`exact`	Exact name matching	High precision, strict matching
`fuzzy`	Approximate string matching	Handle typos and variations
`token`	Word-based matching	Find partial name matches
`composite`	Combined strategy (default)	Balanced precision and recall
`llm_enhanced`	AI-powered matching	Maximum precision with semantic filtering

Request Examples

Check Person Against Single List

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "John Doe",
      "nationality": "US",
      "birth_date": "1985-03-15"
    },
    "list_name": "ofac",
    "search_type": "composite"
  }'

Check Person with Document ID

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "Juan Pérez",
      "document_id": "12345678",
      "document_type": "CI",
      "nationality": "UY"
    },
    "list_name": "senaclaft_uy"
  }'

Check Cryptocurrency Wallet

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    },
    "lists": ["ofac", "ransomwhere", "nbctf"]
  }'

Check Company

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "Acme Corporation",
      "entity_type": "company",
      "tax_id": "12-3456789",
      "incorporation_country": "US"
    },
    "lists": ["ofac", "bis_entity_list", "world_bank"]
  }'

Check Vessel by IMO Number

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "MV Oceanstar",
      "entity_type": "vessel",
      "imo_number": "9123456",
      "call_sign": "V7AB3"
    },
    "list_name": "ofac"
  }'

Check Multiple Lists

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "John Doe",
      "nationality": "US"
    },
    "lists": ["ofac", "un", "eu", "uk", "canada"],
    "search_type": "composite"
  }'

Check with Multiple Identifiers

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "John Doe",
      "identifiers": [
        {
          "type": "Ethereum Wallet",
          "value": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
        },
        {
          "type": "Bitcoin Address",
          "value": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
        }
      ]
    },
    "lists": ["ofac", "ransomwhere"]
  }'

Save Validation for Dashboard

Use save_validation: true to store the validation result and view it later in the dashboard:

curl -X POST https://kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "full_name": "John Doe",
      "nationality": "US",
      "document_id": "AB1234567",
      "document_type": "Passport"
    },
    "lists": ["ofac", "un", "eu"],
    "search_type": "composite",
    "save_validation": true
  }'

Response Format

Success Response (Single List)

{
  "status": "success",
  "data": {
    "list_name": "ofac",
    "subject": {
      "full_name": "John Doe",
      "nationality": "US"
    },
    "is_match": true,
    "match_count": 1,
    "matches": [
      {
        "confidence_score": 0.95,
        "match_type": "composite",
        "matched_field": "name",
        "entity": {
          "id": "12345",
          "name": "JOHN DOE",
          "entity_type": "individual",
          "aliases": ["Johnny Doe"],
          "programs": ["SDGT"],
          "nationality": "US",
          "listing_date": "2020-01-15"
        }
      }
    ],
    "processing_time_ms": 1250
  },
  "meta": {
    "request_id": "abc-123-def",
    "timestamp": "2024-11-22T10:30:00Z",
    "processing_time_ms": 1250,
    "api_version": "2.0"
  }
}

Success Response (Multiple Lists)

{
  "status": "success",
  "data": {
    "subject": {
      "full_name": "John Doe",
      "nationality": "US"
    },
    "results": {
      "ofac": {
        "list_name": "ofac",
        "is_match": true,
        "match_count": 1,
        "matches": [...]
      },
      "un": {
        "list_name": "un",
        "is_match": false,
        "match_count": 0,
        "matches": []
      },
      "eu": {
        "list_name": "eu",
        "is_match": false,
        "match_count": 0,
        "matches": []
      }
    },
    "summary": {
      "total_lists_checked": 3,
      "total_matches": 1,
      "lists_with_matches": ["ofac"],
      "overall_risk_level": "HIGH",
      "recommended_action": "REVIEW - Manual review required before proceeding.",
      "requires_manual_review": true
    },
    "total_lists_checked": 3,
    "total_matches": 1,
    "has_matches": true,
    "overall_risk_level": "HIGH"
  },
  "meta": {
    "request_id": "abc-123-def",
    "timestamp": "2024-11-22T10:30:00Z",
    "processing_time_ms": 3200,
    "api_version": "2.0"
  }
}

No Match Response

{
  "status": "success",
  "data": {
    "list_name": "ofac",
    "subject": {
      "full_name": "Jane Smith",
      "nationality": "CA"
    },
    "is_match": false,
    "match_count": 0,
    "matches": [],
    "processing_time_ms": 850
  },
  "meta": {
    "request_id": "abc-123-def",
    "timestamp": "2024-11-22T10:30:00Z",
    "processing_time_ms": 850,
    "api_version": "2.0"
  }
}

Risk Levels

The API returns risk assessments based on match confidence:

Risk Level	Recommended Action
`CRITICAL`	BLOCK - Immediate escalation required. Do not proceed.
`HIGH`	REVIEW - Manual review required before proceeding.
`MEDIUM`	CAUTION - Enhanced monitoring recommended.
`LOW`	PROCEED - Standard monitoring applies.

Error Responses

400 Bad Request - Missing Subject

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Subject must have at least one of: full_name, document_id, wallet_address, identifiers, or imo_number"
  },
  "meta": {
    "request_id": "abc-123-def",
    "timestamp": "2024-11-22T10:30:00Z",
    "api_version": "2.0"
  }
}

400 Bad Request - Invalid List

{
  "status": "error",
  "error": {
    "code": "LIST_NOT_FOUND",
    "message": "List 'invalid_list' not found"
  },
  "meta": {
    "request_id": "abc-123-def",
    "timestamp": "2024-11-22T10:30:00Z",
    "api_version": "2.0"
  }
}

400 Bad Request - Invalid Birth Date

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "birth_date must be in ISO format (YYYY-MM-DD)",
    "field": "subject.birth_date"
  },
  "meta": {
    "request_id": "abc-123-def",
    "timestamp": "2024-11-22T10:30:00Z",
    "api_version": "2.0"
  }
}

403 Forbidden - Missing Permission

{
  "message": "User is not authorized to perform this action"
}

Status Codes

Code	Description
200	Success - Check completed
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
500	Internal Server Error

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

​Endpoint

​Authentication

​Request Body Parameters

​Subject Parameter Details

​Required Fields

​Entity Types

​Identifiers Array Format

​Available Watchlists

​Government Sanctions Lists

​US Export Control Lists

​Regional & Specialized Lists

​Cryptocurrency Lists

​Search Types

​Request Examples

​Check Person Against Single List

​Check Person with Document ID

​Check Cryptocurrency Wallet

​Check Company

​Check Vessel by IMO Number

​Check Multiple Lists

​Check with Multiple Identifiers

​Save Validation for Dashboard

​Response Format

​Success Response (Single List)

​Success Response (Multiple Lists)

​No Match Response

​Risk Levels

​Error Responses

​400 Bad Request - Missing Subject

​400 Bad Request - Invalid List

​400 Bad Request - Invalid Birth Date

​403 Forbidden - Missing Permission

​Status Codes