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:
ScopeUse
sanctions.screenSubmit screening requests.
sanctions.readCheck readiness and read logs or cases.
sanctions.reviewRecord case decisions. Omit this scope if your integration only reads results.
webhooks.writeCreate the webhook endpoint through the API.
webhooks.readRead 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://v2.app-dev.zquence.com/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://v2.app-dev.zquence.com/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://v2.app-dev.zquence.com/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

StatusIntegration action
clearContinue according to your compliance policy.
possible_matchHold the workflow and retrieve the case for review.
matchHold the workflow and retrieve the case for review.
manual_reviewHold the workflow until a reviewer records a decision.
errorDo not treat the subject as cleared. Fix the reported problem and submit a new screening operation.
skippedNo 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://v2.app-dev.zquence.com/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://v2.app-dev.zquence.com/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.

​
Reference

Screen a subject

Request and response fields for ad-hoc screening.

Retrieve a case

Attempts, matches, decisions, and case state.