Compliance APIs for emerging-market commodity trade.

List all jurisdictions

Returns the 235 jurisdictions covered by the OilFlow regulatory matrix, each with the full per-product rule table (allowed / restricted / blocked + contextual notes).

curl -H "Authorization: Bearer <key>" \
  https://oilflow.us/api/v1/regulatory/countries

{
  "ok": true,
  "data": {
    "count": 235,
    "version": "v1-beta",
    "countries": [
      {
        "slug": "algeria",
        "country": "Algeria",
        "rules": {
          "crude":   { "status": "restricted", "notes": "Sonatrach controls upstream..." },
          "refined": { "status": "restricted", "notes": "Sonatrach controls refining..." }
        }
      }
    ]
  }
}

• ▸Cached at edge for 1 hour (ISR).

Get jurisdiction detail

Returns the full rule set for a single jurisdiction. The slug is the lowercase, hyphenated country name (e.g. 'pakistan', 'saudi-arabia').

curl -H "Authorization: Bearer <key>" \
  https://oilflow.us/api/v1/regulatory/countries/pakistan

{
  "ok": true,
  "data": {
    "slug": "pakistan",
    "country": "Pakistan",
    "rules": {
      "crude":   { "status": "restricted", "notes": "..." },
      "refined": { "status": "allowed",    "notes": "..." }
    }
  }
}

Run a tradability check

Quick tradability check for a (country, product, listing_type) tuple. Returns whether the deal would be allowed and the specific blockers if not.

curl -H "Authorization: Bearer <key>" \
  "https://oilflow.us/api/v1/regulatory/check?country=Kenya&product=crude&listing_type=demand"

{
  "ok": true,
  "data": {
    "country": "Kenya",
    "product": "crude",
    "allowed": false,
    "blockers": [{ "reason": "Private buyers in Kenya cannot independently import crude oil (OTS-only)." }]
  }
}

List product categories

Normalized product categories used by the matrix and accepted by /check.

curl -H "Authorization: Bearer <key>" \
  https://oilflow.us/api/v1/regulatory/products

{
  "ok": true,
  "data": {
    "count": 5,
    "products": [
      { "category": "crude",   "label": "Crude oil" },
      { "category": "refined", "label": "Refined products" },
      { "category": "lpg",     "label": "LPG" },
      { "category": "lng",     "label": "LNG" },
      { "category": "bitumen", "label": "Bitumen" }
    ]
  }
}

Screen a counterparty

Run the 7-step KYC pipeline on a counterparty. Synchronous v0 checks: scam-cluster blocklist + regulatory tradability. Returns a screening_run_id; subscribe via Supabase realtime to stream per-step events.

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"SSW Kafcima","country":"Singapore","directors":["Simar Chahal"]}' \
  https://oilflow.us/api/v1/kyc/screen

{
  "ok": true,
  "data": {
    "screening_run_id": "00000000-...",
    "verdict": "fail",
    "verdict_reasoning": "Confirmed cluster blocklist match: Simar Chahal.",
    "checks": { "cluster_blocklist": { "status": "fail" }, "regulatory_tradability": { "status": "pass" } }
  }
}

• ▸verdict='fail' on confirmed cluster match OR regulatory tradability fail.
• ▸Subscribe to realtime channel `pipeline:{screening_run_id}` for live step events.

Queue a re-screen for a known entity

Asynchronously re-runs the full 7-step pipeline on a previously-screened entity. Returns 202 with a new screening_run_id. Continuous re-screen fires automatically every 90 days; this endpoint is for ad-hoc re-runs.

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"00000000-0000-0000-0000-000000000001"}' \
  https://oilflow.us/api/v1/kyc/rescreen

{ "ok": true, "data": { "screening_run_id": "...", "status": "queued", "queued_at": "2026-06-02T..." } }

• ▸202 Accepted. Subscribe to webhook event `kyc.rescreen_completed` for the final verdict.

