API Reference

Introduction

The Sigeel API is a REST API that screens individual and entity names against the US Treasury OFAC Specially Designated Nationals (SDN) list. It returns ranked matches with a 0–100 confidence score, a recommended action, and a cryptographically signed receipt — so every lookup becomes an audit artifact.

Authentication

Authenticate every request with your API key in the X-API-Key header. Keys are prefixed sk_live_ for production and sk_test_ for sandbox.

X-API-Key: sk_live_your_api_key_here

Rate limits

Limits are applied per API key. When you exceed your limit the API returns 429 Too Many Requests with a Retry-After header (seconds).

Quickstart

One request. One response. Signed and verifiable.

curl -X POST https://api.sigeel.com/screen \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Victor Bout", "min_score": 70}'

Screen a name against the OFAC SDN list. Returns ranked matches with scores, recommended actions, and a signed receipt.

Request body

Example request

curl -X POST https://api.sigeel.com/screen \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Victor Bout",
    "min_score": 70,
    "limit": 5
  }'

import requests

response = requests.post(
    "https://api.sigeel.com/screen",
    headers={"X-API-Key": "sk_live_your_key"},
    json={
        "name": "Victor Bout",
        "min_score": 70,
        "limit": 5,
    },
)

data = response.json()
for match in data["body"]["matches"]:
    print(match["score"], match["primary_name"])

const res = await fetch("https://api.sigeel.com/screen", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_live_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Victor Bout",
    min_score: 70,
    limit: 5,
  }),
});

const data = await res.json();
for (const m of data.body.matches) {
  console.log(m.score, m.primary_name);
}

body := strings.NewReader(`{
  "name": "Victor Bout",
  "min_score": 70,
  "limit": 5
}`)

req, _ := http.NewRequest("POST", "https://api.sigeel.com/screen", body)
req.Header.Set("X-API-Key", "sk_live_your_key")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Example response 200 OK

{
  "body": {
    "query": "Victor Bout",
    "normalized_query": "victor bout",
    "match_count": 1,
    "matches": [{
      "score": 93.1,
      "primary_name": "BOUT, Viktor Anatoljevitch",
      "matched_name": "viktor anatoljevitch bout",
      "matched_on": "primary",
      "entity_type": "individual",
      "sdn_id": "12345",
      "programs": ["SDGT", "UKRAINE-EO13662"],
      "recommended_action": "manual_review",
      "aliases": [
        "BOUT, Victor",
        "BUTT, Viktor",
        "BOUT, Viktor Anatolyevich"
      ]
    }],
    "list": {
      "source": "OFAC SDN",
      "entity_count": 19457,
      "variant_count": 44074,
      "built_at": "2026-10-01T00:00:00Z"
    },
    "usage": {
      "month_to_date": 142,
      "quota": 10000,
      "overage": 0
    }
  },
  "signature": {
    "alg": "Ed25519",
    "key_id": "pk_2026_10",
    "public_key_b64": "MCowBQYDK2VwAyEA…",
    "signature_b64": "9f2a…",
    "signed_at": "2026-10-19T14:32:01Z"
  }
}

Response fields

Returns the current Ed25519 public key used to sign responses. Use this to verify any receipt offline. Public — no auth required.

{
  "alg": "Ed25519",
  "key_id": "pk_2026_10",
  "public_key_b64": "MCowBQYDK2VwAyEA3x8Z...",
  "valid_from": "2026-10-01T00:00:00Z",
  "rotates_at": "2027-01-01T00:00:00Z"
}

Key rotation happens quarterly. Old keys remain valid for verification of previously-signed receipts. Match key_id from a receipt to select the right key.

Liveness and readiness check. Public — no auth required.

{
  "status": "ok",
  "list_loaded": true,
  "entity_count": 19457,
  "list_built_at": "2026-10-01T00:00:00Z",
  "uptime_s": 1843221
}

Match object

Each item in body.matches is a Match object.

Score interpretation

Scores are calibrated so you can act on them consistently. The recommended_action field encodes the same thresholds so you don't have to hard-code them.

A "clear" result does not confirm someone is unsanctioned — it means no candidate exceeded the score threshold against the current list.

Receipt verification

Every response is signed with Ed25519 over a canonical JSON representation of the body. This means you can prove months later that a specific screening happened, with exactly these results, against a specific SDN build — without trusting our servers.

Canonical form

• JSON keys sorted lexicographically (byte order).
• No whitespace between tokens: {"a":1,"b":2}.
• UTF-8 encoded, no BOM.
• Numbers serialized per ECMAScript Number.prototype.toString (no trailing zeros, no + sign).

Verify in code

import json, base64
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

def verify_receipt(receipt, public_key_b64):
    body = receipt["body"]
    sig  = base64.b64decode(receipt["signature"]["signature_b64"])
    pub  = base64.b64decode(public_key_b64)

    canonical = json.dumps(
        body, sort_keys=True, separators=(",", ":"),
    ).encode("utf-8")

    Ed25519PublicKey.from_public_bytes(pub).verify(sig, canonical)
    return True

import { verify, createPublicKey } from "crypto";

function canonicalize(v) {
  if (v === null || typeof v !== "object") return JSON.stringify(v);
  if (Array.isArray(v)) return "[" + v.map(canonicalize).join(",") + "]";
  return "{" + Object.keys(v).sort().map(k =>
    JSON.stringify(k) + ":" + canonicalize(v[k])
  ).join(",") + "}";
}

export function verifyReceipt(receipt, publicKeyB64) {
  const sig = Buffer.from(receipt.signature.signature_b64, "base64");
  const key = createPublicKey({
    key: Buffer.from(publicKeyB64, "base64"),
    format: "der", type: "spki",
  });
  const msg = Buffer.from(canonicalize(receipt.body), "utf-8");
  return verify(null, msg, key, sig);
}

import (
    "crypto/ed25519"
    "encoding/base64"
    "encoding/json"
    "sort"
)

func canonicalize(v any) string {
    switch x := v.(type) {
    case map[string]any:
        keys := make([]string, 0, len(x))
        for k := range x { keys = append(keys, k) }
        sort.Strings(keys)
        out := "{"
        for i, k := range keys {
            if i > 0 { out += "," }
            kb, _ := json.Marshal(k)
            out += string(kb) + ":" + canonicalize(x[k])
        }
        return out + "}"
    default:
        b, _ := json.Marshal(v)
        return string(b)
    }
}

func VerifyReceipt(body any, sigB64, pubB64 string) bool {
    sig, _ := base64.StdEncoding.DecodeString(sigB64)
    pub, _ := base64.StdEncoding.DecodeString(pubB64)
    return ed25519.Verify(pub, []byte(canonicalize(body)), sig)
}

Error codes

All errors return JSON: { "error": { "code": "...", "message": "..." } }

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is missing or invalid."
  }
}

Best practices

• →
  Set min_score to 70 or higher in production. Lower thresholds surface weak matches that waste reviewer time.
• →
  Screen on the exact name given to you, unmodified. Sigeel does all normalization. Pre-normalizing loses signal.
• →
  Store the full receipt envelope, not just the matches. The signature + list.built_at is your audit artifact.
• →
  Verify signatures on ingest if you're building an audit pipeline. It costs microseconds and closes the loop.
• →
  Retry 5xx with exponential backoff. Do not retry 4xx. Do respect Retry-After on 429.
• →
  Cache the pubkey for 24 hours. It rotates quarterly. Match key_id on receipts to select the right one.
• →
  Treat results as input to a human decision, not a final determination. See the compliance disclaimer on the home page.

Changelog