ID verification flow integration

ID verification flow integration

An example of how ID collection and verification can be integrated into your onboarding workflow.

Overview

This guide describes how to integrate Xama’s client onboarding, identity verification, and AML screening capabilities into your application. The integration streamlines the collection of ID documentation, identity verification, and compliance checks as part of your customer onboarding workflow.

Integration Capabilities

This integration enables you to:

• Create clients and contacts in Xama programmatically
• Trigger onboarding requests to collect ID documents and personal information
• Embed verification links in your own onboarding portal or send via email
• Receive real-time notifications when verification is complete via webhooks
• Analyze verification results including document checks and face matching
• Copy verified data back to contact records
• Initiate AML checks for identity verification and PEP/Sanctions screening
• Review screening results and make compliance decisions

Prerequisites

Before starting the integration, ensure you have:

1. Completed the Authentication guide and obtained your OAuth2 credentials
2. A Xama account created at https://platform.xamatech.com
3. Your Client ID from the Xama platform
4. Email connection configured in Xama (if sending onboarding emails): https://platform.xamatech.com/portal/hub/settings/email-settings
5. Familiarity with the Xama training materials (available in the platform’s training center)

Understanding Xama Terminology

Before working with the API, it’s important to understand how Xama uses certain terms:

Xama UI Term	API Term	Description
Client	Account	A client record as shown in the Xama interface (company, individual, trust, etc.)
N/A	Client	Your Xama customer account - used as {clientId} in all API calls
Contact	Contact	An individual person associated with an account
Onboarding level	Level	A reusable, named bundle of onboarding stages. Not a risk level

Integration Workflow

The typical onboarding flow follows this sequence:

1. Create client and contacts in Xama
2. Trigger onboarding request to collect documents
3. Contact completes verification via email link or embedded portal
4. Receive webhook notification when verification is complete
5. Analyze results and check document/face match decisions
6. Copy verified data to contact record
7. Trigger AML check for identity verification and screening
8. Review screening results for PEP/Sanctions matches
9. Complete compliance workflow based on results

Workflow Diagram

The verification journey follows this high-level flow:

API Endpoints and Implementation

Create Client and Contacts

Before triggering onboarding requests, you must create the client (account) and associated contacts in Xama.

Create Client with Primary Contact

Endpoint

POST /clients/{clientId}/accounts

Request Example

curl -X POST "https://xamahub.xamatech.com/api/clients/{clientId}/accounts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "name": "Acme Corporation",
    "type": "COMPANY",
    "reg_number": "12345678",
    "primary_contact": {
      "first_name": "John",
      "middle_name": "Robert",
      "last_name": "Smith",
      "email": "john.smith@acme.com",
      "phone": "+44 20 1234 5678",
      "date_of_birth": "1985-03-15",
      "driving_license_number": "SMITH123456JR9AB",
      "driving_license_expiry_date": "2030-03-15",
      "passport_number": "123456789<<<<01",
      "passport_expiry_date": "2029-06-20",
      "primary_address": {
        "street": "123 High Street",
        "postcode": "SW1A 1AA",
        "city": "London",
        "country_code": "GB",
        "type": "PRIMARY"
      }
    }
  }'

Account Type Parameter

Value	Use Case	Description
INDIVIDUAL	B2C relationships	Single-person entities (e.g., personal tax returns, sole traders)
COMPANY	B2B relationships	Multi-contact entities (companies, partnerships, trusts, charities)

Request Parameters

Field	Type	Required	Description
name	string	Yes	Client/company name
type	string	Yes	COMPANY or INDIVIDUAL
reg_number	string	No	Company registration number
primary_contact	object	Yes	Primary contact details

Primary Contact Fields

Field	Type	Required	Description
first_name	string	Yes	Contact’s first name
middle_name	string	No	Contact’s middle name
last_name	string	Yes	Contact’s last name
email	string	Yes	Contact’s email (required for onboarding emails)
phone	string	No	Contact phone number
date_of_birth	string	No	Format: YYYY-MM-DD
driving_license_number	string	No	Driving license number
driving_license_expiry_date	string	No	Format: YYYY-MM-DD
passport_number	string	No	Passport number
passport_expiry_date	string	No	Format: YYYY-MM-DD
primary_address	object	No	Primary residential address

