Developers
Show batch ingestion and synchronization guides and endpoints, core concepts, and the content hash calculator.
Explore the docs

Work with data

Read data

Retrieve records, list business IDs, and paginate with opaque cursors.

On this page

All reads below use Authorization: Bearer YOUR_API_KEY and return only that tenant's data. Use logical table names, not physical database table names. Public clients do not need an internal secret.

List records

http
GET /api/tables/payments?limit=25&sort_by=created_at&sort_order=desc
Authorization: Bearer YOUR_API_KEY
json
{
  "data": [{"payment_id": "PAY-2024-001", "disbursement_id": "DSB-2024-001", "payment_total": 250, "currency": "USD"}],
  "pagination": {"limit": 25, "has_more": false}
}
ParameterContract
limitInteger 1-1000, default 50; invalid values return 400, not silent clamping
cursorOpaque token from pagination.next_cursor; URL-encode it
sort_byDefaults to created_at; asset_status and disbursement_status use on_date. A custom value must name a supported non-nullable column in that table
sort_orderasc or desc, default desc
include_countExactly true or false; true adds total and total_pages. Counts may be cached
date_fieldAn actual date/timestamp column; required if either date bound is supplied
start_date, end_dateInclusive valid date bounds; start must not be after end
searchPartial match across searchable ID/status columns for the table

Sorting uses primary-key tiebreakers for deterministic pagination. Rows with a null selected sort value are excluded. Keep the same table, filters, and sort on every page. Discard legacy raw-ID/timestamp cursors and start again from the first page.

API 4.4.0 rejects unknown or duplicate query parameters, malformed integer/boolean/enum values, invalid date ranges, and incompatible cursor values with 400. Query strings are limited to 8192 characters and each value to 4096; control characters are rejected. Inspect code and issues for the offending query path, such as /limit. Do not sort on nullable payment_date; use a supported non-nullable field such as created_at, and use date_field for date filtering.

List business IDs

http
GET /api/tables/clients/ids?limit=50
Authorization: Bearer YOUR_API_KEY
json
{
  "data": ["client-001", "client-002"],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJ2IjoxLCJzIjoiY2xpZW50LTAwMiIsImsiOltdfQ"
  }
}

The limit is 1-1000, default 50, and IDs sort ascending. Pass the returned token as cursor, not client-002 itself. The token is opaque even if you recognize how this illustrative token is encoded.

The ID-list endpoint accepts only limit and cursor; row-list filters and sorting parameters are rejected here.

Example pagination loop (supply your environment's base URL and API key securely):

javascript
async function listClientIds(baseUrl, apiKey) {
  const ids = new Set();
  const url = new URL('/api/tables/clients/ids', baseUrl);
  url.searchParams.set('limit', '1000');
  while (true) {
    const response = await fetch(url, {headers: {Authorization: `Bearer ${apiKey}`}});
    if (!response.ok) throw new Error(`Read failed: ${response.status}`);
    const page = await response.json();
    page.data.forEach((id) => ids.add(id));
    if (!page.pagination.has_more) return ids;
    if (!page.pagination.next_cursor) throw new Error('Missing continuation token');
    url.searchParams.set('cursor', page.pagination.next_cursor);
  }
}

Choose create versus update

Compare source IDs with stored IDs: absent IDs use create; existing IDs use update. Do not probe with a create and fall back after 409: terminal failures can reserve the key and add error noise. For a single interactive record, GET /api/tables/{table}/{id} gives 200 or 404.

Use sync-state when you also need version-3 hashes to skip redundant updates. A page with missing, older, or unknown hash metadata returns 409 CONTENT_HASH_NOT_INITIALIZED until the operator backfills it. ID-based reconciliation and normal ingestion remain available. Missing source IDs should be reviewed, not automatically deleted.

Get one record

http
GET /api/tables/disbursements/DSB-2024-001
Authorization: Bearer YOUR_API_KEY
json
{"data": {"disbursement_id": "DSB-2024-001", "client_id": "BR-2024-001", "disbursement_amount": 10000, "currency": "USD"}}

For the four main tables, the path ID is the business ID (client_id, disbursement_id, payment_id, or operation_id). Other allowed tables use their table primary key. Returned database rows are not valid ingest bodies: select allowed fields and add the correct envelope/step instead of copying audit fields, content_hash, content_hash_version, or request_hash_version back to ingestion.

Single-record reads accept no query parameters. Numeric history IDs must be positive PostgreSQL bigint values.

Allowed tables

clients, disbursements, payments, operations, purchase_clients, asset_status, disbursement_status, write_offs, rebates, extensions, restructures.

Internal event tables, deleted mirrors, and silver/gold tables are not exposed through these routes.

Errors

  • 400: invalid identifier, table, cursor, limit, sort/date-field, dates, or unknown/duplicate query parameters. Inspect INVALID_QUERY, INVALID_CURSOR, and field issue paths.
  • 401: missing or invalid API key.
  • 403: an unnecessary internal header failed verification; normal public requests use bearer authentication only.
  • 404: requested record or provisioned table does not exist; inspect code.
  • 500 / 503: unexpected read, authentication-storage, or dependency failure; follow retryable and action.

Retain error_id and the current X-Correlation-ID for support. See errors and recovery for the response format and public code catalogue.

Validate locally. Verify in sandbox.
The JSON validator checks structure and rounding. Credentials, existing records, and server-side state still require your test environment.

Search documentation

Start typing to find your next step.

    ↑ ↓ navigate Enter openLocal, private search