Screenings

Screen a person, business, customer, or wallet address against designated lists

Point-in-time screening against OZAV's in-house designated-persons dataset (UN, OFAC, EU, UK and national sources, refreshed daily). Subjects may be inline (person/business) or reference an existing customer.

Send an Idempotency-Key to retry safely: the same key and body return the same screening, with Idempotent-Replayed: true, and on OZAV Services the retry is not charged again.

post/screenings

Request

  • Base URL
    https://developers.ozav.io/v2
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Headers

PAYMENT-SIGNATUREstring

Pay this call in USDC with x402 (v2, scheme exact) instead of prepaid credit: the base64 PaymentPayload answering the PAYMENT-REQUIRED challenge of a previous 402. OZAV checks the authorization itself, settles it on-chain itself, credits the amount to your prepaid balance and runs the call, which is then charged as usual; the settlement comes back in the PAYMENT-RESPONSE header. A call that fails after payment is refunded to your credit, not on-chain. To pay with MPP instead, send Authorization: Payment <credential> answering the WWW-Authenticate challenge, with your API key in X-API-Key; the receipt returns in Payment-Receipt, and one authorization is credited once whichever protocol carries it. With a test key, see X-Ozav-Simulate-Payment.

X-Ozav-Simulate-Payment'required'

Sandbox only. A sandbox call is never charged, so it never answers 402 by itself. Send required to rehearse the payment: the call answers the same 402 (PAYMENT-REQUIRED and details.x402, with details.simulated: true) at the real price of the call, payable to the sandbox address 0x0000000000000000000000000000000000000402. Retry with a well-formed PAYMENT-SIGNATURE (for example the one an OZAV agent signs in the sandbox with POST /agents/{agent_id}/payments): the call runs and PAYMENT-RESPONSE comes back with simulated: true. Nothing is checked on-chain and nothing moves. Ignored with a live key.

Idempotency-Keystring

Optional idempotency key (16-256 characters of [A-Za-z0-9_-]); same semantics as on money-moving operations.

Request body

listsstring[]

Which designated lists to screen against. Each item is one of:

  • sanctions - consolidated sanctions / designated-persons lists (UN, OFAC, EU, UK and national sources). Consulted for every subject.
  • pep - politically exposed persons. Consulted in-house for subjects whose country is BR (the Brazilian PEP register, refreshed monthly; list_source is national). For any other or missing country the list cannot be consulted and the result is review with an empty matches array.
  • adverse_media - negative-news screening. Not consultable yet: the result is review with an empty matches array.

Defaults to [ sanctions ] when omitted.

Response

Screening result (synchronous when possible).

idstring required

Opaque screening identifier, prefixed ozav_scr_.

object'screening' required

Resource type discriminator; always the literal screening.

listsstring[]

The designated lists that were requested / screened against. Each item is one of:

  • sanctions - consolidated sanctions / designated-persons lists.
  • pep - politically exposed persons.
  • adverse_media - negative-news screening.
status'pending' | 'completed' required

Processing state of the screening:

  • pending - the screening is still running.
  • completed - the screening finished; read the outcome from result.
result'clear' | 'match_found' | 'review' required

Conservative, fail-closed outcome:

  • clear - every requested list was fully consulted with zero matches.
  • match_found - a strong (exact/alias) designated-list match.
  • review - a weaker match, or a requested list that could not be fully consulted; never silently cleared.

Telling the two review causes apart, because they call for opposite actions and the answer is already in this response - read matches:

  • review with a non-empty matches - a weak (token-level) hit. A human decides. Retrying changes nothing; the same subject screens the same way.
  • review with an empty matches - every list you requested came back without a hit, and at least one of them could not be fully consulted. Nobody matched anything. This is transient on our side: retry later rather than queueing the subject for review. One exception, flagged in signals: pep_exact_name_only means the name is too common on the PEP register for a word-by-word comparison, so only exact name and aliases were compared. That is not transient - retrying returns the same; queue the subject for human review.

The two are exhaustive for review, by construction: a weak hit is counted from the same array that matches is serialized from, so an empty matches leaves an unconsultable source as the only remaining cause.

Which source degraded is not published. It is an operational fact about OZAV's ingestion, not about your subject, and the action it implies (retry) is the same whichever one it was.

suggested_decision'clear' | 'review' | 'decline'

OZAV's suggested decision for this subject, computed and stored when the screening ran (reading it later returns that decision, not a recomputation). It only escalates:

  • decline - a strong (exact/alias) sanctions match corroborated by a second attribute: the date_of_birth you sent matches the date on the list entry. A name-only match - no date on either side, or a different date - is review, never decline, because a homonym must not be declined automatically. Consequences: a business subject cannot reach decline (businesses carry no date of birth), and a customer_id subject is screened by name only today (the customer's stored date of birth is not used) - both stop at review.
  • review - any list signal (every sanctions or PEP signal escalates), a high contact signal, or a review result (see result).
  • clear - no list match, every requested list consulted, and any contact signals below the escalation threshold (medium/low contact signals may be present). result keeps its list-only meaning; suggested_decision also weighs contact signals.
contact_evaluatedboolean

true when the email/phone you sent were fully evaluated. false when no email or phone was sent, contact signals are disabled on the OZAV platform (a platform-wide setting, not per account), the evaluation failed, or the email domain's DNS did not answer in time (then email_domain_dns_unresolved appears in signals). With false, the absence of contact signals says nothing about the contact data.

created_atstring date-time

When the screening was created (RFC 3339 / ISO 8601, UTC).

Changes

No recorded changes to this operation across all 1 revision of this API.