Integration guides

Build against ReconIQ

These guides cover everything you need to integrate with the ReconIQ API in production, following the same standards that back the OpenAPI 3.1 spec at /api/public/openapi.yaml.

1. Authentication

ReconIQ uses OAuth 2.0 Bearer tokens (RFC 6750). Tokens are Supabase-issued JWTs obtained through the sign-in flow (email/password, magic link, or your configured enterprise SSO — SAML 2.0 or OIDC). Every request MUST send the token in theAuthorization header.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens are scoped by tenant and by role (viewer, analyst, admin, platform_admin). Access is enforced twice — in the server function middleware and again at the database via Postgres RLS. A missing or expired token returns 401; a token that lacks the required role returns 403.

2. Requests & responses

All requests use JSON (application/json; charset=utf-8). Timestamps are ISO-8601 in UTC (2026-07-05T14:22:19Z). IDs are UUID v4. Money is returned as a decimal string plus an ISO-4217 currency code — never a float.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-07-05T14:22:19Z",
  "amount": "1250.00",
  "currency": "USD"
}

3. Error model (RFC 7807)

Errors follow RFC 7807 problem+json. Every error response carries a stable type URI, HTTP status, human-readable title, and a request_id you can quote when contacting support.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type":     "https://reconintelligence.app/errors/validation",
  "title":    "Validation failed",
  "status":   422,
  "detail":   "amount must be a positive decimal",
  "instance": "/api/reconciliation/batches",
  "request_id": "req_01JB3QK6H3Q0M8W2S4X7Y9Z1AB",
  "errors": [ { "field": "amount", "code": "positive_decimal" } ]
}

4. Pagination

List endpoints use cursor pagination for stable ordering and O(1) performance. The next page cursor is opaque — treat it as a string and pass it back verbatim in ?cursor=. The Link header (RFC 8288) mirrors the same information for HTTP-native clients.

GET /api/reconciliation/batches?limit=50
→ 200 OK
Link: </api/reconciliation/batches?cursor=eyJvIjoiMjAyNi0wNy0wNVQxNDoyMjoxOVoifQ>; rel="next"

{
  "data":   [ { "id": "..." }, ... ],
  "next":   "eyJvIjoiMjAyNi0wNy0wNVQxNDoyMjoxOVoifQ",
  "limit":  50
}

5. Idempotency

For any POST that creates or mutates state (batches, exports, webhook subscriptions), send an Idempotency-Key header — a client-generated UUID v4. The API stores the first response for 24 hours and returns it verbatim on any retry with the same key, so a retried network request never creates a duplicate resource.

POST /api/reconciliation/batches
Idempotency-Key: example-idempotency-key
Authorization: Bearer $FVI_TOKEN

6. Rate limits

Every tenant is metered with a token bucket (default: 600 req/min sustained, burst 100 per second). Responses always carry the standard headers:

RateLimit-Limit:     600
RateLimit-Remaining: 587
RateLimit-Reset:     42        # seconds until refill
Retry-After:         2         # only sent on 429

On 429 Too Many Requests, back off using exponential jitter — the safe minimum is Retry-After.

7. Webhooks

Subscribe via POST /api/webhooks with a target URL and an event filter. Each delivery is signed with HMAC-SHA256 over the raw body using your per-endpoint secret; verify signatures with a timing-safe comparison before you trust the payload. Deliveries carry a monotonically increasing webhook-id andwebhook-timestamp; reject any timestamp older than 5 minutes to prevent replay attacks.

POST /your/endpoint  HTTP/1.1
webhook-id:         evt_01JB3QK6H3Q0M8W2S4X7Y9Z1AB
webhook-timestamp:  1782529636
webhook-signature:  v1,sha256=8c...

Event catalogue: batch.completed, batch.failed, exception.created, exception.resolved, export.ready, connector.sync.completed.

8. Versioning & deprecation

The API follows SemVer 2.0. The current major is v4. Breaking changes ship in a new major only. When we deprecate a field or route, responses gain the Deprecation and Sunset headers (RFC 8594) with at least 12 months notice before removal.

Deprecation: true
Sunset:      Wed, 01 Jul 2027 00:00:00 GMT
Link:        <https://reconintelligence.app/developers/changelog>; rel="deprecation"

9. SDK examples

curl

curl -sS https://reconintelligence.app/api/reconciliation/batches \
  -H "Authorization: Bearer $FVI_TOKEN"

TypeScript (fetch)

const res = await fetch(
  "https://reconintelligence.app/api/reconciliation/batches",
  { headers: { Authorization: `Bearer ${process.env.FVI_TOKEN}` } },
);
if (!res.ok) throw new Error(await res.text());
const { data, next } = await res.json();

Python (httpx)

import os, httpx
r = httpx.get(
  "https://reconintelligence.app/api/reconciliation/batches",
  headers={"Authorization": f"Bearer {os.environ['FVI_TOKEN']}"},
  timeout=30,
)
r.raise_for_status()
print(r.json())

Java (HttpClient)

HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://reconintelligence.app/api/reconciliation/batches"))
  .header("Authorization", "Bearer " + System.getenv("FVI_TOKEN"))
  .GET().build();
HttpResponse<String> res = HttpClient.newHttpClient()
  .send(req, HttpResponse.BodyHandlers.ofString());

10. ERP connectors

Native connectors for SAP, Oracle EBS/Fusion, Finacle, Flexcube, and Tally normalize their ledgers into the ReconIQ reconciliation schema. See docs/connectors/ in the platform documentation for setup runbooks, OAuth/credential flow, and the reconciliation output schema per connector.

11. Support

Email [email protected] with the request_id from the failing response. Security issues: [email protected] — see also our disclosure policy at /.well-known/security.txt.