Create Additional Contacts

Add additional contacts (beneficial owners, directors, etc.) to an account.

Endpoint

POST /clients/{clientId}/accounts/{accountId}/contacts

Request Example

curl -X POST "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "first_name": "Jane",
    "middle_name": "Marie",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+44 20 9876 5432",
    "primary_address": {
      "street": "456 Oxford Street",
      "postcode": "W1D 1BS",
      "city": "London",
      "country_code": "GB",
      "type": "PRIMARY"
    }
  }'

Reference: See the Contacts API documentation for complete specifications.

Trigger Onboarding Request

Onboarding requests collect ID documents, selfies, personal details, and proof of address from contacts.

There are two ways to specify what a request should collect. Use an onboarding level — a reusable, named bundle of stages managed in the Xama platform. This is the recommended approach for new integrations. Specifying individual stage flags is still fully supported for existing integrations and is documented under Specifying individual stages below.

Prerequisites for Onboarding Requests

1. Email connection configured (if sending emails): Configure at https://platform.xamatech.com/portal/hub/settings/email-settings
2. Contact must have email address (even if suppressing emails, use a placeholder/internal email)

Using an Onboarding Level (Recommended)

An onboarding level bundles a set of stages under a human-readable name such as “Basic due diligence”. Each of your clients has its own levels, and exactly one is marked as the default. Because levels are configured in the Xama platform, your compliance team can change what a level collects without you shipping a code change.

Note that an onboarding level is not a risk level. The two are unrelated.

Retrieve the available levels

GET /clients/{clientId}/onboarding-levels

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/onboarding-levels" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Response Extract

{
  "total_records": 2,
  "page": 1,
  "items": [
    {
      "id": "8a95d590-4951-11f1-9c12-c5e6a9c8cd22",
      "name": "Basic due diligence",
      "is_default": true,
      "stages": ["idscan", "personal_details", "proof_of_address"],
      "created_at": "2025-06-18T10:28:15.188000Z",
      "updated_at": "2025-06-18T10:28:15.188000Z"
    }
  ]
}

Field	Description
id	The value you pass as level when creating the request
name	Display name — use this as the option text in your UI
is_default	Exactly one level per client is the default. Pre-select it so your UI matches the Xama platform
stages	The stages this level resolves to. Useful for showing the user what the level will collect

To fetch a single level by id, for example to re-display its stages:

GET /clients/{clientId}/onboarding-levels/{levelId}

Drive your level picker from this endpoint rather than hard-coding level names. Levels are client-specific and editable, so a hard-coded list will drift out of sync per client.

Create the request with a level

PUT /clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding

curl -X PUT "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "config": {
      "parameters": {
        "level": "8a95d590-4951-11f1-9c12-c5e6a9c8cd22",
        "suppress_invitation_mail": "false",
        "frontend_redirect_url": "https://yourapp.com/onboarding/complete"
      },
      "ttl_in_days": 365,
      "is_automatic_refresh_enabled": false
    }
  }'

Inside config.parameters:

Parameter	Type	Description
level	string	Id of the onboarding level to apply
mail_template_id	string	Id of the ONBOARDING email template to use. Defaults to the client’s default template
suppress_invitation_mail	boolean	false = Send email; true = Don’t send email (retrieve link manually)
frontend_redirect_url	string	URL to redirect user after completion (optional)

Alongside parameters, on config:

Parameter	Type	Description
ttl_in_days	number	How long the verification remains valid (e.g., 365)
is_automatic_refresh_enabled	boolean	Automatically refresh verification before expiry - not recommended
is_reminder_enabled	boolean	Send reminder emails for this request

And at the root of the request body:

Parameter	Type	Description
trigger_lookup	boolean	Look the contact up against connected data sources as part of creating the request

The parameters object is a map of strings, so send its values as strings — "true" rather than true. Xama always returns them as strings when you read the request back, whatever you sent.

Levels are resolved at creation time

When the request is created, Xama resolves the level into explicit per-stage flags and stores those on the request. This is a snapshot: editing or deleting the level afterwards does not change requests that were already created from it.

Do not combine a level with individual stage flags

