Retrieve a screening
Retrieves a single screening by its ozav_scr_ id, including its result and any matches. Retain the id as evidence of the check.
Request
- Base URLhttps://developers.ozav.io/v2
- Auth
- API key in header X-API-Key
- or HTTP bearer
Path parameters
The opaque screening id (ozav_scr_...).
Response
The screening.
Opaque screening identifier, prefixed ozav_scr_.
Resource type discriminator; always the literal screening.
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.
Processing state of the screening:
- pending - the screening is still running.
- completed - the screening finished; read the outcome from result.
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.
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.
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.
When the screening was created (RFC 3339 / ISO 8601, UTC).
Changes
No recorded changes to this operation across all 1 revision of this API.