KYC Protect Basic Integration Process

This page describes the complete production integration workflow for KYC Protect, applicable to both business entities and individual persons:

1. Authenticate - Generate authentication token
2. Create Profile - Establish entity profile for grouping and monitoring
3. Run AML Screening - Execute comprehensive AML search (business or individual)
4. Link Search to Profile - Associate search results with profile
5. Review AML Hits - Retrieve and analyze screening matches
6. Update Hit Decisions - Classify matches (true match, false positive, undecided)
7. Enable AML Monitoring - Configure ongoing monitoring schedules
8. Enable KYC Monitoring - Set up country-specific compliance monitoring
9. Retrieve KYC Alerts - Get list of monitoring alerts for the profile
10. Update Alert Status - Classify and resolve KYC alerts

ℹ️ Important: This workflow is identical for both business and individual screening. The only differences are in Steps 2-3 (profile creation and AML search endpoints/parameters). All other steps use the same APIs and follow the same pattern.

Diagram summary: Authenticate, create a profile, run AML screening, link searches to the profile, review and update hits, add searches to AML monitoring and update schedules, and optionally add profiles to KYC monitoring to review alerts and update alert statuses.

Diagram summary: This sequence diagram shows the complete integration flow for both business and individual entities, with the only variation being the specific search endpoint used in Step 3.

Diagram summary: This decision flow shows success and failure paths for each stage, applicable to both business and individual workflows. Note: If country doesn't support KYC monitoring at decision point O, the workflow skips Steps 8-10 and completes successfully at Step 7.

All endpoints follow standard Connect API error patterns. Errors include a correlationId for support tracking.

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Validation failed",
  "details": "threshold must be one of: 75, 80, 85, 90, 95, 100"
}

• 401 (Unauthorized): Re-authenticate once, then fail
• 403 (Forbidden): Do not retry (permission issue)
• 404 (Not Found): Do not retry in workflow (indicates data flow error)
• 409 (Conflict): Do not retry (resource already exists)
• 500/503 (Server Errors): Retry up to 3 times with exponential backoff

Before using any of the endpoints, you must authenticate. This ensures you have the necessary permissions to access the data.

Applies To: Business & Individual workflows

POST /authenticate

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

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

Profiles are required for grouping searches, monitoring, and audit trails. The profile structure differs slightly between business and individual entities.

Key Difference: Use appropriate type and details structure for your entity.

POST /compliance/kyc-protect/profiles

{
  "name": "Creditsafe Ltd",
  "type": "company",
  "details": {
    "legalName": "Creditsafe Ltd",
    "registrationNumber": "03495298",
    "countryCode": "GB"
  }
}

{
  "name": "John Smith",
  "type": "individual",
  "details": {
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "1980-05-15"
  }
}

Execute comprehensive AML screening. Choose the appropriate endpoint based on entity type.

Key Difference: Use /searches/businesses for companies or /searches/individuals for persons.

POST /compliance/kyc-protect/searches/businesses

{
  "countryCodes": ["GB"],
  "threshold": 85,
  "name": "Creditsafe",
  "datasets": ["AM"]
}

POST /compliance/kyc-protect/searches/individuals

{
  "threshold": 80,
  "name": "Donald Trump",
  "datasets": ["AM", "PEP"]
}

{
  "threshold": 80,
  "firstName": "Donald",
  "lastName": "Trump",
  "dateOfBirth": "1946-06-14",
  "gender": "male",
  "datasets": ["AM", "PEP", "SAN"]
}

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "Creditsafe Ltd",
  "threshold": 85,
  "type": "business",
  "datasets": ["AM"],
  "status": "new",
  "riskRating": "veryLow",
  "totalHitCount": 1
}

Note: Response structure is identical. The type field indicates "business" or "individual".

ℹ️ Important: Steps 4-10 use identical endpoints and processes for both business and individual entities. Simply use the searchId from Step 3 in the appropriate endpoint path.

Attach the search to the profile for future monitoring.

Applies To: Business & Individual workflows (identical)

POST /compliance/kyc-protect/profiles/{profileId}/searches/link

