Integrate sanctions screening

Use this flow when your application owns the user interface and Zquence supplies sanctions screening and case records through the API.

Before you start

Create an environment-bound API key with these scopes:

Scope	Use
`sanctions.screen`	Submit screening requests.
`sanctions.read`	Check readiness and read logs or cases.
`sanctions.review`	Record case decisions. Omit this scope if your integration only reads results.
`webhooks.write`	Create the webhook endpoint through the API.
`webhooks.read`	Read event types and delivery history.

Add sanctions.export only if the integration downloads CSV exports.

Store x-api-secret on your server. Do not send either credential from browser or mobile code.

1. Check screening readiness

Call readiness before enabling screening in your production workflow:

curl https://api.zquence.ai/v1/sanctions/readiness \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY"

Proceed only when ready is true. A false value includes tenant-safe blockers and the team responsible for resolving them.

2. Register a webhook endpoint

curl -X POST https://api.zquence.ai/v1/webhooks \
  -H "content-type: application/json" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -d '{
    "url": "https://example.com/webhooks/zquence",
    "events": ["sanctions.*"],
    "secret": "replace-with-a-long-random-secret"
  }'

The API key and endpoint belong to the same environment. Zquence sends only that environment’s events to the endpoint.

3. Screen a subject

Send a unique requestNonce for each logical screening operation. Reusing the nonce returns the existing screening record instead of calling the provider and charging twice.

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"
  }'

Store _id, caseId, attemptId, and status from the response. Keep your original requestNonce with the operation in your own system; the stored response value may include an internal namespace.

4. Apply the result

Status	Integration action
`clear`	Continue according to your compliance policy.
`possible_match`	Hold the workflow and retrieve the case for review.
`match`	Hold the workflow and retrieve the case for review.
`manual_review`	Hold the workflow until a reviewer records a decision.
`error`	Do not treat the subject as cleared. Fix the reported problem and submit a new screening operation.
`skipped`	No provider screen occurred. Do not treat the subject as cleared.

A screening result is evidence for your compliance process, not legal advice. Define your own review and escalation policy with qualified compliance counsel.

5. Process webhook results

Verify the signature against the raw request body, deduplicate on the top-level event id, enqueue the event, and return 2xx within 10 seconds. Use caseId to retrieve current state after receiving sanctions.screening.completed or an outcome-specific event. Do not depend on delivery order. Retries and endpoint recovery can change the order in which your worker sees events. See Sanctions webhook events and signature verification.

6. Review a potential match

Retrieve the authoritative case:

curl https://api.zquence.ai/v1/sanctions/cases/$CASE_ID \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY"

Use the current projection.version when you record a decision:

curl -X POST https://api.zquence.ai/v1/sanctions/cases/$CASE_ID/decisions \
  -H "content-type: application/json" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -d '{
    "disposition": "FALSE_POSITIVE",
    "expectedVersion": 1,
    "reason": "Date of birth and nationality do not match the listed subject."
  }'

If another reviewer or screening attempt changed the case, the API returns 409. Retrieve the case again and reassess it before submitting another decision.

Recovery checklist

Retry network failures with the same requestNonce.
Treat error, skipped, and HTTP 5xx responses as unresolved.
Poll GET /sanctions/cases/{caseId} when a webhook is late.
Deduplicate webhook deliveries on the event id.
Keep sandbox and live API keys, webhook secrets, and stored event data separate.

Core workflows

Webhooks

Integrate sanctions screening

Before you start

1. Check screening readiness

2. Register a webhook endpoint

3. Screen a subject

4. Apply the result

5. Process webhook results

6. Review a potential match

Recovery checklist

Reference

Screen a subject

Retrieve a case

​Before you start

​1. Check screening readiness

​2. Register a webhook endpoint

​3. Screen a subject

​4. Apply the result

​5. Process webhook results

​6. Review a potential match

​Recovery checklist

​Reference

Screen a subject

Retrieve a case

Before you start

1. Check screening readiness

2. Register a webhook endpoint

3. Screen a subject

4. Apply the result

5. Process webhook results

6. Review a potential match

Recovery checklist

Reference