Individual AML Search Workflow

This page describes the production-focused AML screening workflow for individual persons:

1. Authenticate - Generate authentication token
2. Create Individual AML Search - Submit person screening request
3. Retrieve AML Hits - Get list of potential matches
4. Retrieve Full AML Intelligence - Get detailed compliance data

This deterministic sequence helps teams integrate quickly and reduces implementation ambiguity.

Diagram summary: This flowchart shows a single linear path with four steps: authenticate, create an individual AML search, retrieve individual AML search hits, and retrieve full individual AML hit details.

Workflow Summary: Authenticate with the platform, perform an individual AML screening search using personal details, retrieve screening hits, and retrieve detailed compliance intelligence for a selected match.

Before accessing any KYC Protect endpoints, an authentication token must be generated.

The returned bearer token should be included in the Authorization header for all subsequent requests.

POST /authenticate

{
  "username": "your-username",
  "password": "your-password"
}

{
  "token": "eyJhbGciOi..."
}

Create an Individual AML screening search using the supplied personal details.

The API performs screening across the configured AML datasets and returns a unique search identifier in the id field.

POST /compliance/kyc-protect/searches/individuals

{
  "name": "John Smith",
  "firstName": "John",
  "middleName": "Andrew",
  "lastName": "Smith",
  "dateOfBirth": "1980-05-15",
  "gender": "male",
  "countryCodes": ["GB"],
  "threshold": 80,
  "datasets": ["AM", "PEP", "SAN"]
}

Name Field Requirements:

• Option 1: Provide name (full name as single string)
• Option 2: Provide firstName AND lastName (with optional middleName)

{
  "id": "7ba85f64-8821-4562-c4gd-3d074g77bgb7",
  "firstName": "John",
  "middleName": "Andrew",
  "lastName": "Smith",
  "dateOfBirth": "1980-05-15",
  "gender": "male",
  "countryCodes": ["GB"],
  "threshold": 80,
  "type": "individual",
  "datasets": ["AM", "PEP", "SAN"],
  "status": "new",
  "riskRating": "veryLow",
  "totalHitCount": 3
}

Retrieve AML screening hits associated with the previously created individual AML search.

Each hit represents a potential AML match and includes a unique hitId required for retrieval of the detailed AML intelligence profile.

GET /compliance/kyc-protect/searches/individuals/{searchId}/hits

[
  {
    "id": "hit-789",
    "firstName": "John",
    "middleName": "A",
    "lastName": "Smith",
    "dateOfBirth": "1980-05-15",
    "riskRating": "medium",
    "datasets": ["PEP"]
  }
]

Retrieve the full compliance intelligence profile for a selected individual AML hit.

This endpoint provides detailed AML information associated with the selected screening result.

GET /compliance/kyc-protect/searches/individuals/{searchId}/hits/{hitId}

{
  "id": "hit-789",
  "firstName": "John",
  "middleName": "A",
  "lastName": "Smith",
  "dateOfBirth": "1980-05-15",
  "gender": "male",
  "riskRating": "medium",
  "country": "GB",
  "datasets": ["PEP"],
  "adverseMedia": [],
  "sanctions": [],
  "pep": []
}

Diagram summary: This sequence diagram shows the client authenticating first, then creating an individual search, retrieving hits for that search, and finally retrieving full details for one selected hit.

Diagram summary: This decision flow shows success and failure paths for each stage: authentication, search creation, hit retrieval, and detailed hit retrieval, ending in workflow completion or a stage-specific failure outcome.

All requests following authentication must include the bearer token in the request header.

Authorization: Bearer <token>

The threshold property controls match sensitivity.

Recommended production threshold values typically range between 80–90.

The datasets property controls which screening datasets are evaluated during AML screening.

{
  "datasets": ["AM", "PEP", "SAN"]
}

Dataset definitions are documented separately within the KYC Protect documentation.

• PEP datasets include both current and former politically exposed persons
• PEP tier filtering can refine results by tier level
• Some datasets available for business searches may not be available for individual searches

Required:
  - username (string)
  - password (string)
  - threshold (integer: 75, 80, 85, 90, 95, or 100)
  - datasets (array)
  - name OR (firstName + lastName)

Optional:
  - middleName (string)
  - dateOfBirth (string, format: date)
  - gender (string: "male" or "female")
  - countryCodes (array, default: ["GB"])