{
  "searchIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"]
}

Retrieve screening hits for review.

Applies To: Business & Individual workflows (use appropriate path)

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

[
  {
    "id": "hit-123",
    "name": "Creditsafe Holdings Ltd",
    "riskRating": "medium",
    "datasets": ["AM"]
  }
]

Classify each hit with a decision.

Applies To: Business & Individual workflows (use appropriate path)

PUT /compliance/kyc-protect/searches/{businesses|individuals}/{searchId}/hits/{hitId}

{
  "decision": "trueMatch",
  "note": "Confirmed match after manual review"
}

Configure ongoing monitoring schedules.

Applies To: Business & Individual workflows (identical)

POST /compliance/kyc-protect/schedules

{
  "profileId": "profile-123",
  "searchIds": ["search-456"],
  "email": "alerts@yourdomain.com",
  "frequency": "daily"
}

Set up country-specific compliance monitoring (if supported).

Applies To: Business & Individual workflows (identical)

• Profile must have a valid safeNumber
• Country must support KYC monitoring

GET /compliance/kyc-protect/lookup/kycMonitoring/countryCodes

If country not supported: Skip Steps 8-10 (KYC monitoring unavailable). Workflow completes at Step 7.

POST /compliance/kyc-protect/kycMonitoring/profiles/bulk

{
  "profileIds": ["profile-123"]
}

Retrieve monitoring alerts generated for the profile.

Applies To: Business & Individual workflows (identical)

GET /compliance/kyc-protect/kycMonitoring/profiles/{profileId}/alerts

GET /compliance/kyc-protect/kycMonitoring/profiles/profile-123/alerts?statuses=Open
Authorization: Bearer <token>

{
  "items": [
    {
      "id": "alert-456",
      "profileId": "profile-123",
      "alertType": "directorChange",
      "status": "Open",
      "createdAt": "2026-07-16T10:30:00Z",
      "description": "New director appointed",
      "severity": "medium"
    }
  ],
  "totalSize": 1
}

Update the status of a KYC alert after review.

Applies To: Business & Individual workflows (identical)

PUT /compliance/kyc-protect/kycMonitoring/profiles/{profileId}/alerts/{alertId}

{
  "status": "ClosedProcessed",
  "note": "Director change verified and documented in compliance records"
}

{
  "id": "alert-456",
  "profileId": "profile-123",
  "alertType": "directorChange",
  "status": "ClosedProcessed",
  "note": "Director change verified and documented in compliance records",
  "updatedAt": "2026-07-16T11:00:00Z",
  "updatedBy": "user@company.com"
}

Diagram summary: Data flows from authentication through profile creation, search execution, linking, hit management, and monitoring setup.

Required:
  - username, password
  - profileName, profileType (company/plc/etc.)
  - legalName, businessName
  - threshold (75-100)
  - datasets (array)
  - hitDecision (undecided/trueMatch/falsePositive)
  - monitoringEmail
  - alertStatus (Open/ClosedProcessed/ClosedUnprocessed)

Optional:
  - registrationNumber, countryCode
  - searchCountryCodes
  - hitNote
  - monitoringFrequency (daily/weekly/monthly)
  - alertNote

Required:
  - username, password
  - profileName
  - name OR (firstName + lastName)
  - threshold (75-100)
  - datasets (array)
  - hitDecision
  - monitoringEmail
  - alertStatus (Open/ClosedProcessed/ClosedUnprocessed)

Optional:
  - middleName, dateOfBirth, gender
  - searchCountryCodes
  - hitNote
  - monitoringFrequency
  - alertNote

• Profile Naming: Include legal name and identifier (registration number or DOB)
• Hit Decisions: Always include descriptive notes for audit trails
• Dataset Selection: Use AM + SAN minimum; add PEP for individuals
• Monitoring: Set frequency based on risk profile
• Thresholds: Use 85 for balanced production screening
• Alert Management: Review KYC alerts promptly and document actions taken
• Alert Status: Use ClosedProcessed when action taken, ClosedUnprocessed for false positives

All requests following authentication must include:

Authorization: Bearer <token>