Public REST API

The Omnified API is a small set of JSON-over-HTTPS endpoints. Every request is authenticated with a Bearer key, every write is idempotent, every response is either the resource or an RFC 7807 application/problem+json error. CORS is intentionally disabled — the API is server-to-server; browser clients cannot read responses directly.

• PII fields (name, DOB, ID number, address) are encrypted at rest with AES-256-GCM before insert.
• Sandbox and live use separate keys and separate data — sandbox data never mixes with live.
• All timestamps are ISO 8601 UTC. All IDs are opaque strings; do not parse them.

Create a sandbox key from Settings → API, then run:

curl -X POST https://getomnified.com/api/public/v1/verifications \
  -H "Authorization: Bearer omn_sk_test_sg_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "subject": {
      "customer_type": "individual",
      "full_name": "Wei Ling Tan",
      "nationality": "SG",
      "id_type": "nric",
      "id_number": "S9412345A"
    },
    "jurisdiction": "SG",
    "checks": "auto",
    "client_reference": "cust_123"
  }'

import { randomUUID } from "node:crypto";

const res = await fetch("https://getomnified.com/api/public/v1/verifications", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OMNI_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    subject: { customer_type: "individual", full_name: "Wei Ling Tan", nationality: "SG" },
    jurisdiction: "SG",
    checks: "auto",
  }),
});

if (!res.ok) throw new Error(await res.text());
const verification = await res.json();

import os, uuid, requests

r = requests.post(
    "https://getomnified.com/api/public/v1/verifications",
    headers={
        "Authorization": f"Bearer {os.environ['OMNI_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "subject": {"customer_type": "individual", "full_name": "Wei Ling Tan", "nationality": "SG"},
        "jurisdiction": "SG",
        "checks": "auto",
    },
    timeout=30,
)
r.raise_for_status()
verification = r.json()

Send an Authorization: Bearer <key> header on every request. Keys are prefixed omn_sk_live_sg_… (production) or omn_sk_test_sg_… (sandbox); the segment after the environment is the issuing region. Keys are shown once at creation — we store only the SHA-256 hash plus a 16-character display prefix, and verify with a constant-time comparison. To rotate a key, create a new one in Settings → API, move your systems to it, then revoke the old one. Revocation is immediate: the revoked key is refused with 401 key_revoked from then on.

Authorization: Bearer omn_sk_live_sg_9c81b12e...

Each key has one or more scopes. Requests without the required scope return 403 forbidden_scope.

Sandbox is fully isolated: sandbox keys can only create sandbox verifications, vendor calls are mocked, and no live data is ever touched. Live keys require the org to have live mode activated (see the in-app activation checklist).

• Sandbox — omn_sk_test_sg_…
• Live — omn_sk_live_sg_…

Both use the same base URL. The key prefix selects the environment; a key used against the wrong environment returns 401.

Metered products (Rulebook, Pilcrow) behave differently per environment: sandbox keys read only the curated demo corpus slice for each jurisdiction. When that slice is empty the call abstains and returns no results — it never widens to the full corpus. Production keys read the full ingested corpus for the jurisdictions the org is entitled to.

All POST endpoints accept an Idempotency-Key header (8–200 characters, UUIDv4 recommended). We store the request hash plus response for 24 hours. A retry with the same key returns the original response with Idempotent-Replay: true. Reusing the same key with a different body returns 409 idempotency_key_mismatch.

POST /api/public/v1/verifications
Idempotency-Key: 4c5b1e6a-9f2a-4e1e-8fbb-1b3f0f2c9d10
Content-Type: application/json

Sliding-window per key, per minute. Defaults: sandbox 300 req/min, live 1200 req/min. Every response includes the current limit state; when exceeded we return 429 rate_limited with a Retry-After value in seconds.

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1187
X-RateLimit-Reset: 1751780400
Retry-After: 12

Metered endpoints (Rulebook search, Pilcrow) additionally report the remaining credit balance for that product after the call, so you can watch exhaustion approach rather than discovering it as a 402 insufficient_credits.

X-Credits-Product: rulebook
X-Credits-Remaining: 87

Every error is application/problem+json (RFC 7807). We never return stack traces, framework names, or version strings.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://docs.getomnified.com/api/errors#validation_failed",
  "title": "Request validation failed",
  "status": 400,
  "code": "validation_failed",
  "errors": [{ "path": "subject.full_name", "message": "Required" }]
}

