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"
    }
  ]
}

Identifier Matching

Identifier and document matching is value-first. An exact ID or document number matches a list entry regardless of how the document-type label is named on either side (CI, DNI, National ID, document_id, a numeric id, etc.). Values are normalized before comparison (non-alphanumeric characters stripped, case-insensitive). This means you do not need to send document_type to get an exact identifier hit — document_id alone is enough:

{
  "subject": {
    "full_name": "Jane Roe",
    "document_id": "30708422459"
  },
  "list_name": "senaclaft_uy"
}

The match works whether the number is stored on the list entry as ci, document_id, a numeric id, or inside an identifiers[] array. Sending document_type (or the identifiers array) is still supported and never blocks a match. An exact identifier match always returns confidence_score: 1.0.

nationality and birth_date refine name-based matches only (and may lower confidence on a mismatch). They never affect an exact identifier match.

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

OFAC Metadata Fields

When an OFAC entry includes public identity metadata, the API returns it inside matches[*].match_data:

nationality
birth_date
identifiers (array with document/wallet/tax identifiers depending on list entry data)

Example:

{
  "match_data": {
    "match_type": "composite",
    "name": "Allan Estuardo RODRIGUEZ REYES",
    "nationality": "Guatemala",
    "birth_date": "19 Oct 1981",
    "identifiers": [
      { "type": "national id no.", "value": "2754422680101" },
      { "type": "passport", "value": "F5573390" }
    ]
  }
}

Note: Metadata availability depends on source list data. If a source entry does not publish nationality/identifiers, those fields may be absent.

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

​Endpoint

​Authentication

​Request Body Parameters

​Subject Parameter Details

​Required Fields

​Entity Types

​Identifiers Array Format

​Identifier Matching

​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

​OFAC Metadata Fields

​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

Endpoint

Authentication

Request Body Parameters

Subject Parameter Details

Required Fields

Entity Types

Identifiers Array Format

Identifier Matching

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

OFAC Metadata Fields

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