Basic Integration Process

1. Authenticate

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

Example Request

POST /authenticate

2. Create Profile

Profiles are required for grouping searches, monitoring, and audit trails.

POST /compliance/kyc-protect/profiles

Example Request Body

This example uses only the required parameters. Additional parameters are available for more targeted results. Use the API Documentation for the full list.

{
  "name": "Creditsafe Ltd",
  "type": "company",
  "details": {
    "legalName": "Creditsafe Ltd"
  }
}

Note: Valid profile type values include trust, individual, soletrader, company, plc, partnership, otherEntity.

3. AML Screening

Business Search

POST /compliance/kyc-protect/searches/businesses

Example Request Body

This example uses only the required parameters. Additional parameters are available for more targeted results.

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

Example Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "Creditsafe Ltd",
  "countryCodes": [
    "GB"
  ],
  "threshold": 0,
  "type": "business",
  "datasets": [
    "AM"
  ],
  "status": "new",
  "riskRating": "veryLow",
  "assignedToUserId": 0,
  "assignedUser": "Test User",
  "createdById": 0,
  "createdBy": "Test User",
  "createdAt": "2019-08-24T14:15:22Z",
  "modifiedById": 0,
  "modifiedBy": "Test User",
  "modifiedAt": "2019-08-24T14:15:22Z",
  "note": "No Notes",
  "scheduleId": "b7b4f318-018f-4d71-ac1a-f61e4bfaefbe",
  "totalHitCount": 1,
  "truePositiveHitsCount": 1,
  "falsePositiveHitsCount": 0,
  "undecidedHitsCount": 0,
  "correlationId": "string"
}

Individual Search

POST /compliance/kyc-protect/searches/individuals

Example Request Body

This example uses only the required parameters. Additional parameters are available for more targeted results.

Note: You may use either the name property or a combination of firstName and lastName.

• The name property is required if firstName and lastName are not provided.
• If firstName is used, then lastName becomes required.

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

Example Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "donald trump",
  "threshold": 80,
  "type": "individual",
  "datasets": [
    "AM"
  ],
  "status": "new",
  "riskRating": "notApplicable",
  "assignedToUserId": 0,
  "assignedUser": "test user",
  "createdById": 0,
  "createdBy": "test user",
  "createdAt": "2019-08-24T14:15:22Z",
  "modifiedById": 0,
  "modifiedBy": "test user",
  "modifiedAt": "2019-08-24T14:15:22Z",
  "totalHitCount": 4,
  "truePositiveHitsCount": 0,
  "falsePositiveHitsCount": 0,
  "undecidedHitsCount": 4
}

Important: Not all properties will be returned in every response. Refer to the API documentation for a full list of possible response properties.

PEP Tiering is available for individual searches:

4. Link Search to Profile

Attach a search (by searchId) to a profile for future monitoring. More details can be found here

Incorporating a search into a profile effectively links all associated hits to that profile. This action is critical for maintaining a coherent and relevant record of searches conducted on an entity.

Important Consideration: Adding a search to a profile is a necessary precursor to activating AML monitoring services, ensuring that ongoing surveillance is both relevant and accurate.

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

{
  "searchIds": [
    "abc123-xyz789"
    ]
}

Link to Profile

5. Return AML Search Hits

At this stage, use the searchId from the previous response to retrieve the search hits.

This endpoint returns an array of results. Each result includes a unique id, which is required to retrieve the full details for that hit.

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

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

Additional parameters are available to filter results if needed. Please refer to the main API documentation for Businesses and Individuals.

6. Update AML Hits

There are two options:

• Update each hit one at a time
• Update a batch of hits from a search

Mark each hitId from the previous step with a decision.

Single Hit Update

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

{
  "decision": "trueMatch",
  "note": "Confirmed match"
}

Batch Update

PUT /v1/compliance/kyc-protect/searches/individuals/{searchId}/hits

[
  {
    "hitId": "abc123",
    "decision": "falsePositive"
  }
]

Valid decisions:

• undecided
• trueMatch
• falsePositive

Once changed, undecided cannot be re-applied.

7. Enable AML Monitoring

Once linked, the search can be monitored for changes over time.

POST /compliance/kyc-protect/schedules

Example Request

{
  "profileId": "1234-5678",
  "searchIds": ["abc123"],
  "email": "alerts@yourdomain.com"
}

Note: The response includes a scheduleId required for future schedule management.

8. Enable KYC Monitoring

Only available for selected countries and requires a safeNumber on the profile.

Step 1: Check Available Countries

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

Step 2: Add Profile to Monitoring

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

Step 3: Get Alerts by Profile

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

Step 4: Update Alert Status

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

Additional Notes

• All actions require a valid authenticated token.

• Use appropriate dataset combinations to match your compliance policy.

• Use profile naming conventions to assist with management and auditing.

• Monitor hit decisions closely for audit traceability.