Developers
API reference
The endpoints for integrating and operating fraud prevention. JSON over HTTPS; every response has the same envelope. New here? Start with the integration guide.
Conventions
Requests and responses
Access
Tokens and roles
Send Authorization: Bearer <access token>. Each account has one role: admin, integration (your systems), analyst (fraud_analyst) or approver (the decision authority, for example a CMS official) or examiner (a regulator: reads with personal fields withheld, decrypts granted records offline). All roles means any of the five; other accounts have no access. Staff accounts also send X-Access-Purpose (and X-Access-Reference where the purpose needs one) when reading personal or case data or changing anything.
Envelope
Same shape everywhere
{ "success": true, "data": …, "meta": { "requestId", "timestamp" } }, or "success": false with error.code and error.message.
Errors
Standard status codes
400 invalid input (with the fields at fault), 401 no or expired token, 403 wrong role, 404 not found, 409 conflict, 429 rate-limited, 5xx server error. Quote meta.requestId when reporting one.
Authentication
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/auth/login | Sign in with email and password; returns an access token, a refresh token and the user. | Public |
| POST | /v1/auth/refresh | Exchange a refresh token for a new pair. | Public |
| POST | /v1/auth/logout | Revoke a refresh token. | Public |
| GET | /v1/auth/me | The signed-in user. | Any account |
Entity types
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/entity-types | Register a record type: its JSON Schema and fraud identifiers. | Admin |
| GET | /v1/entity-types | List registered types. | All roles |
| GET | /v1/entity-types/{name} | One type, with its schema and identifiers. | All roles |
Entities
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/entities | Create a record; its data is validated against the type's schema. | Admin · integration |
| GET | /v1/entities | List records. Filters: type, jurisdiction, limit, offset. | All roles |
| GET | /v1/entities/{id} | One record as it stands. | All roles |
| PUT | /v1/entities/{id} | Replace a record's data after your system of record changes it. | Admin · integration |
| DELETE | /v1/entities/{id} | Delete a record. | Admin |
Rules
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/rules | Create a rule: condition, consequence, entity and event type it applies to. | Admin |
| GET | /v1/rules | List rules. Filters: entityType, eventType, jurisdiction, status, severity, tags, effectiveAt. | Admin · analyst |
| GET | /v1/rules/{id} | One rule. | Admin · analyst |
| PUT | /v1/rules/{id} | Change a rule; each change creates a new version. | Admin |
| DELETE | /v1/rules/{id} | Delete a rule that has never made a decision. A rule with decisions returns 409: set it INACTIVE instead. | Admin |
| GET | /v1/rules/{id}/versions | Every version of a rule. | Admin · analyst |
| GET | /v1/rules/{id}/versions/{version} | One version. | Admin · analyst |
| GET | /v1/rules/{id}/audit-log | Who changed the rule, and when. | Admin · analyst |
Events and decisions
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/events/process | Check an event against the record, the rules and fraud memory. Returns the decision, its audit record id, any fraud cases and the chain anchor. | Admin · integration |
| GET | /v1/events/{id} | One event as received. | All roles |
| GET | /v1/decisions/{id} | A decision with every rule evaluated, the event and the record. | All roles |
| GET | /v1/decisions | List decisions. Filters: entityId, eventId, status, startDate, endDate, limit, offset. | All roles |
Evidence
| Method | Path | What it does | Access |
|---|---|---|---|
| GET | /v1/audits/{id} | An audit record: the record, event, rules and fraud context the decision was based on, and its integrity hash. | All roles |
| GET | /v1/audits/{id}/verify | Recompute the hash and compare it with the stored and on-chain copies. | All roles |
| GET | /v1/audits/{id}/evidence | Offline evidence bundle (pact-evidence/1): the sealed record, its signed PACT transaction, Merkle proof and commit certificate. Check it with pact verify. | All roles |
| POST | /v1/audits/verify-batch | Check many records at once (auditIds, a caseId, or a date range): each against its hash and its PACT copy. | Admin · analyst · approver |
Fraud cases and watchlist
| Method | Path | What it does | Access |
|---|---|---|---|
| GET | /v1/fraud/cases | List cases. Filters: status, pattern. | Admin · analyst · approver |
| GET | /v1/fraud/cases/{id} | One case with its evidence. | Admin · analyst · approver |
| PATCH | /v1/fraud/cases/{id} | Set status (OPEN, INVESTIGATING, CONFIRMED_FRAUD, FALSE_POSITIVE, CLOSED), assignee or resolution. Confirming blocks the subject; a false positive clears the signals it raised. | Admin · analyst |
| GET | /v1/fraud/watchlist | List entries. Filters: type, level, active. | Admin · analyst · approver |
| POST | /v1/fraud/watchlist | Add an identity: type, value, level (BLOCK or WATCH), reason, optional expiry. | Admin · analyst |
| PATCH | /v1/fraud/watchlist/{id} | Change an entry's level, reason or active flag. | Admin · analyst |
| GET | /v1/fraud/cases/{id}/evidence-package | Everything behind a case, with each decision's sealed hash and PACT receipt; package hash and signed manifest. | Admin · analyst · approver |
| POST | /v1/fraud/cases/{id}/handoff | Hand a case to another region or contractor: toRegion, actionRequested, urgency, restrictions, dueAt, receivingOwner. Signed transfer receipt recorded on PACT. | Admin · analyst |
| POST | /v1/fraud/handoffs/{id}/acknowledge | The receiver confirms receipt (signed and recorded). | Admin · analyst |
| POST | /v1/fraud/handoffs/{id}/request-info | The receiver asks for more information; the sender answers with answer-info. | Admin · analyst |
| POST | /v1/fraud/handoffs/{id}/accept | Accept (or decline) a handoff; only acceptance moves the case. | Admin · analyst |
Medicare program integrity
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/medicare/claims | X12 837P or FHIR R4 claims, up to 500 per request; one decision per claim. | Admin · integration |
| POST | /v1/medicare/pi/leads | Receive a complaint, referral or analytical finding (one intake envelope for every source). Duplicates and earlier matters are found; no case opens until the decision authority accepts it. | Admin · analyst · approver |
| POST | /v1/medicare/pi/leads/bulk | Up to 500 leads as a JSON array or CSV. | Admin · analyst · approver |
| POST | /v1/medicare/pi/leads/{id}/accept | The decision authority opens an investigation from a lead (or declines it), with a reason. Signed and recorded on PACT. | Admin · analyst · approver |
| GET | /v1/medicare/pi/subjects/{type}/{value} | Everything about one provider or beneficiary over time: leads, cases with their outcome, actions, requests, claim decisions, links. | Admin · analyst · approver |
| POST | /v1/medicare/pi/subjects/{type}/{value}/resolve | Entity resolution: providers that may be the same actor (location, phone, authorized official, name), each with its basis and score, for an analyst to confirm or reject. | Admin · analyst · approver |
| POST | /v1/medicare/pi/cases/{id}/evidence | Register an evidence item: its SHA-256 (or the file, hashed and not kept), repository, source, collection method and custodian. | Admin · analyst · approver |
| POST | /v1/medicare/pi/evidence/{id}/verify | Check a file against its registered hash; the result joins the custody chain. | Admin · analyst · approver |
| POST | /v1/medicare/pi/cases/{id}/actions | Prepare an administrative action (payment suspension, revocation, OIG or law enforcement referral, review) with its action-ready checklist. | Admin · analyst · approver |
| POST | /v1/medicare/pi/actions/{id}/approve | The decision authority approves, returns or declines a submitted action; never the person who recommended it. | Admin · analyst · approver |
| POST | /v1/medicare/pi/requests | Log a request for information or assistance, or a vetting request: standard or expedited lane, checked for completeness. | Admin · analyst · approver |
| POST | /v1/medicare/pi/directives | Issue a versioned, signed directive (priority, restriction, instruction, pause), or answer a request for direction. | Admin · analyst · approver |
| GET | /v1/medicare/pi/cases/{id}/clock | Elapsed time split into investigator-controlled time and time waiting on the decision authority or partners. | Admin · analyst · approver |
| GET | /v1/medicare/pi/metrics | Intake, action, handoff, request, evidence and direction measures, with harm indicators. | Admin · analyst · approver |
| POST | /v1/medicare/pi/leads/{id}/translations | Add a translation of a lead (human or machine, attributed); the original stays as received. | Admin · analyst · approver |
| POST | /v1/medicare/pi/sla/matrix | Set a service-level target: kind of work, priority, hours, who the clock is on, escalation contact, when the clock stops. Versioned and signed. | Admin · analyst · approver |
| GET | /v1/medicare/pi/sla/status | Open work against its target: on track, at risk, breached. Breaches are escalated once. | Admin · analyst · approver |
| GET | /v1/medicare/pi/sla/compliance | Share of work done within target, by kind, priority and who the clock is on. | Admin · analyst · approver |
| POST | /v1/medicare/pi/templates | Propose a program version of an action checklist; built-in items cannot be removed or loosened. | Admin · analyst · approver |
| POST | /v1/medicare/pi/templates/{id}/approve | A second person approves the template; signed and recorded on PACT. | Admin · analyst · approver |
Payments screening
| Method | Path | What it does | Access |
|---|---|---|---|
| GET | /v1/payments/lists | Sanctions lists loaded (US OFAC SDN, UN, EU, Japan MOF, custom), each with its version, SHA-256 and source. | Admin · analyst · approver · examiner |
| POST | /v1/payments/lists/{list} | Load a list: OFAC_SDN, UN or EU as the publisher's XML, JP_MOF or CUSTOM as CSV, or { url } from the publisher. | Admin |
| POST | /v1/payments/instructions | Receive a payment instruction: every party is screened and the clearance is decided; the screening record is sealed with the payment in one record. | Admin · integration |
| POST | /v1/payments/instructions/{id}/release | Release: the parties are re-screened automatically against the newest lists, then the release is decided and sealed. | Admin · integration |
| GET | /v1/payments/instructions/{id}/trail | The payment's whole trail: clearance and release, each with who was screened, list versions, time, result and PACT receipt; signed. | Admin · analyst · approver · examiner |
| POST | /v1/payments/screenings/{id}/review | Review a potential match: false positive (with the reason) or true match; never by the account that screened. | Admin · analyst |
Examiner access
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/examiner/keys | The examiner registers an X25519 public key (the private key never leaves their machine). | Examiner |
| GET | /v1/examiner/grants | Access grants: the examiner's own, or all for an administrator. | Admin · examiner |
| POST | /v1/examiner/grants | Request examiner access to specific payments, with a reason and an expiry. | Admin |
| POST | /v1/examiner/grants/{id}/approve | A second administrator approves: each payment's data key is wrapped to the examiner's key; recorded on PACT. | Admin |
| GET | /v1/examiner/grants/{id}/package | The examiner downloads the granted records and wrapped keys, and decrypts them offline with their private key. | Admin · examiner |
Administration
| Method | Path | What it does | Access |
|---|---|---|---|
| GET | /v1/access/purposes | The purposes of use your role may state, and whether a purpose is required. | All roles |
| GET | /v1/audit-log/purposes | Purpose-of-use report: who accessed personal or case data, for what purpose and reference. | Admin |
| GET | /v1/users | Staff accounts with role, regions, languages, MFA and access end date. | Admin |
| POST | /v1/users | Create an account (temporary accounts with an access end date); returns a one-time password. | Admin |
| GET | /v1/export | Every record in open format (newline-delimited JSON) with a signed manifest; sensitive fields stay encrypted unless decrypt=true with a reason. | Admin |
| POST | /v1/rules/{id}/versions/{version}/backtest | Replay a proposed rule version against past decisions and count what would change. | Admin |
| POST | /v1/rules/{id}/versions/{version}/rollback | Propose an earlier version again (two-person approval applies). | Admin |
Pilot applications
| Method | Path | What it does | Access |
|---|---|---|---|
| POST | /v1/pilot-applications | Submit an application (the website form). Rate-limited, with spam checks. | Public |
| GET | /v1/pilot-applications | List applications with counts per status. Filters: status, q (name, company, email or country), limit, offset. | Admin |
| GET | /v1/pilot-applications/export.csv | Export applications as CSV. Filter: status. | Admin |
| GET | /v1/pilot-applications/{id} | One application with its follow-up notes. | Admin |
| PATCH | /v1/pilot-applications/{id} | Change status (NEW, UNDER_REVIEW, CONTACTED, QUALIFIED, CLOSED) or add a note. | Admin |
| POST | /v1/pilot-applications/{id}/resend-emails | Send the notification and confirmation emails that have not gone out. | Admin |
Health
| Method | Path | What it does | Access |
|---|---|---|---|
| GET | /health/live | The process is running. | Public |
| GET | /health/ready | The database is reachable; 503 when it is not. | Public |
See it end to end
Every reference scenario in the repository drives these endpoints from a shell script, with the request and the expected decision side by side. Run the reference scenarios