Sending level together with individual stage flags such as idscan or proof_of_address in the same request is rejected with:

contact-onboarding-report-service/level/stages-not-allowed-with-level

Use one approach or the other, not both.

Other responses to expect

• Asynchronous initialisation. The call returns before the request has settled. The state moves briefly through INITIAL to INITIATED on success, or to an error state such as CREDIT_BALANCE_EXCEEDED. Re-fetch after a short delay, or use webhooks, to read the settled state.
• 402 Payment Required. Returned if the chosen level contains stages that need a subscription feature the client does not have. Pick a different level rather than retrying.

Choosing the Email Template

Xama sends the invitation email using a template. Retrieve the available ONBOARDING templates and pass the chosen template’s id as mail_template_id on the request above. Omit it to use the client’s default.

GET /clients/{clientId}/mail-templates?q:type=ONBOARDING&q:status=ACTIVE

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/mail-templates?q:type=ONBOARDING&q:status=ACTIVE" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Response Extract

{
  "total_records": 2,
  "page": 1,
  "items": [
    {
      "id": "onboarding-request",
      "type": "ONBOARDING",
      "name": "Onboarding Request",
      "status": "ACTIVE",
      "is_default": true,
      "description": "Default template for contact onboarding requests"
    }
  ]
}

Query parameter	Description
q:type	ONBOARDING and/or CLIENT_ONBOARDING, comma-separated. Omit to return all types
q:status	ACTIVE and/or ARCHIVED, comma-separated. Defaults to ACTIVE

Only offer ACTIVE templates in your UI, and filter to ONBOARDING for onboarding requests. The CLIENT_ONBOARDING type is used for the client portal link instead — see the Client portal integration guide.

To fetch a single template you need both its type and its id:

GET /clients/{clientId}/mail-templates/{mailTemplateType}/{mailTemplateId}

Specifying Individual Stages (Legacy)

Requests can also be created by setting each stage flag explicitly, without a level. This remains supported and is the right choice if your integration predates onboarding levels, or if you need a combination of stages that no level covers. For new integrations, prefer a level.

Request Example

curl -X PUT "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "config": {
      "parameters": {
        "suppress_invitation_mail": "false",
        "frontend_redirect_url": "https://yourapp.com/onboarding/complete",
        "idscan": "true",
        "personal_details": "true",
        "proof_of_identity": "true",
        "selfie": "false",
        "face_match": "false",
        "proof_of_address": "true"
      },
      "ttl_in_days": 365,
      "is_automatic_refresh_enabled": false
    }
  }'

Configuration Parameters

Parameter	Type	Description
suppress_invitation_mail	boolean	false = Send email; true = Don’t send email (retrieve link manually)
frontend_redirect_url	string	URL to redirect user after completion (optional)
personal_details	boolean	Request home address from user
idscan	boolean	Request ID document (passport/license) - use when face_match is false
face_match	boolean	Request ID document + selfie + perform biometric verification
face_match_mobile	boolean	Request ID document + selfie + perform biometric verification over Xama Verify app
unique_mail	boolean	Collect preferred email address
legal_names_history	boolean	Collect legal names history
home_address_history	boolean	Collect address history of 12 months
selfie	boolean	Request selfie without biometric check (use when face_match is false) - not recommended
proof_of_identity	boolean	Request additional proof of identity document
proof_of_address	boolean	Request proof of address document
ttl_in_days	number	How long the verification remains valid (e.g., 365)
is_automatic_refresh_enabled	boolean	Automatically refresh verification before expiry - not recommended

Configuration Guidelines:

• Standard ID verification: idscan: true, face_match: false, selfie: false
• Biometric verification: face_match: true, idscan: false, selfie: false
• Biometric verification (NFC enabled): face_match_mobile: true, idscan: false, selfie: false

Suppressing Emails and Embedding Links

You have two options for delivering the onboarding link to contacts:

Option 1: Email Sent by Xama (Default)

Set suppress_invitation_mail: "false" and Xama will email the link to the contact’s email address.

Option 2: Embed Link in Your Application

Set suppress_invitation_mail: "true" and retrieve the link to embed in your customer portal, onboarding wizard, or other interface.

Retrieve the Onboarding Link:

Endpoint

GET /clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding

Request Example

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Response Extract

{
  "data": {
    "onboarding_url": "https://idscan.xamatech.com/clients/{clientId}/reports/onboarding/{accountId}--{contactId}?key_id=...&token=...",
    "request_sent_at": "2026-05-06T13:01:46.834Z",
    "request_most_recent_sent_at": "2026-05-06T13:01:46.834Z"
  }
}

Use the onboarding_url value to direct users to the verification flow from your application. Treat it as an opaque URL: it carries its own key_id and token, and it is only present while the request still has status INITIATED. Note that the report id is the account id and contact id joined by a double dash.

Frontend Redirect URL:

Set frontend_redirect_url to redirect users back to your application after they complete verification. Without this, users see a generic “Thank you” screen.

Example Use Cases:

• https://yourapp.com/onboarding/success - Return to onboarding wizard
• https://yourapp.com/dashboard?verified=true - Return to dashboard with status
• https://yourapp.com/clients/{clientId}/complete - Return to client record

Setting Up Webhook Subscriptions

Use webhooks to receive real-time notifications when contacts complete onboarding requests, eliminating the need for polling.

Endpoint

POST /clients/{clientId}/subscriptions

Request Example

curl -X POST "https://xamahub.xamatech.com/api/clients/{clientId}/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "callback_url": "https://yourapp.com/webhooks/xama/onboarding",
    "type": "WEBHOOK",
    "config": {
      "api_secret": "your-webhook-secret",
      "entities": [
        {
          "entity": "CONTACT",
          "report_types": ["ONBOARDING"],
          "events": [
            "REPORT_INITIATED",
            "REPORT_READY",
            "REPORT_ERROR",
            "REPORT_CREDIT_LIMIT_EXCEEDED",
            "REPORT_IN_REVIEW",
            "REPORT_REVIEW_COMPLETED"
          ]
        }
      ]
    }
  }'

Configuration Parameters

Field	Type	Description
callback_url	string	Your webhook endpoint URL
type	string	Must be WEBHOOK
api_secret	string	Secret for webhook signature verification
entities[].entity	string	CONTACT for onboarding reports
entities[].report_types	array	["ONBOARDING"] to monitor onboarding requests
entities[].events	array	Events to monitor (see below)

Webhook Events for Onboarding:

Event	Description	Action
REPORT_INITIATED	Onboarding request created	Optional: Update UI to show “pending” status
REPORT_READY	Contact completed verification	Primary event: Retrieve and analyze results
REPORT_ERROR	Error during verification	Handle error, potentially retry
REPORT_CREDIT_LIMIT_EXCEEDED	Account credit limit reached	Contact Xama support
REPORT_IN_REVIEW	Manual review required	Optional: Notify admin team
REPORT_REVIEW_COMPLETED	Manual review finished	Retrieve updated results

Implementation Notes:

• Focus on REPORT_READY for completed verifications
• Verify webhook signatures using your api_secret
• Respond with 2xx status code to acknowledge receipt
• Implement idempotency to handle duplicate webhooks

Analyzing Onboarding Request Results

Once you receive a REPORT_READY webhook notification, retrieve the full onboarding report to analyze verification results.

Endpoint

GET /clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding

Request Example

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/onboarding" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Response Example

{
  "account_id": "ae9a6650-48cb-11ef-b07f-21e051e087da",
  "client_id": "1b62c5a0-03a1-11ee-b515-618e61a59cb4",
  "config": {
    "parameters": {
      "face_match": "true",
      "proof_of_address": "true"
    },
    "ttl_in_days": 365,
    "is_automatic_refresh_enabled": false
  },
  "contact_id": "ae9a6651-48cb-11ef-b07f-21e051e087da",
  "data": {
    "idscan": {
      "date_of_birth": "1970-01-01",
      "document_type": "Passport",
      "passport_number": "564[..]<<<02",
      "document_decision": "PASSED",
      "document_last_name": "SMITH",
      "face_match_decision": "PASSED",
      "document_expiry_date": "2030-01-01",
      "document_given_names": "JOHN ROBERT",
      "document_decision_date": "2024-07-23T08:22:07.3078793",
      "driving_license_number": "56[..]63"
    },
    "report_link": "https://platform.xamatech.com/...",
    "refreshed_at": "2024-07-23",
    "request_sent_at": "2024-07-23T08:19:08.290Z",
    "personal_details": {
      "city": "London",
      "street": "123 High Street",
      "country": "GB",
      "postcode": "SW1A 1AA"
    }
  },
  "id": "ae9a6650-48cb-11ef-b07f-21e051e087da--ae9a6651-48cb-11ef-b07f-21e051e087da",
  "review": {
    "empty": false,
    "notes": "Verified",
    "status": "COMPLETE",
    "decision": "PASSED"
  },
  "revision": "1721722746296",
  "status": "READY",
  "type": "ONBOARDING"
}

