Developer Documentation

Residual Genius API

Integrate residual auditing into your CRM, portfolio tools, and agent workflows. Pull audit results, sync portfolio metadata, and automate follow-up when variances are found.

Introduction

The Residual Genius API lets you read audit outcomes and (on the roadmap) submit reports, export reconciliation data, and subscribe to webhooks from your own systems. Responses are JSON over HTTPS.

Enterprise Access: API access is an Enterprise-tier capability. Most endpoints beyond the small live set below are available on request. Tell us what you are building and we will prioritize the endpoints that matter for your integration.

Base URL: https://www.residualgenius.io/api/v1 (same origin as the web app; use your deployment host in staging).

What Is Live Today

Six read-only endpoints cover permissioned Audit Passports, audits, portfolios, portfolio summaries, and flagged exceptions. Organization endpoints remain tenant-scoped; Passport links expose only their issued aggregate snapshot. Everything else on this page is roadmap.

Request API Access

Authentication

The API uses Bearer Token authentication. Send an Authorization header on every request:

Authorization: Bearer YOUR_TOKEN

Dedicated API Keys (Enterprise)

Production integrations will use organization-scoped API keys (for example rg_live_... for live, rg_test_... for sandbox). Keys are issued manually after Enterprise onboarding. Self-serve key generation is not available yet.

Pilot Access (Live Endpoints Today)

Approved pilot partners can call the live endpoints using a Supabase Access Token from an authenticatedResidual Genius session. This is interim until dedicated API keys ship. Tokens expire; refresh via the app session or request a long-lived key for production.

Never expose secrets in client-side code or public repositories. Call the API from your backend when possible.

Request API Access

Endpoints

Live

Callable today with a valid Bearer token. Org-scoped: you only see data for your organization (platform admins may pass org_id).

GET/api/v1/passports/{token}Live

Retrieve an Audit Passport

Returns the immutable, evidence-bound snapshot for an issued Audit Passport. The response contains aggregate coverage, economics, evidence references, limitations, and an integrity hash. It is not an accounting opinion or a guarantee of future performance.

Authentication: Possession token in the URL. No bearer token is required. The link expires after 30 days by default and stops working immediately when revoked. Responses are never cacheable.

Example Request (curl)

curl -s "/api/v1/passports/YOUR_ONE_TIME_TOKEN" \
  -H "Accept: application/json"

Example Request (JavaScript)

const token = "YOUR_ONE_TIME_TOKEN";
const res = await fetch(`/api/v1/passports/${token}`, {
  cache: "no-store",
  headers: { Accept: "application/json" },
});
const passport = await res.json();

Example Response

{
  "title": "Q2 portfolio evidence package",
  "evidenceHash": "64-character SHA-256 hex digest",
  "issuedAt": "2026-07-01T14:00:00.000Z",
  "expiresAt": "2026-07-31T14:00:00.000Z",
  "snapshot": {
    "schema": "residual-genius.audit-passport.v2",
    "period": { "start": "2026-04", "end": "2026-06" },
    "rowsetSha256": "64-character SHA-256 hex digest",
    "coverage": { "evaluatedRows": 1840, "reviewedRows": 8, "reviewPct": 0.4 },
    "evidence": [
      { "id": "...", "completionReceipt": { "manifestVersion": 1, "rowCount": 1840 } }
    ]
  }
}

GET/api/v1/auditsLive

List Audits

Returns a paginated-style list of residual audits for your organization, newest first. Each completed audit includes a high-level summary (merchant count, flagged items, recoverable variance). Processing audits appear without a summary until the run finishes.

Authentication: Bearer token required. Use a Supabase access token from an authenticated session during pilot access, or a dedicated API key once issued.

Query Parameters

Name	Type	Required	Description
limit	integer	No	Max results (1 to 50, default 20).
cursor	string	No	Opaque next_cursor from the prior response. Bound to this endpoint and org.
org_id	uuid	No	Platform admins only. View another org (god_admin).

Example Request (curl)

curl -s "/api/v1/audits?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example Request (JavaScript)

const res = await fetch("/api/v1/audits?limit=10", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});
const body = await res.json();

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "portfolio_id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "portfolio_name": "CardConnect Book",
      "month_year": "2026-03",
      "status": "complete",
      "batch_job_status": "ended",
      "uploaded_at": "2026-03-15T18:42:11.000Z",
      "completed_at": "2026-03-15T18:47:03.000Z",
      "summary": {
        "total_merchants": 142,
        "total_line_items": 1840,
        "flagged_count": 8,
        "amount_owed": 1247.5,
        "total_variance": -1247.5
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/api/v1/audits/{audit_id}Live

Retrieve an Audit

Returns one audit by ID for your organization, including filename and processor name. Summary metrics are included when status is complete.

Authentication: Bearer token required (same as List audits).

Query Parameters

Name	Type	Required	Description
org_id	uuid	No	Platform admins only (god_admin).

Example Request (curl)

curl -s "/api/v1/audits/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example Request (JavaScript)

const auditId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const res = await fetch(`/api/v1/audits/${auditId}`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});
const body = await res.json();

