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

⚠️ Required: details.legalName is always required, for every profile type — including individual. It holds the full name of the business or person. There is no separate firstName/lastName pair at the profile level.

{
  "name": "Creditsafe Ltd",
  "type": "company",
  "details": {
    "legalName": "Creditsafe Ltd",
    "organizationNumber": "03495298",
    "vatNo": "GB12345678"
  }
}

{
  "name": "John Smith",
  "type": "individual",
  "details": {
    "legalName": "John Smith",
    "dateOfBirth": "1980-05-15",
    "countryCode": "GB"
  }
}

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

{
  "items": [
    {
      "id": "hit-123",
      "hitScore": 92,
      "name": "Creditsafe Holdings Ltd",
      "match": "Creditsafe Holdings Ltd",
      "countries": ["GB"],
      "datasets": ["AM"],
      "decision": "undecided",
      "note": null,
      "modifiedAt": "2026-07-16T10:30:00Z",
      "createdAt": "2026-07-16T09:00:00Z"
    }
  ],
  "totalSize": 1
}

Note: The response is a paginated collection (items + totalSize), not a bare array. Hits do not carry a riskRating — that field belongs to the profile/search, not the individual hit.

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)

⚠️ Prerequisite: The search must already be linked to a profile (Step 4) before it can be added to monitoring.

POST /compliance/kyc-protect/schedules

{
  "items": [
    {
      "searchId": "search-456",
      "threshold": 85,
      "datasets": ["AM", "SAN"],
      "isEmailRequired": true,
      "emailRecipients": ["alerts@yourdomain.com"]
    }
  ]
}

Body is { "items": [...] } — an array of schedule objects, one per search. There is no frequency (daily/weekly/monthly) setting; monitoring runs on Creditsafe's schedule and re-screens using the threshold/datasets given here.

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

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

Note: The array key is items (list of profile IDs), not profileIds.

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",
      "safeNumber": "GB1234567",
      "companyId": "company-789",
      "ruleName": "directorChange",
      "previousValue": "Jane Doe",
      "newValue": "John Smith",
      "eventAt": "2026-07-16T10:30:00Z",
      "status": "open",
      "note": null,
      "createdAt": "2026-07-16T10:30:05Z",
      "createdById": 1015,
      "createdBy": "compliance.user@company.com",
      "modifiedAt": null,
      "modifiedById": null,
      "modifiedBy": null
    }
  ],
  "totalSize": 1
}

Note: There is no alertType, description, or severity field. The alert object identifies the change via ruleName (what triggered it), previousValue/newValue (what changed), and eventAt (when the underlying change happened, as distinct from createdAt — when the alert record itself was created).

Update the status of a KYC alert after review.

Applies To: Business & Individual workflows (identical)

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

Only status and note are accepted — the endpoint does not accept alertType or any other field.

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

{
  "id": "alert-456",
  "profileId": "profile-123",
  "safeNumber": "GB1234567",
  "companyId": "company-789",
  "ruleName": "directorChange",
  "previousValue": "Jane Doe",
  "newValue": "John Smith",
  "eventAt": "2026-07-16T10:30:00Z",
  "status": "closedProcessed",
  "note": "Director change verified and documented in compliance records",
  "createdAt": "2026-07-16T10:30:05Z",
  "createdById": 1015,
  "createdBy": "compliance.user@company.com",
  "modifiedAt": "2026-07-16T11:00:00Z",
  "modifiedById": 1015,
  "modifiedBy": "compliance.user@company.com"
}

Note: There is no alertType, updatedAt, or updatedBy field. The response is the full alert object (same shape as Step 9) with modifiedAt/modifiedById/modifiedBy now populated.

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
  - threshold (75-100)
  - datasets (array)
  - hitDecision (undecided/trueMatch/falsePositive)
  - alertStatus (open/closedProcessed/closedUnprocessed)

Optional:
  - organizationNumber, vatNo
  - searchCountryCodes
  - hitNote
  - emailRecipients, isEmailRequired (schedule notifications)
  - alertNote

Required:
  - username, password
  - profileName
  - legalName
  - name OR (firstName + lastName)  (for AML search)
  - threshold (75-100)
  - datasets (array)
  - hitDecision
  - alertStatus (open/closedProcessed/closedUnprocessed)

Optional:
  - dateOfBirth, countryCode (profile details)
  - middleName, gender (AML search only)
  - searchCountryCodes
  - hitNote
  - emailRecipients, isEmailRequired (schedule notifications)
  - 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: Keep schedule threshold/datasets aligned to your current risk criteria — there is no separate run-frequency setting
• 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>