List endpoints are cursor-paginated. Pass limit (max 100) and, for subsequent pages, the next_cursor from the previous response.

{
  "data": [ /* … */ ],
  "next_cursor": "eyJvIjoiY3JlYXRlZF9hdCJ9",
  "has_more": true
}

Machine-readable compliance reporting for external BI, GRC and audit tooling. Rows carry no PII — no name, DOB, ID number or address — only IDs, verdicts, risk, jurisdiction, vendor, timestamps and your client_reference. Results are scoped to the environment of the key used.

GET /api/public/v1/reports/summary?from=2026-07-01&to=2026-07-31&jurisdiction=SG

{
  "data": [
    {
      "id": "ver_01HZ…",
      "created_at": "2026-07-14T09:12:44Z",
      "jurisdiction": "SG",
      "verdict": "approved",
      "risk_score": 12,
      "reason_codes": [],
      "vendor_used": "singpass_myinfo",
      "status": "completed",
      "case_id": null,
      "client_reference": "cust_123",
      "sandbox": false
    }
  ],
  "next_cursor": "MjAyNi0wNy0xNC…",
  "has_more": true
}

Hybrid retrieval and reranking over ingested regulator documents (MAS, IFSCA/GIFT City, Indian PMLA and more), returning verbatim provisions with document, clause and page provenance. Every call is recorded as a sealed agent run and consumes product credits. Requires the rulebook product entitlement.

{
  "question": "What EDD is required for a non-face-to-face onboarding?",
  "jurisdictions": ["SG", "GIFT_IFSC"],
  "top_k": 6
}

{
  "run_id": "run_01HZ…",
  "question": "…",
  "jurisdictions": ["SG", "GIFT_IFSC"],
  "sandbox": true,
  "result_count": 4,
  "results": [
    {
      "chunk_id": "…",
      "document_id": "…",
      "document": "MAS Notice 626",
      "jurisdiction": "SG",
      "clause_ref": "6.14",
      "section_path": "6 · Customer Due Diligence",
      "version_label": "2024-07",
      "instrument_type": "notice",
      "is_binding": true,
      "issuing_authority": "MAS",
      "page_from": 12,
      "page_to": 12,
      "source_url": "https://…",
      "content": "…",
      "score": 0.71
    }
  ]
}

Pilcrow is the conversational compliance agent layered over the rulebook engine: it plans retrieval, quotes only verbatim provisions it can cite, and abstains structurally when the corpus does not support an answer. API turns are stateless — pass a thread_id belonging to your org to carry prior context read-only; nothing is written to it. Requires the pilcrow entitlement and available credits.

{
  "message": "Does a GIFT IFSC entity need to re-KYC an existing client?",
  "jurisdictions": ["GIFT_IFSC"],
  "thread_id": "6f1c…"
}

{
  "run_id": "run_01HZ…",
  "thread_id": null,
  "sandbox": true,
  "answer": "…",
  "citations": [
    { "document": "IFSCA AML Guidelines", "clause_ref": "9.1", "quote": "…" }
  ],
  "confidence": "high",
  "determination": "answered",
  "abstained": false,
  "billable_units": 1
}

Run a published Journey Builder journey for an applicant. Every run pins the journey’s live release in the key’s environment (sandbox keys: Test). Production opens when Journey Builder is available in Production. Personal data in applicant and inputs is sealed in the run’s log; responses and webhooks carry ids, statuses and verdicts. Requires a Journey Builder install.

New to Journey Builder? The Journey Builder guide covers journeys, versions, review, evidence and delivery options.

{
  "journey_id": "6f1c…",
  "subject_ref": "cust-0001",
  "applicant": { "type": "individual", "residency": "SG" },
  "inputs": { "full_name": "…" },
  "jurisdiction": "SG",
  "hosted_link": { "ttl_seconds": 86400 }
}

{
  "id": "0a3e…",
  "object": "journey_run",
  "status": "waiting",
  "sandbox": true,
  "next_step": {
    "kind": "form",
    "node_id": "profile",
    "entry": 1,
    "form": { "id": "f_profile", "title": "About you", "fields": [
      { "id": "full_name", "type": "text", "label": "Full name", "required": true,
        "value": "…", "locked": true, "show_if": null }
    ] }
  },
  "outcome": null,
  "hosted_link": { "url": "https://…/j/s/jh_…", "expires_at": "…", "single_use": true }
}

