Retrieve sanctions screening results and evidence

GET /api/v1/results/{id} returns a retained result under data. GET /api/v1/results lists permitted results with items and nextCursor. Result IDs do not grant access on their own: the key or session must belong to the correct organization and environment.

GET /api/v1/results/{id}/evidence returns a downloadable JSON evidence document. Unlike the ordinary API data envelope, that document is the evidence object itself. Its format field identifies sanctionskit-evidence@1. Preserve the original result separately from later analyst decisions.

curl --fail-with-body \
  "https://www.sanctionskit.com/api/v1/results/$SCREENING_ID/evidence" \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY" \
  --output screening-evidence.json

Use results:read. GET /results?limit=100 returns {data:{items:[ScreeningResult],nextCursor}}. Follow the returned nextCursor until null; default limit is 25, maximum 100. The server can return fewer complete items to respect its response byte limit even when another page exists. A short page is not proof that the list is finished.

This iterator uses the helper from authentication and checks for a repeated cursor. Plain result-list items contain the stored result, not the subject/reference augmentation from GET /results/{id}. The summary=true variant is a different summary schema for history displays; do not parse it as full ScreeningResult objects.

// Save alongside sk-api.mjs; pass each item to your authorized storage.
export async function* resultPages(api) {
  let cursor = null;
  const seen = new Set();
  do {
    const query = new URLSearchParams({ limit: '100' });
    if (cursor) query.set('cursor', cursor);
    const page = await api('/results?' + query);
    if (!Array.isArray(page.items) ||
        (page.nextCursor !== null && typeof page.nextCursor !== 'string')) {
      throw new Error('Invalid result page.');
    }
    yield page.items;
    cursor = page.nextCursor;
    if (cursor != null) {
      if (typeof cursor !== 'string' || seen.has(cursor)) {
        throw new Error('Invalid or repeated continuation cursor.');
      }
      seen.add(cursor);
    }
  } while (cursor != null);
}

// import { api } from './sk-api.mjs';
// for await (const items of resultPages(api)) {
//   await saveResults(items); // Your application's authorized storage.
// }

The result evidence download is application/json with an attachment disposition and has no data wrapper. Its top-level required fields are format, result, retention, expires_at, subject, reference, request, retainedInputs and replayLimit. format is sanctionskit-evidence@1. result is the screening outcome; request and subject describe retained inputs, or null when they were omitted.

For minimal retention, subject, reference and request are null, retainedInputs is false, and replayLimit explains why full historical replay is unavailable. expires_at can be null when retention protection applies. Check format before parsing an archived file, and keep the exact bytes in authorized storage if you need the downloaded snapshot. The document is not a signed attestation.

Error responses for a download still use the JSON error envelope. Check HTTP status before writing the response as a successful evidence file. curl --fail-with-body returns a nonzero exit status for an HTTP failure; remove a partial output file and surface the error instead of accepting it as evidence.

The dashboard’s deterministic evidence summaries require a signed-in human session; they are not a public API-key operation. Machine clients read the complete retained ScreeningResult and its evidence document. A summary cannot replace source facts or regenerate missing inputs.

Use /cases?screeningId=ID to locate a linked case, then GET /investigations/{caseId} for its current decisions, checks and history. Case IDs and screening IDs are separate identifiers. See review for how reopened and superseded cases affect business status.

curl --fail-with-body "https://www.sanctionskit.com/api/v1/investigations/$CASE_ID" \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY"

GET /reports accepts from and to in YYYY-MM-DD and optional timeZone as a location-based IANA name. It returns a data envelope containing operational report fields. Omitting timeZone preserves UTC date boundaries. Use the response’s actual range and timezone when labeling your own report.

GET /reports/screenings accepts the same range and format=csv; it returns downloadable CSV text, not a JSON envelope. GET /reports/cases/{caseId}?format=json returns the raw audit packet without a data wrapper; format=pdf returns PDF bytes. Both require results:read and applicable export permissions for human sessions. Do not send these bodies through a generic data-envelope helper.

For large cases, /reports/cases/{caseId}/archive paginates the retained archive under data. Begin without cursor, then send each returned nextCursor until complete=true. Preserve caseId, revision, asOf and ordered segment numbers. If a case changes and export returns 409, discard the incomplete local export and restart; combining segments from different revisions is not a complete record.

GET /api/v1/reports/cases/{id}?format=json or format=pdf produces a bounded audit packet with retained screening evidence, decisions, attributed findings, external-check history, text attachments and document references. A large case may exceed the packet limit and must use the segmented archive.

GET /api/v1/reports/cases/{id}/archive returns a data envelope with format sanctionskit-case-archive@1, caseId, revision, asOf, segment, category, records, nextCursor, complete and limitations. Save each numbered segment and send its nextCursor to retrieve the next. Keep all segments through complete=true; one response is not the complete archive. A changed case returns 409 and requires restarting the export.

Archive categories include the case, screenings, decisions, match reviews and history, comments, attachments, findings, corrections, checks, documents, holds, reuse rules and audit events. Expiry still applies. External repository document bytes are not included. These exports are not signed, immutable, tamper-proof archives or compliance certifications.

Upload original PDFs, images, and passport scans directly to your organization’s document service, then add the existing HTTPS link under Original document references in the case. Owners and administrators configure the service name and approved HTTPS repository URL in Settings → Organization documents. SanctionsKit stores the reference and reviewer assertions, not the original file; it does not fetch or independently verify the document.

Opening a document link takes the reviewer to that service, where its permissions, security, and retention controls apply. Approving a repository does not connect accounts or grant access. Preserve the original there even if you place a hold on the SanctionsKit case.

Supporting text attachments accept UTF-8 .txt or .md files up to 200,000 bytes and follow the case’s evidence retention. They count toward file storage alongside private bulk screening uploads and in-progress upload reservations. Database screening evidence and external document links do not count toward that allowance; see usage and limits.

The result includes the selected source versions, dataset, matching-engine version, policy version, and package version when used. Original source records and authority references help reviewers understand the finding. Retention must preserve the necessary inputs and source history to support later reproduction.

An expired result returns 410 rather than a fabricated historical response. Minimal retention omits the retained subject, redacts submitted values from persisted match evidence, and limits the reduced result to 24 hours. The immediate response and any copy your application stores remain your responsibility. A request digest cannot reconstruct a deleted subject.

Request and response reference

Frequently asked questions