Example Response

{
  "object": "audit",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "portfolio_id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "portfolio_name": "CardConnect Book",
  "filename": "march-2026-residuals.csv",
  "processor_name": "CardConnect",
  "month_year": "2026-03",
  "status": "complete",
  "batch_job_status": "ended",
  "uploaded_at": "2026-03-15T18:42:11.000Z",
  "completed_at": "2026-03-15T18:47:03.000Z",
  "summary": {
    "total_merchants": 142,
    "total_line_items": 1840,
    "flagged_count": 8,
    "amount_owed": 1247.5,
    "total_variance": -1247.5
  }
}

GET/api/v1/portfoliosLive

List Portfolios

Returns portfolios for your organization with high-level audit stats: latest audit date, total flagged variance, and total recoverable amount. Read-only summary data, no merchant-level detail.

Authentication: Bearer token required (same as List audits).

Query Parameters

Name	Type	Required	Description
limit	integer	No	Max results (1 to 50, default 20).
cursor	string	No	Opaque next_cursor from the prior response. Bound to this endpoint and org.
org_id	uuid	No	Platform admins only (god_admin).

Example Request (curl)

curl -s "/api/v1/portfolios?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example Request (JavaScript)

const res = await fetch("/api/v1/portfolios?limit=10", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});
const body = await res.json();

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "CardConnect Book",
      "processor": "CardConnect",
      "created_at": "2025-11-02T14:20:00.000Z",
      "latest_audit_at": "2026-03-15T18:47:03.000Z",
      "latest_audit_month": "2026-03",
      "total_flagged_variance": -2847.25,
      "total_recoverable": 2847.25
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/api/v1/portfolios/{portfolio_id}/summaryLive

Portfolio Summary

Returns a rollup for one portfolio: line items audited, flagged counts, variance and recoverable totals, confirmed recoverable, mediation recovery if any, per-period breakdown, and audit recency. Summary only, no merchant-level financial detail. Returns 404 when the portfolio is outside your organization.

Authentication: Bearer token required (same as List audits).

Query Parameters

Name	Type	Required	Description
org_id	uuid	No	Platform admins only (god_admin).

Example Request (curl)

curl -s "/api/v1/portfolios/p1b2c3d4-e5f6-7890-abcd-ef1234567890/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example Request (JavaScript)

const portfolioId = "p1b2c3d4-e5f6-7890-abcd-ef1234567890";
const res = await fetch(`/api/v1/portfolios/${portfolioId}/summary`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});
const body = await res.json();

Example Response

{
  "object": "portfolio_summary",
  "id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "CardConnect Book",
  "processor": "CardConnect",
  "line_items_audited": 1840,
  "flagged_count": 8,
  "total_flagged_variance": -1247.5,
  "total_recoverable": 1247.5,
  "confirmed_recoverable": 892.0,
  "total_recovered": 750.0,
  "latest_audit_at": "2026-03-15T18:47:03.000Z",
  "latest_audit_month": "2026-03",
  "periods": [
    {
      "month_year": "2026-03",
      "line_items_audited": 920,
      "flagged_count": 5,
      "total_flagged_variance": -892.0,
      "total_recoverable": 892.0
    }
  ]
}

GET/api/v1/exceptionsLive

List Exceptions

Returns flagged underpayment findings for your organization as machine-readable data. Each row includes merchant ID, line item type, expected vs actual residuals, variance, recovery-likelihood band, triage status, period, and portfolio. Paginated with a default limit of 20 (max 50). Raw line payloads are excluded.

Authentication: Bearer token required (same as List audits).

Query Parameters

Name	Type	Required	Description
limit	integer	No	Max results (1 to 50, default 20).
cursor	string	No	Opaque next_cursor from the prior response. Bound to this endpoint, org, and filter set.
month_year	string	No	Filter by period (YYYY-MM).
portfolio_id	uuid	No	Filter by portfolio.
recovery_band	string	No	Filter by band: high, medium, or low.
status	string	No	Filter by triage status: open, reviewed, confirmed, dismissed, or unsure.
org_id	uuid	No	Platform admins only (god_admin).

Example Request (curl)

curl -s "/api/v1/exceptions?limit=20&month_year=2026-03&status=open" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example Request (JavaScript)

const res = await fetch("/api/v1/exceptions?limit=20&recovery_band=high", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});
const body = await res.json();

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "e1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_id": "MID-004821",
      "line_item_type": "Visa Interchange",
      "expected_residual": 142.5,
      "actual_residual": 98.25,
      "variance": -44.25,
      "recovery_band": "high",
      "status": "open",
      "month_year": "2026-03",
      "portfolio_id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "portfolio_name": "CardConnect Book"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoyLC4uLn0"
}

