Documentation

Authentication

Every request must include a bearer token in the Authorization header. API keys are issued per organization and scoped to a single tenant namespace. Keys do not expire but can be revoked at any time from the administrative console.

Key prefixes

Requests authenticated with a qrm_test_ key follow identical decision logic but suppress all downstream regulatory actions (SAR/STR auto-filing, evidence package generation). Use sandbox keys during development and integration testing.

Browser SDK

The Quorum Browser SDK passively collects seven behavioral signal channels from authenticated user sessions and attaches them to every API call via request headers. Integration is a two-step process: include the script, then initialize with the current user's identifier.

Include

Initialize

Headers injected

Signal channels

The SDK operates entirely passively after init(). It does not read DOM content, intercept form values, or make independent network requests. Signal collection runs in a background microtask; call sdk.destroy() on logout to clear the collection interval.

POST /api/v1/analyze

The primary decisioning endpoint. Submits a transaction or event for multi-tier fraud scoring. Returns a verdict with full reasoning, score decomposition, and active flags.

Request body

Example request

POST /api/v1/analyze HTTP/1.1
Authorization: Bearer qrm_live_••••••••
Content-Type: application/json
X-Quorum-Atomic-QID: 7f3a2b1c-...
X-Quorum-CIV-Signals: eyJjYW52YXNfaGFzaCI6...
X-Quorum-Subject-Id: usr_48f2a9e1

{
  "organizationId": "org_f84e21",
  "userId": "usr_48f2a9e1",
  "amount": 4750.00,
  "currency": "USD",
  "action": "payment",
  "ipAddress": "198.51.100.4",
  "merchantCategory": "ELECTRONICS",
  "deviceFingerprint": "dfp_9c3e..."
}

Response Schema

All responses are JSON. A successful analysis returns HTTP 200 with the following structure.

{
  "success": true,
  "verdict": "FLAG",
  "totalScore": 61,
  "finalAction": "review",
  "flags": [
    "HIGH_VELOCITY",
    "CROSS_BORDER_MISMATCH"
  ],
  "reasoning": "Transaction velocity elevated (4 in 60min). IP geolocation (DE) inconsistent with account registration (CA).",
  "scoreBreakdown": {
    "velocityScore": 25,
    "geolocationScore": 20,
    "behavioralScore": 16,
    "deviceScore": 0
  },
  "caseId": null,
  "evidencePackagePath": null,
  "processingMs": 43
}

Verdict Codes

The decision engine maps total risk score to a three-tier verdict. Thresholds are configurable per organization; the defaults below apply to all accounts at provisioning.

BLOCK verdicts at score ≥ 85 automatically trigger SAR filings under FinCEN Form 111 (US jurisdiction) and FINTRAC STR (Canadian jurisdiction) when SAR_AUTO_SUBMIT is enabled for the organization.

Flag Reference

Flags are human-readable identifiers for individual risk signals. A response may carry zero or more flags. Flags from multiple signal categories (behavioral, velocity, geographic, device) are combined into the total score.

Behavioral flags

Velocity flags

Geographic / network flags

Device flags

Institutional API

Institutional-tier endpoints are scoped to /api/institutional/v1/ and require an Operational or Sovereign access tier. All institutional endpoints apply the Atomic Handshake protocol — each request must carry a valid X-Quorum-Atomic-QID header obtained from the handshake sequence below.

Atomic Handshake

The Atomic Handshake is a two-step challenge/response protocol that binds each institutional API call to a single-use quantum-inspired state token. Tokens expire after 30 seconds.

POST /api/v1/atomic/init
Authorization: Bearer qrm_live_••••••••

→ { "qid": "7f3a2b1c-...", "ttl": 30 }

GET /api/v1/atomic/verify/:qid
Authorization: Bearer qrm_live_••••••••

→ { "challenge": "a3f8..." }

// Include challenge in subsequent request:
X-Quorum-Atomic-QID: 7f3a2b1c-...
X-Quorum-Atomic-Challenge: a3f8...

Key institutional endpoints

Error Codes

All errors return a structured JSON body with a machine-readable error code and a human-readable message.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 12 seconds.",
    "status": 429,
    "retryAfter": 12
  }
}

Webhooks

QUORUM can POST event payloads to a configured HTTPS endpoint for real-time notification of significant decisions. Webhooks are configured per organization in the administrative console.

Signed delivery

Every webhook request includes an X-Quorum-Signature-256 header containing an HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Verify the signature before processing the payload.

import crypto from 'node:crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature.replace('sha256=', ''))
  );
}

Event types

Rate Limits

Rate limits are applied per API key (not per IP). Limits are enforced at the Redis layer and reset on a rolling window.

When a rate limit is exceeded, the response includes a Retry-After header with the number of seconds until the window resets. Requests beyond the limit return HTTP 429 with code RATE_LIMIT_EXCEEDED.