Urim — API Documentation

Authentication

All API requests require your API key sent in the X-API-Key header. You can find your API key in the Admin page of your Urim dashboard, or generate a new one via the API.

Header
X-API-Key: your_api_key_here

⚠ Keep your key safe

Your API key has full access to your account. Don't commit it to source control or share it in client-side code. If compromised, rotate it immediately from the Admin page or via POST /me/rotate-key.

Base URL

All API endpoints are available at:

Base URL
https://urimkyc.com/api

For example, to screen an individual: POST https://urimkyc.com/api/screen

Quick Start with Postman

The fastest way to explore the API. Import our pre-built collection and start screening in under 2 minutes.

Download Postman Collection

Import the collection Open Postman → click Import (top left) → drag in the JSON file → click Import.

Set your API key Click on Urim KYC API in the sidebar → Variables tab → paste your API key in the api_key value field → Save (Ctrl+S).

Set the base URL In the same Variables tab, set base_url to https://urimkyc.com/api → Save.

Send your first request Expand System → click Health Check → click Send. You should get back the API version and status.

Screen someone Expand Screening → click Screen Individual → click Send. The test subject (Vladimir Putin) is pre-loaded. The screen_id auto-saves so you can immediately test Dispose, Get Screen, and Delete.

ℹ Environment override

If requests fail with a connection error, check the environment dropdown (top-right of Postman). Set it to No environment so the collection variables are used.

Endpoints

Health Check

GET /health

Returns API version and status. No authentication required.

curl

curl https://urimkyc.com/api/health

Response 200
{
  "status": "ok",
  "version": "1.5.0",
  "timestamp": "2026-04-04T01:19:43.768129+00:00"
}

Screen Individual

POST /screen 🔑 API Key Required

Run a full screening (sanctions, PEP, criminal) on an individual. Returns a complete JSON result with risk level, matches, and AI-generated compliance narratives.

Field	Type	Required	Description
name	`string`	Yes	Full name to screen (min 2 characters)
dob	`string`	No	Date of birth in YYYY-MM-DD format
nationality	`string`	No	e.g. "American", "British", "Russian"
location	`string`	No	City or country
alias	`string`	No	Known alias or alternative name
types	`string`	No	Comma-separated: sanctions,pep,criminal (default: all three)
force	`boolean`	No	Bypass duplicate check and cache (default: false)

curl

curl -X POST https://urimkyc.com/api/screen \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vladimir Putin",
    "dob": "1952-10-07",
    "nationality": "Russian",
    "location": "Moscow",
    "types": "sanctions,pep,criminal"
  }'

Response 200
{
  "screen_id": "SCR-20260404-0001",
  "risk_level": "CRITICAL",
  "subject": {
    "name": "Vladimir Putin",
    "dob": "1952-10-07",
    "nationality": "Russian",
    "location": "Moscow"
  },
  "sanctions_result": {
    "risk_level": "CRITICAL",
    "is_sanctioned": true,
    "matches": [ ... ],
    "narrative": "The screening returned a hit against..."
  },
  "pep_result": {
    "risk_level": "HIGH",
    "is_pep": true,
    "tier": 1,
    "tier_label": "Tier 1 — Current",
    "category": "head_of_state",
    "narrative": "Vladimir Putin is identified as a Tier 1..."
  },
  "criminal_result": {
    "risk_level": "CLEAR",
    "interpol_hits": [],
    "fbi_hits": [],
    "narrative": "No matches were found..."
  },
  "screened_at": "2026-04-04T01:40:46Z",
  "skipped": false
}

ℹ Duplicate detection

By default, if you screen the same person twice within the rescreen window, the API returns the cached result. Set "force": true to bypass this and run a fresh screen.

List All Screens

GET /screens?limit=50 🔑 API Key Required

Returns all screening results for your tenant, most recent first.

List Pending Screens

GET /screens/pending 🔑 API Key Required

Returns screens awaiting analyst review (no disposition recorded yet).

Get Screen by ID

GET /screens/{screen_id} 🔑 API Key Required

Returns full details for a specific screen including all match data and narratives.

Get Screen History

GET /screens/{screen_id}/history 🔑 API Key Required

Returns the full disposition history and analyst notes for a screen.

Dispose Screen

POST /screens/{screen_id}/dispose 🔑 API Key Required

Record an analyst disposition on a screen — confirm a hit, clear a false positive, or flag for further review.

Field	Type	Required	Description
disposition	`string`	Yes	One of: confirmed_hit, false_positive, needs_review, cleared, approved
note	`string`	No	Analyst notes explaining the decision
override	`boolean`	No	Override an existing disposition from another analyst
approval_requested	`boolean`	No	Flag this decision for admin approval

curl

curl -X POST https://urimkyc.com/api/screens/SCR-20260404-0001/dispose \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "disposition": "confirmed_hit",
    "note": "Verified match — OFAC SDN list"
  }'

Delete Screen

DELETE /screens/{screen_id} 🔑 API Key Required

Permanently delete a screen and all associated analyst notes. Admins can delete any screen; analysts can only delete their own.

Batch Screen

POST /batch/stream 🔑 Growth Plan+