List clusters

All verified-fraudulent counterparty clusters from the OilFlow scam blocklist. Filterable by severity, country, and timestamp.

curl -H "Authorization: Bearer <key>" \
  "https://oilflow.us/api/v1/clusters?severity=confirmed"

{ "ok": true, "data": { "count": 1, "clusters": [{ "entity_name": "Simar Chahal", "severity": "confirmed", ... }] } }

Check an entity

Fast lookup: is this entity in the cluster blocklist? Integrate into intake to short-circuit obvious frauds before full KYC.

curl -H "Authorization: Bearer <key>" \
  "https://oilflow.us/api/v1/clusters/check?entity=Simar%20Chahal"

{ "ok": true, "data": { "matched": true, "matches": [{ "severity": "confirmed", ... }], "highest_severity": "confirmed" } }

List webhook subscriptions

Returns the caller's active subscriptions plus the catalog of valid event types.

curl -H "Authorization: Bearer <key>" https://oilflow.us/api/v1/webhooks

{ "ok": true, "data": { "subscriptions": [...], "valid_events": ["kyc.match_detected", "cluster.entity_added", "watchlist.match_detected", ...] } }

Create a subscription

Subscribe a URL to one or more event types. HMAC-signed delivery with exponential-backoff retry and DLQ. delivery_format='slack'|'teams' renders payloads as Block Kit / Adaptive Card; 'raw' is the default HMAC JSON.

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.slack.com/services/...","events":["kyc.match_detected","cluster.entity_added"],"delivery_format":"slack"}' \
  https://oilflow.us/api/v1/webhooks

{ "ok": true, "data": { "id": "wh_...", "secret_preview": "..." } }

• ▸HMAC secret displayed once on create. Store it in your secret manager.

Revoke a subscription

Soft-deletes the subscription. Stops future deliveries; existing DLQ entries are retained for audit.

curl -X DELETE -H "Authorization: Bearer <key>" https://oilflow.us/api/v1/webhooks/wh_...

{ "ok": true }

Recent delivery log

Returns the caller's last 50 webhook delivery attempts with status, attempt count, and HTTP response code. Used to audit a flaky endpoint.

curl -H "Authorization: Bearer <key>" https://oilflow.us/api/v1/webhooks/events

{ "ok": true, "data": { "events": [{ "id": "...", "status": "delivered", "attempt_count": 1, "response_code": 200 }] } }

Replay a failed delivery

Re-queues a specific event for delivery. Useful after fixing a receiver bug.

curl -X POST -H "Authorization: Bearer <key>" https://oilflow.us/api/v1/webhooks/events/evt_.../replay

{ "ok": true, "data": { "queued_at": "..." } }

List your generated reports

Returns paginated list of regulator-ready report packages your team has generated. Filterable by template_id and status.

{ "ok": true, "data": { "reports": [{ "id": "...", "template_id": "fatf_rec10", "status": "ready" }] } }

Generate a report

Synthesises a regulator-ready evidence package from a previous KYC run. PDF rendered server-side; webhook `report.ready` fires when complete.

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"...","template_id":"fatf_rec10"}' \
  https://oilflow.us/api/v1/reports

{ "ok": true, "data": { "id": "rpt_...", "status": "queued" } }

Fetch a report

Returns report metadata + signed-URL download link for the PDF. Append ?include_cover_letter=true for a Claude-Haiku-synthesised regulator-officer-voice cover letter, cached after first request.

{ "ok": true, "data": { "report": {...}, "download_url": "https://...", "cover_letter": { "text": "...", "cached": false } } }

Report audit trail

Returns the append-only audit trail for a report (generation events, signed-URL fetches, regenerate triggers). Bank regulators ask for this directly.

{ "ok": true, "data": { "events": [{ "kind": "generated", "at": "..." }, { "kind": "downloaded", "at": "..." }] } }

List monitored entities