Key Response Fields

Field Path	Description
status	Overall status: READY when complete
data.idscan.document_decision	PASSED, REFER, or ALERT
data.idscan.face_match_decision	PASSED or FAILED (if face match enabled)
data.idscan.document_type	Passport or Driving License
data.idscan.document_decision_date	When document was verified
data.idscan.date_of_birth	Extracted from ID document
data.idscan.document_given_names	Given names from document
data.idscan.document_last_name	Last name from document
data.idscan.passport_number	If document type is Passport
data.idscan.driving_license_number	If document type is Driving License
data.idscan.document_expiry_date	Document expiration date
data.personal_details	Address provided by contact
review.decision	Manual review decision (if applicable)
review.notes	Reviewer notes

Decision Logic

Document Decision:

• PASSED - Document verified successfully, data can be trusted
• REFER - Requires manual review, often due to OCR extraction failures
• ALERT - Serious issue (rare: underage, deceased, etc.)

Face Match Decision (if enabled):

• PASSED - Biometric match between ID photo and selfie successful
• FAILED - Biometric match failed

Critical Implementation Notes:

1. **Only accept extracted data if **document_decision: "PASSED" - REFER decisions may indicate OCR extraction errors, so data may be incorrect
2. Check document type before using ID numbers - Use passport_number only if document_type: "Passport", use driving_license_number only if document_type: "Driving License"
3. Handle REFER decisions - Implement manual review workflow or request re-submission

Copying Verified Data to Contact Record

After verifying onboarding results, update the contact record with the verified information.

Important: Xama’s PUT requests replace all contact data. You must include existing data you want to preserve along with new verified data.

Best Practice Workflow

1. Retrieve current contact data via GET request
2. Merge verified data with existing contact data
3. Update contact via PUT request with complete merged data

Retrieve Contact Record

Endpoint

GET /clients/{clientId}/accounts/{accountId}/contacts/{contactId}

Request Example

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Update Contact Record

Endpoint

PUT /clients/{clientId}/accounts/{accountId}/contacts/{contactId}

Request Example

curl -X PUT "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "metadata": {
      "external_reference": "YOUR-CLIENT-ID-123"
    },
    "first_name": "John",
    "middle_name": "Robert",
    "last_name": "Smith",
    "type": "PRIMARY",
    "email": "john.smith@acme.com",
    "phone": "+44 20 1234 5678",
    "date_of_birth": "1970-01-01",
    "driving_license_number": "",
    "driving_license_expiry_date": "",
    "passport_number": "564123456",
    "passport_expiry_date": "2030-01-01",
    "primary_address": {
      "street": "123 High Street",
      "postcode": "SW1A 1AA",
      "city": "London",
      "country_code": "GB"
    }
  }'

Important Notes:

• Country codes: Use ISO-2 format (e.g., GB for United Kingdom, US for United States)
• Blank fields: Set to empty string ("") if not applicable, don’t omit
• Data not included will be cleared: Always retrieve existing data first and include it in the update
• External reference: Use metadata.external_reference to link to your system’s client ID

Triggering AML Checks

An AML check performs electronic identity verification and screens for Politically Exposed Persons (PEPs) and Sanctions matches.

Prerequisites:

• Contact must have sufficient data: full name, date of birth, and address

Endpoint

PUT /clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/aml

Request Example

curl -X PUT "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/aml" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "config": {
      "ttl_in_days": 365,
      "is_automatic_refresh_enabled": false
    }
  }'