Roadmap

Planned capabilities. These endpoints are not callable today. Use the contact button on each card to request priority access.

POST/api/v1/auditsContact to Unlock

Submit an Audit

Upload a processor residual file and queue an audit job programmatically.

Intended Request

multipart/form-data: file (required), portfolio_id, month_year (YYYY-MM)

Intended Response

{ "object": "audit_job", "id": "...", "status": "queued" }

Contact to Unlock

GET/api/v1/audits/{audit_id}/reconciliationContact to Unlock

Bulk Export Reconciliation Data

Download line-item reconciliation rows for a completed audit (CSV or JSON).

Intended Request

Query: format=csv|json, findings_only=true|false

Intended Response

File download or paginated JSON rows with merchant, line item, expected, actual, variance

Contact to Unlock

POST/api/v1/webhooks/endpointsContact to Unlock

Webhook Subscriptions

Intended Request

{ "url": "https://...", "events": ["audit.completed", "audit.failed"] }

Intended Response

{ "object": "webhook_endpoint", "id": "...", "secret": "whsec_..." }

Contact to Unlock

POST (event)Your registered HTTPS URLContact to Unlock

audit.completed Webhook

Roadmap only: outbound customer webhooks are not implemented or available to enable today. Poll the audit detail endpoint for completion. The payload below is an illustrative proposed contract, not a production delivery guarantee; contact us if you want to help shape the pilot.

Intended Request

POST https://your-app.example/webhooks/residual-genius
Content-Type: application/json
X-RG-Signature: t=1710000000,v1=HMAC_SHA256_HEX
X-RG-Event-Id: evt_01H...

{
  "event": "audit.completed",
  "created_at": "2026-03-15T18:47:03.000Z",
  "data": {
    "audit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "org_id": "o1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "portfolio_id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "month_year": "2026-03",
    "status": "complete",
    "summary": {
      "total_merchants": 142,
      "flagged_count": 8,
      "amount_owed": 1247.5
    }
  }
}

Proposed behavior: verify X-RG-Signature with your webhook secret before trusting the payload.

Intended Response

Proposed behavior only: respond with HTTP 2xx quickly and deduplicate by X-RG-Event-Id. Outbound delivery and retry infrastructure are not currently available.

Contact to Unlock

POST/api/v1/mediation/casesContact to Unlock

Dispute and Mediation Case Creation

Open a managed mediation or self-service dispute case from confirmed findings.

Intended Request

{ "audit_id", "line_item_ids", "processor_email" }

Intended Response

{ "object": "mediation_case", "id", "status", "portal_url" }

Contact to Unlock

GET/api/v1/schedule-a/ratesContact to Unlock

Schedule A Management

Read and version Schedule A rate tables used for reconciliation.

Intended Request

Query: portfolio_id, effective_date

Intended Response

{ "object": "schedule_a_version", "rates": [{ "line_item_type", "rev_share_pct" }] }

Contact to Unlock

GET/api/v1/benchmarks/processorsContact to Unlock

Processor Benchmark Data

Anonymized processor accuracy and variance benchmarks for portfolio comparison.

Intended Request

Query: processor, line_item_type

Intended Response

{ "object": "benchmark", "processor", "metrics": { "median_variance_pct", "sample_size" } }

Contact to Unlock

Rate Limits

Rate limits protect platform stability and align with your subscription tier. The live read API enforces durable per-endpoint request windows for both the authenticated user and organization.

Per user: 120 requests per minute per endpoint
Per organization: 600 requests per minute per endpoint
Audit Submissions (Roadmap): concurrency limits per organization
When exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds)

Need higher throughput for batch sync or embedded auditing? Mention your use case in an API Access Request.

Errors

The API uses standard HTTP status codes. Error bodies are JSON with a consistent shape:

Error Response Shape

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid authorization header",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

HTTP Status	Code	Meaning
400	invalid_request	Malformed parameters or body
401	unauthorized	Missing or invalid Bearer token
403	forbidden	Valid token but not allowed for this org or action
404	not_found	Resource does not exist or is outside your org scope
429	rate_limited	Live request window exceeded
500	internal_error	Unexpected server error; retry with backoff

Successful responses may include X-Request-Id for support correlation. Include it when contacting us about a failed call.

Changelog

2026-06-21Portfolios, Exceptions, and Webhook Roadmap

Live: GET /api/v1/portfolios, GET /api/v1/portfolios/:id/summary, and GET /api/v1/exceptions
Roadmap: audit.completed webhook (Contact to unlock)

2026-06-20Initial API Documentation Published

Public docs at /docs with live and roadmap endpoints
Live: GET /api/v1/audits and GET /api/v1/audits/:id
Enterprise API key self-serve: not yet available; contact for pilot access