Read each kind of version separately
A result saves several version IDs because different parts of a screening can change. The dataset release identifies the source versions used together. matchingEngine identifies the retrieval and scoring behavior. versions.policy identifies the matching decision rules. A package version identifies the fixed sources in a named package.
Store the returned IDs with the result. A new source file and a change to matching rules can both affect candidates, but they explain different changes. Parser versions and original file hashes can also help trace how the published source became a normalized record.
Persist version identifiers without interpreting their spelling
Every ScreeningResult includes versions.dataset, versions.matchingEngine and versions.policy. versions.package is present when applicable. Store these exact strings together with id, createdAt, coverage and any policySnapshot. Treat version values as opaque identifiers; do not derive timestamps or policy settings by splitting their strings.
coverage entries give sourceId, version, retrievedAt and fresh, plus publishedAt and source notices when supplied. publishedAt is optional and is not an alias for retrievedAt. The business-policy policySnapshot has a separate id/version; it is not the matching-engine versions.policy.
Use the retained result or evidence download when you need the versions that actually ran. GET /sources reports current source state, which can differ from historical evidence. A new dataset or matching version can change monitoring outcomes; handle policy_changed and evidence_changed events through the same review path as other meaningful changes.
curl --fail-with-body "https://www.sanctionskit.com/api/v1/results/$SCREENING_ID" \
-H "Authorization: Bearer $SANCTIONSKIT_API_KEY"Updates qualify before they become active
Imports are validated for parse completeness, stable identifiers, declared counts when supplied, and suspicious volume changes. Broken or suspicious files are quarantined. The previous qualified release remains available until it expires under the freshness policy; an unqualified file does not become live merely because it was downloaded.
Activation publishes an immutable release and switches the active pointer in a transaction. Each screening pins one release, so it does not mix old and new source versions partway through the request. Reproducing a retained result still depends on retaining its necessary inputs and source history.
Read timestamps according to their meaning
Retrieval time records when the system obtained the file. Publication time exists only when the authority supplies it. A designation’s legal effective date belongs to that designation. None of these dates should be substituted for another simply to fill an empty field.
Frequently asked questions
Which version fields should I save with a screening result?
Keep versions.dataset, versions.matchingEngine, versions.policy, and versions.package when present, along with the result ID, createdAt, coverage, and any policySnapshot. Treat version values as opaque IDs. Do not derive dates or settings by splitting their strings.
Can the latest source catalog prove what an old screening used?
No. GET /sources describes current state. Use the retained result or evidence download for the source versions that actually ran. A later dataset release can differ from the one pinned to the earlier screening.
Does a successful source download immediately become active?
No. Imports must pass validation before activation. Broken or suspicious files are quarantined. The prior qualified release can remain available until its freshness deadline. A downloaded file alone does not establish that screening used it.
Are retrieval time and a designation’s effective date interchangeable?
No. Retrieval time says when the system obtained the file. Publication time is present only when the authority supplies it. A legal effective date belongs to the designation. Keep missing dates unknown instead of substituting another timestamp.
KEEP BUILDING