API reference

Connections

Each provider the books are connected to, read only: whether it syncs, when it last did, what went wrong, and whether it may read the provider's people.

GET/v1/connectionsList the books' connections
GET/v1/connections/{connection_id}Get a connection and how it is doing

Guides: Connect your banks, cards, payroll and revenue

List the books' connections

GET/v1/connections

client.connections.list()

The books' connections, oldest first, each with how it is doing: in plain words, against its freshness target, with any reauth deadline, how much of its history is in, and whether it may read the provider's people.

Parameters

Name	Type	Description
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200ConnectionPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/connections" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Get a connection and how it is doing

GET/v1/connections/{connection_id}

client.connections.get()

One connection and how it is doing. Never its credentials.

Parameters

Name	Type	Description
`connection_id`Path · Required	string	An id that starts with `conn_`.

Response

200ConnectionOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/connections/{connection_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Objects

The objects these operations take and return.

ConnectionPage

A page of the books' connections.

Name	Type	Description
`data`Required	array of ConnectionOut
`has_more`Required	boolean
`next_cursor`Required	string or null

ConnectionOut

A connection's state. Never its credentials.

Name	Type	Description
`account_id`Required	string or null	An id that starts with `gla_`.
`configured`Required	boolean	Whether credentials are on file. Never the credentials themselves.
`health`	ConnectionHealthOut or null	How it is doing; given when connections are listed or read one by one.
`id`Required	string	An id that starts with `conn_`.
`kind`Required	string	`banking`, `card`, `revenue`, `payroll`, `ledger`, …
`label`Required	string or null	What tells two connections to one provider apart.
`last_error`Required	string or null	What went wrong last, in the provider's words; null when nothing did.
`last_synced_at`Required	string (date-time) or null	When it last synced, successfully or not.
`people_unreadable_since`	string (date-time) or null	Since when the provider has refused to let the books read its people (Brex `users.readonly`, Ramp `users:read`), so cardholders are known by name only. Null when it may. Connecting the provider again with that scope grants it, and the next sync clears this.
`provider`Required	string	What it connects: `brex`, `ramp`, `mercury`, `stripe`, …
`status`Required	string	`active`, `error`, `paused` or `revoked`.

ConnectionHealthOut

How the connection is doing, in plain terms (PLAN.md §8.3).

Name	Type	Description
`backfill_from`Required	string (date)	How far back its history is asked for: 12 months.
`backfill_progress`Required	number	0 to 1: how much of that history is in.
`behind_by_hours`Required	number or null	How far past its target it is; null within it.
`freshness_target_hours`Required	integer	How recent its last good sync should be: 24, or 1 for Stripe.
`history_from`Required	string (date) or null	The oldest transaction it has brought in.
`last_success_at`Required	string (date-time) or null	The last sync that succeeded.
`reauth_by`Required	string (date-time) or null	When the provider needs a person to sign in again, if it says.
`state`Required	string	`healthy`, `behind` (no successful sync within its target), `failing`, `reauth_soon` (a person must sign in again within a week), `paused` or `revoked`.