{ "node_id": "profile", "entry": 1, "answers": { "date_of_birth": "1980-01-01" } }

Hosted link and Web SDK. A hosted link (/j/jl_…) is created in Journey Builder → Settings and opens the journey for anyone who has it. Embed it with the dependency-free Web SDK (/sdk/journeys-v1.js, or the ES module /sdk/journeys-v1.mjs; types at /sdk/journeys-v1.d.ts) after adding your site to the allowed origins: the page is framed only by those origins and posts its events (ready, started, step, completed, failed, expired, error, resize, close) only to them. Confirm an outcome server-side before acting on it.

<script src="https://getomnified.com/sdk/journeys-v1.js"></script>
<script>
  OmnifiedJourneys.open({ link: "jl_…", mode: "modal" })
    .on("completed", (e) => fetch("/my-backend/check-run/" + e.runId));
</script>

A Model Context Protocol endpoint exposes the same capabilities to AI agents as first-class tools, over JSON-RPC 2.0 at POST /api/public/v1/mcp, authenticated with the same Bearer key. Each tool enforces the same scope as its REST equivalent. Call the apex host directly — cross-host redirects strip the Authorization header.

curl -X POST https://getomnified.com/api/public/v1/mcp \
  -H "Authorization: Bearer omn_sk_test_sg_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Configure a HTTPS endpoint at Settings → API → Webhooks. Every delivery is signed with HMAC-SHA256 over <timestamp>.<raw_body>. Verify the signature before trusting the payload.

Omni-Signature: t=1751780400,v1=8c7a…
Omni-Event: verification.completed
Omni-Delivery: dlv_01H…

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyOmniSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((s) => s.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "", "hex");
  const exp = Buffer.from(expected, "hex");
  return got.length === exp.length && timingSafeEqual(got, exp);
}

Journey events (journey.run.*) carry the run, journey and version ids, node ids, verdicts and reason codes. Runs in Test are marked "sandbox": true and are sent only to endpoints with Test runs switched on in Settings → Webhooks.

Deliveries retry with exponential backoff — up to 7 attempts: the first try, then retries after 1 min, 5 min, 15 min, 1 h, 6 h and 24 h. Endpoints resolving to private / RFC 1918 / loopback IP ranges are rejected at both save time and send time.

• Transport: HTTPS-only; HSTS with preload; webhooks HTTPS-only; SSRF guard blocks private ranges.
• Field-level encryption: subject name, DOB, ID number, address, and raw vendor payloads are AES-256-GCM encrypted (WebCrypto) before insert. Envelope v1:iv:ciphertext+tag supports versioned key rotation.
• Key hygiene: shown once, stored as SHA-256 + 16-char prefix, constant-time compare, per-key rate limit, immediate revocation.
• Auth boundary: RLS on every table; API paths bypass session auth but verify Bearer + scopes inside the handler.
• Logging hygiene: structured logs record method / path / status / duration / request-id / IP and only the 16-char key prefix — never the key, never full PII, never signatures.
• Data residency: every verification records a data_region derived from the jurisdiction so future in-region storage can shard on it.
• Maker-checker: sanctions-hit and high-risk case closures require a second, different-user approver enforced at the database level.

Machine-readable OpenAPI 3.1 document — feed it to any generator to produce a typed client:

GET /api/public/v1/openapi.json

Download openapi.json

• v1 · 2026-11-01 — Journey endpoints under journeys:run: start a run, read its next step, answer it, read its outcome, and mint single-use hosted links. Journey webhooks journey.run.*, with Test-run delivery opt-in per endpoint.
• v1 · 2026-08-14 — Metered product endpoints: POST /rulebook/search (rulebook:read) and POST /pilcrow (pilcrow:write), with entitlement and credit gating, sandbox demo corpus slices, sealed agent-run provenance, and new 402 insufficient_credits / 403 not_entitled problem codes.
• v1 · 2026-08-02 — Reporting API: GET /reports/summary and GET /reports/verifications under reporting:read. Added GET /build deployed-build provenance and the MCP endpoint at POST /mcp.
• v1 · 2026-07-05 — Initial public release: verifications, documents, cases, webhooks. Sandbox 300 req/min, live 1200 req/min.