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://residualgenius.io/api/v1 (same origin as the web app; use your deployment host in staging).

What is live today

Five read-only endpoints list audits, portfolios, portfolio summaries, and flagged exceptions for your organization. Everything else on this page is roadmap: documented so you can plan integrations and request early access.

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/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).
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
}

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).
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
}

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).
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, or dismissed.
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
}

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

When enabled, Residual Genius POSTs a signed JSON event to your registered URL each time an audit completes, so your systems can pull results automatically without polling. Requires signature verification on your side and supports delivery retries. Contact us to enable webhook delivery for your organization.

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
    }
  }
}

Verify X-RG-Signature with your webhook secret before trusting the payload. Failed deliveries are retried with exponential backoff.

Intended response

Your endpoint should respond with HTTP 2xx quickly (within 10 seconds). Non-2xx responses trigger retries. Idempotency: use X-RG-Event-Id to dedupe.

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. Limits below apply once dedicated API keys launch; pilot session tokens share the same org-level AI and upload guards as the web app.

Default (planned): 60 requests per minute per API key
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_limit_exceeded	Too many requests (planned for API keys)
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