Batch Sanctions Screening API for CSV and XLSX Uploads

name,country,search_type
Test Person,PL,sanctions_check
Example Trading Company,DE,sanctions_check
Second Test Person,,sanctions_check

# name         required. Blank names are skipped, not rejected.
# country      optional. Used as a jurisdiction hint.
# search_type  optional, defaults to sanctions_check.
#              Accepted: sanctions_check | adverse_media | full_search
#              Aliases:  aml_check -> sanctions_check
#                        deep_research -> full_search (deprecated)
#              All rows in one file must resolve to the SAME type.
# Duplicate (name, country) pairs are removed before queueing.

# 1. Create the job (multipart upload)
curl -X POST https://screenveritai.com/api/v1/batch \
  -H "X-API-Key: svai_your_key_here" \
  -F "file=@entities.csv"

# HTTP/1.1 202 Accepted
# {
#   "job_id": "c41f7b90-2ad8-4e35-9f61-77b0c9d2e401",
#   "total_rows": 3,
#   "credits_charged": 3,
#   "search_type": "sanctions_check",
#   "status": "pending",
#   "message": "Batch job created successfully. Poll the GET endpoint for status."
# }

# 2. Poll the job
curl https://screenveritai.com/api/v1/batch/c41f7b90-2ad8-4e35-9f61-77b0c9d2e401 \
  -H "X-API-Key: svai_your_key_here"

# 3. Inspect individual rows while it runs
curl "https://screenveritai.com/api/v1/batch/c41f7b90-2ad8-4e35-9f61-77b0c9d2e401/rows?status=error&page=1&page_size=20" \
  -H "X-API-Key: svai_your_key_here"

# 4. Export once status is "completed" (400 before that)
curl -o results.csv \
  "https://screenveritai.com/api/v1/batch/c41f7b90-2ad8-4e35-9f61-77b0c9d2e401/export" \
  -H "X-API-Key: svai_your_key_here"

{
  "id": "c41f7b90-2ad8-4e35-9f61-77b0c9d2e401",
  "status": "running",
  "total_rows": 3,
  "processed_rows": 2,
  "success_rows": 2,
  "error_rows": 0,
  "credits_charged": 3,
  "source_filename": "entities.csv",
  "search_type": "sanctions_check",
  "created_at": "2026-09-04T09:31:12.004000+00:00",
  "completed_at": null
}

// GET /api/v1/batch/{job_id}/rows
{
  "rows": [
    {
      "ordinal": 1,
      "name": "Test Person",
      "country": "PL",
      "status": "done",
      "result_json": {
        "entity_processed": "Test Person",
        "ofac_sanctions_details": "## OFAC Sanctions Findings\n\n**Status:** *No relevant listing found* ...",
        "criminal_watchlists_details": "",
        "pep_details": "",
        "final_report_content": ""
      },
      "error_message": null
    },
    {
      "ordinal": 3,
      "name": "Second Test Person",
      "country": null,
      "status": "queued",
      "result_json": null,
      "error_message": null
    }
  ],
  "page": 1,
  "page_size": 20
}

import os
import time
import requests

BASE = "https://screenveritai.com/api/v1"
HEADERS = {"X-API-Key": os.environ["SCREENVERITAI_API_KEY"]}

# 1. Upload. Keep the local file: nothing on the server maps back to your
#    own row references, and there is no idempotency key on re-upload.
with open("entities.csv", "rb") as handle:
    created = requests.post(
        f"{BASE}/batch",
        headers=HEADERS,
        files={"file": ("entities.csv", handle, "text/csv")},
        timeout=60,
    )
created.raise_for_status()     # 400 rows/type, 413 size, 415 file type
job = created.json()
job_id = job["job_id"]
print(job["total_rows"], "rows queued,", job["credits_charged"], "credits reserved")

# 2. Poll. Terminal statuses: completed, failed, canceled.
while True:
    status_response = requests.get(f"{BASE}/batch/{job_id}", headers=HEADERS, timeout=30)
    status_response.raise_for_status()
    state = status_response.json()
    print(state["status"], state["processed_rows"], "/", state["total_rows"])
    if state["status"] in {"completed", "failed", "canceled"}:
        break
    time.sleep(10)

if state["status"] != "completed":
    raise RuntimeError(f"batch {job_id} ended as {state['status']}")

# 3. Export. errors_only=true returns just the rows with status "error".
export = requests.get(f"{BASE}/batch/{job_id}/export", headers=HEADERS, timeout=120)
export.raise_for_status()
with open(f"batch-{job_id}.csv", "wb") as out:
    out.write(export.content)

if state["error_rows"]:
    errors = requests.get(
        f"{BASE}/batch/{job_id}/export",
        headers=HEADERS,
        params={"errors_only": "true"},
        timeout=60,
    )
    errors.raise_for_status()
    print("re-screen these rows:", errors.text.splitlines()[1:])