Configuration Parameters

Parameter	Type	Description
ttl_in_days	number	How long the AML check remains valid (e.g., 365)
is_automatic_refresh_enabled	boolean	Automatically refresh before expiry

Processing Notes:

• AML checks are asynchronous and take a few seconds to complete
• Use webhooks (recommended) or polling to check for completion
• Results include identity verification decision + PEP/Sanctions screening

Setting Up AML Check Webhooks

Monitor AML check completion with webhooks.

Endpoint

POST /clients/{clientId}/subscriptions

Request Example

curl -X POST "https://xamahub.xamatech.com/api/clients/{clientId}/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "callback_url": "https://yourapp.com/webhooks/xama/aml",
    "type": "WEBHOOK",
    "config": {
      "api_secret": "your-webhook-secret",
      "entities": [
        {
          "entity": "CONTACT",
          "report_types": ["AML"],
          "events": [
            "REPORT_INITIATED",
            "REPORT_READY",
            "REPORT_ERROR",
            "REPORT_CREDIT_LIMIT_EXCEEDED",
            "REPORT_IN_REVIEW",
            "REPORT_REVIEW_COMPLETED"
          ]
        }
      ]
    }
  }'

Focus on the REPORT_READY event to know when AML checks are complete.

Analysing AML Check Results

Retrieve and analyze AML check results after receiving a REPORT_READY webhook.

Endpoint

GET /clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/aml

Request Example

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/accounts/{accountId}/contacts/{contactId}/reports/aml" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Response Example

{
  "account_id": "4552c460-91f2-11ef-96be-935da77d5118",
  "client_id": "1b62c5a0-03a1-11ee-b515-618e61a59cb4",
  "config": {
    "ttl_in_days": 365,
    "is_automatic_refresh_enabled": false
  },
  "contact_id": "4552c461-91f2-11ef-96be-935da77d5118",
  "data": {
    "decision": "PASS",
    "pep_matches": "Potential Match",
    "report_link": "https://platform.xamatech.com/...",
    "refreshed_at": "2024-10-24",
    "sanctions_matches": "No Match",
    "last_decision_date": "2024-10-24"
  },
  "id": "4552c460-91f2-11ef-96be-935da77d5118--4552c461-91f2-11ef-96be-935da77d5118",
  "review": {
    "empty": false,
    "notes": "Reviewed potential PEP match - determined to be false positive",
    "status": "COMPLETE",
    "decision": "PASS",
    "pep_matches": "MATCH_DISMISSED",
    "sanctions_matches": "NO_MATCH"
  },
  "revision": "1729766007467",
  "status": "READY",
  "type": "AML"
}

Key Response Fields

Field	Possible Values	Description
status	READY, INITIAL , CREDIT_BALANCE_EXCEEDED, ERROR	Overall status of the AML check
data.decision	PASS, REFER, ALERT	Identity verification decision
data.pep_matches	No Match, Potential Match	PEP screening result
data.sanctions_matches	No Match, Potential Match	Sanctions screening result
data.last_decision_date	Date	When the check was performed
review.decision	PASS, FAIL	Manual review decision (if reviewed)
review.pep_matches	MATCH_DISMISSED, MATCH_CONFIRMED, NO_MATCH	Reviewed PEP decision
review.sanctions_matches	MATCH_DISMISSED, MATCH_CONFIRMED, NO_MATCH	Reviewed Sanctions decision
review.notes	String	Reviewer notes

Decision Interpretations

Identity Verification Decision (data.decision)

Value	Meaning	Recommended Action
PASS	Identity verified against 2+ authoritative sources	Proceed with onboarding
REFER	Could not verify against 2+ sources	Manual review required or request additional documents
ALERT	Serious issue detected (rare)	Manual review required - may indicate underage, deceased, or other critical issue

PEP Matches (data.pep_matches)

Value	Meaning	Recommended Action
No Match	No PEP matches found	No action required
Potential Match	Possible PEP match requires review	Review match details in Xama platform - most are false positives

Sanctions Matches (data.sanctions_matches)

Value	Meaning	Recommended Action
No Match	No sanctions matches found	No action required
Potential Match	Possible sanctions match requires review	Review - may indicate restricted individual