Screen up to 500 subjects in a single request. Returns a Server-Sent Events stream with progress updates as each subject completes.

curl

curl -X POST https://urimkyc.com/api/batch/stream \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subjects": [
      {"name": "Vladimir Putin", "nationality": "Russian"},
      {"name": "Ali Khamenei", "nationality": "Iranian"},
      {"name": "John Smith", "location": "London"}
    ],
    "types": "sanctions,pep,criminal"
  }'

Batch Screen + Add to Clients

POST /batch/clients/stream 🔑 Growth Plan+

Same as batch screen, but also registers each subject as an ongoing client for continuous monitoring and scheduled re-screens.

Clients

POST /clients 🔑 API Key Required

Register a client for ongoing monitoring with scheduled re-screens.

GET /clients 🔑 API Key Required

List all registered client profiles for your tenant.

GET /clients/screened 🔑 API Key Required

All unique subjects ever screened — one row per person, showing their most recent screen and latest disposition.

GET /clients/reviewed 🔑 API Key Required

Subjects that have been reviewed (have a disposition).

POST /clients/rescreen/auto/trigger 🔑 API Key Required

Manually trigger the auto-rescreen scheduler for all clients past their rescreen due date.

Account

GET /me 🔑 API Key Required

Returns your user info, role, tenant name, and current plan.

POST /me/rotate-key 🔑 API Key Required

Generate a new API key. Your old key is immediately invalidated — update your integration right away.

GET /dbstatus 🔑 API Key Required

Returns sanctions database stats — entity counts per list, last sync time, and staleness indicators.

Reference

Risk Levels

Every screen returns an overall risk level based on the highest-risk result across all check types.

Level	Meaning
CRITICAL	Confirmed sanctions match — all dealings prohibited
HIGH	Strong match requiring immediate review (PEP Tier 1, high-confidence sanctions match)
MEDIUM	Partial match or lower-confidence result requiring investigation
LOW	Weak match — likely a different person but worth noting
CLEAR	No matches found across all checked databases

Dispositions

After screening, analysts record a disposition to document their review decision.

Disposition	When to use
confirmed_hit	Verified match — the subject is the person on the list
false_positive	Different person — name similarity but not a match
needs_review	Unclear — requires further investigation or additional information
cleared	Reviewed and no compliance concern identified
approved	Admin sign-off on a disposition (admin role only)

Error Responses

The API uses standard HTTP status codes. Errors return a JSON body with a detail field.

Status	Meaning
400	Bad request — check your request body
401	Unauthorized — missing or invalid API key
403	Forbidden — your role doesn't have permission for this action
404	Not found — screen or resource doesn't exist
409	Conflict — screen already has a disposition (use override: true)
429	Rate limited — you've exceeded your plan's monthly screen limit

Error Response
{
  "detail": "Monthly screen limit reached (1000/1000). Upgrade your plan."
}

Rate Limits

Your monthly screen quota depends on your plan. Each individual screen and each subject in a batch counts as one screen.

Plan	Screens / Month	Analysts	Batch
Starter	1,000	1	No
Growth	5,000	5	Yes
Professional	20,000	20	Yes
Enterprise	Unlimited	Unlimited	Yes

Using Other Languages

The API is a standard REST API — you can use any language or tool that makes HTTP requests.

Python

python

import requests

API_KEY = "your_api_key_here"
BASE    = "https://urimkyc.com/api"

# Screen an individual
resp = requests.post(f"{BASE}/screen",
    headers={"X-API-Key": API_KEY},
    json={
        "name": "Vladimir Putin",
        "nationality": "Russian",
        "types": "sanctions,pep,criminal"
    }
)
result = resp.json()
print(f"Risk: {result['risk_level']} | ID: {result['screen_id']}")

# Get pending screens
pending = requests.get(f"{BASE}/screens/pending",
    headers={"X-API-Key": API_KEY}
).json()

# Auto-dispose all CLEAR screens
for screen in pending.get("screens", []):
    if screen["risk_level"] == "CLEAR":
        requests.post(f"{BASE}/screens/{screen['screen_id']}/dispose",
            headers={"X-API-Key": API_KEY},
            json={"disposition": "cleared", "note": "Auto-cleared"}
        )

JavaScript / Node.js

javascript

const API_KEY = "your_api_key_here";
const BASE    = "https://urimkyc.com/api";

// Screen an individual
const resp = await fetch(`${BASE}/screen`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Vladimir Putin",
    nationality: "Russian",
    types: "sanctions,pep,criminal"
  })
});
const result = await resp.json();
console.log(`Risk: ${result.risk_level} | ID: ${result.screen_id}`);

curl

bash

# Screen an individual
curl -X POST https://urimkyc.com/api/screen \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vladimir Putin", "types": "sanctions,pep,criminal"}'

# List pending screens
curl https://urimkyc.com/api/screens/pending \
  -H "X-API-Key: your_api_key_here"

# Dispose a screen
curl -X POST https://urimkyc.com/api/screens/SCR-20260404-0001/dispose \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"disposition": "confirmed_hit", "note": "Verified OFAC match"}'