Screen a subject

POST

sanctions

screen

curl -X POST https://api.zquence.ai/v1/sanctions/screen \
  -H "content-type: application/json" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -d '{
    "entityName": "Jane Merchant",
    "entityType": "person",
    "country": "DE",
    "userId": "customer-1842",
    "requestNonce": "onboarding-customer-1842-v1"
  }'

{
  "_id": "68bbd741f4c6f683f94ca210",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "userId": "customer-1842",
  "provider": "sanctionsio",
  "status": "possible_match",
  "matchScore": 0.9425,
  "matchedLists": ["UK-SANCTIONS"],
  "entityName": "Jane Merchant",
  "entityCountry": "DE",
  "requestNonce": "manual:onboarding-customer-1842-v1",
  "billable": true,
  "caseId": "68bbd741f4c6f683f94ca211",
  "attemptId": "68bbd741f4c6f683f94ca212",
  "createdAt": "2026-08-12T10:15:32.000Z",
  "updatedAt": "2026-08-12T10:15:32.000Z"
}

Requires API-key scope sanctions.screen and tenant permission sanctions.screen.execute.

Body

string

required

Legal name to screen.

string

person or business.

string

Country associated with the subject. Use an ISO country code where available.

string

Email used as supporting screening context.

string

Your user correlation identifier.

string

Related Zquence KYC record identifier.

string

Related Zquence account identifier.

string

Role of the subject in the related account.

string

Caller-defined idempotency token for this logical screening operation.

boolean

When true, creates a manual-review result without dispatching to the configured screening provider.

curl -X POST https://api.zquence.ai/v1/sanctions/screen \
  -H "content-type: application/json" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -d '{
    "entityName": "Jane Merchant",
    "entityType": "person",
    "country": "DE",
    "userId": "customer-1842",
    "requestNonce": "onboarding-customer-1842-v1"
  }'

{
  "_id": "68bbd741f4c6f683f94ca210",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "userId": "customer-1842",
  "provider": "sanctionsio",
  "status": "possible_match",
  "matchScore": 0.9425,
  "matchedLists": ["UK-SANCTIONS"],
  "entityName": "Jane Merchant",
  "entityCountry": "DE",
  "requestNonce": "manual:onboarding-customer-1842-v1",
  "billable": true,
  "caseId": "68bbd741f4c6f683f94ca211",
  "attemptId": "68bbd741f4c6f683f94ca212",
  "createdAt": "2026-08-12T10:15:32.000Z",
  "updatedAt": "2026-08-12T10:15:32.000Z"
}

The stored requestNonce includes an internal namespace prefix. Compare your original value with the requestNonce in webhook payloads, which preserves the caller-supplied value.

Status values

clear, possible_match, match, manual_review, error, or skipped.

Only clear represents a completed screen without a returned candidate. Do not convert an error, skipped screen, timeout, or missing response into a clear result.

curl -X POST https://api.zquence.ai/v1/sanctions/screen \
  -H "content-type: application/json" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -d '{
    "entityName": "Jane Merchant",
    "entityType": "person",
    "country": "DE",
    "userId": "customer-1842",
    "requestNonce": "onboarding-customer-1842-v1"
  }'

{
  "_id": "68bbd741f4c6f683f94ca210",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "userId": "customer-1842",
  "provider": "sanctionsio",
  "status": "possible_match",
  "matchScore": 0.9425,
  "matchedLists": ["UK-SANCTIONS"],
  "entityName": "Jane Merchant",
  "entityCountry": "DE",
  "requestNonce": "manual:onboarding-customer-1842-v1",
  "billable": true,
  "caseId": "68bbd741f4c6f683f94ca211",
  "attemptId": "68bbd741f4c6f683f94ca212",
  "createdAt": "2026-08-12T10:15:32.000Z",
  "updatedAt": "2026-08-12T10:15:32.000Z"
}

Introduction

Tenant

Environments

Customers

Accounts

KYC

Document reviews

Source of funds

Files

Webhooks

Sync

Sanctions

Screen a subject

Body

Status values

​Body

​Status values

Body

Status values