Your active monitoring list. Each entity is swept across 11 languages daily; matches fire `adverse_media.match_detected` webhooks.

{ "ok": true, "data": { "entities": [{ "id": "...", "entity_name": "Acme Trading FZE", "languages": ["en","ar"] }] } }

Add an entity to monitoring

Begins daily multilingual sweeps for the named entity. Idempotent on (member_id, entity_name).

{ "ok": true, "data": { "id": "mon_..." } }

Stop monitoring an entity

Pauses daily sweeps. Soft-delete; historical findings retained.

{ "ok": true }

List findings

Returns adverse-media findings for your monitored entities. Filterable by entity, severity, language, and time window.

{ "ok": true, "data": { "findings": [{ "id": "...", "severity": "high", "language": "ar", "source_url": "..." }] } }

Screen a UBO graph

Traverses ownership N hops from a root entity, screens every node + edge against the 8 sanctions lists + cluster blocklist, and runs shell-company detection on each entity. Returns a graph_id; the full graph fetches via /ubo/graph/{id}.

{ "ok": true, "data": { "graph_id": "...", "status": "queued" } }

Fetch a UBO graph

Returns the screened ownership graph: nodes, edges, sanctions matches, shell-company verdicts, and aggregate risk score.

{ "ok": true, "data": { "nodes": [...], "edges": [...], "shell_company_verdicts": {...}, "aggregate_risk": "medium" } }

Validate an LC + invoice + B/L

Cross-document discrepancy detection: UCP 600 rule engine + amount/currency/port/expiry consistency between letter of credit, commercial invoice, and bill of lading.

{ "ok": true, "data": { "report_id": "lc_...", "discrepancies": [{ "rule": "UCP 600 Art. 14(d)", "severity": "major", "detail": "..." }] } }

Fetch an LC validation report

Returns the persisted validation report with discrepancies, UCP rule citations, and signed-URL PDF download.

{ "ok": true, "data": { "report": {...}, "download_url": "https://..." } }

Upload a counterparty watchlist (CSV)

Ingests a CSV of counterparties you want continuously screened against new sanctions deltas, cluster upgrades, and adverse-media findings. Matches fire `watchlist.match_detected` webhooks. CSV header: entity_name,aliases,jurisdictions (aliases + jurisdictions pipe-separated within the cell).

{ "ok": true, "data": { "id": "wl_...", "name": "...", "entries_count": 1247 } }

Fetch a watchlist + recent matches

Returns the watchlist + the first 25 entries + the 50 most recent match events.

{ "ok": true, "data": { "watchlist": {...}, "sample_entries": [...], "recent_matches": [{ "matched_at": "...", "source": "adverse_media" }] } }

Export your audit trail

Returns your own api_request_log rows for compliance-evidence submission. Three modes via the `format` parameter: 'json' (full rows, paginated), 'csv' (download), 'summary' (aggregate counts by SKU scope — used by the dashboard SpendForecast card).

{ "ok": true, "data": { "days": 90, "count": 9842, "rows": [...], "next_cursor": "2026-04-21T15:02:11Z" } }

• ▸Customer-scoped to your member_id (or tenant if you're on SKU #4 Workflow Suite).
• ▸Page by passing the prior response's next_cursor; null = end of stream.

Issue a sandbox API key

Unauthenticated. Issues a 7-day, 100 calls/day, read-only key scoped to /api/v1/regulatory/* + /api/v1/clusters/check. Use it to evaluate the API without signing up. Rate-limited by IP (3/h) and email (5/day).

curl -X POST -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","company":"Example Bank","use_case":"Evaluate /regulatory/check for Saudi crude"}' \
  https://oilflow.us/api/v1/keys/sandbox

{ "key": "oilflow_sk_...", "key_id": "...", "environment": "sandbox", "scopes": ["regulatory","cluster"], "expires_at": "...", "daily_call_cap": 100 }

• ▸Welcome email fires on issuance with curl gallery + dashboard link.