API reference

Approvals

A person's go-ahead for a payment, bound to its amount and destination, expiring, and stale the moment either changes.

GET/v1/approvalsList approvals
GET/v1/approvals/{approval_id}Get an approval
POST/v1/approvals/{approval_id}/decideApprove or reject

Guides: Record payments and apply them

List approvals

GET/v1/approvals

client.approvals.list()

Approvals asked for in these books, the newest first: what waits for a decision, and what was decided.

Parameters

Name	Type	Description
`status`Query	string or null	Only `pending`, `approved`, `rejected` or `cancelled` ones.
`subject_id`Query	string or null	An id. Which resource it names is given by the field beside it.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200ApprovalPage

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/approvals" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Get an approval

GET/v1/approvals/{approval_id}

client.approvals.get()

One approval: what it approves, who decided, and whether it stands.

Parameters

Name	Type	Description
`approval_id`Path · Required	string	An id that starts with `appr_`.

Response

200ApprovalOut

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/approvals/{approval_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Approve or reject

POST/v1/approvals/{approval_id}/decide· Idempotent

client.approvals.decide()

Approve or reject, once. Needs money.approve, or an approval limit in the approval's currency that covers its amount (the Approver add-on); anyone else is refused with role. An approval past its expiry is refused with conflict: ask for another. So is a change the assistant proposed, which its person decides in the conversation.

Parameters

Name	Type	Description
`approval_id`Path · Required	string	An id that starts with `appr_`.

Request body

ApprovalDecide

Response

200ApprovalOut

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 -X POST "https://api.ledgerit.ai/v1/approvals/{approval_id}/decide" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"decision":"…"}'

Objects

The objects these operations take and return.

ApprovalPage

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

ApprovalOut

Name	Type	Description
`action`Required	string	What it lets happen: `payment.send` or `agent.change`.
`amount`Required	string or null
`can_decide`Required	boolean	Whether the caller may decide it here: pending, and theirs to approve (`money.approve`, or an approval limit in its currency that covers its amount).
`created_at`Required	string (date-time)
`currency`Required	string or null
`decided_at`Required	string (date-time) or null
`decisions`Required	array of DecisionOut
`expires_at`Required	string (date-time) or null
`id`Required	string	An id that starts with `appr_`.
`requested_by`Required	string or null	An id that starts with `usr_`.
`stands`Required	boolean	Approved, unexpired, and the subject is still what it was when asked: false once a payment's amount or destination changes.
`status`Required	string	`pending`, `approved`, `rejected` or `cancelled`.
`subject_id`Required	string	An id. Which resource it names is given by the field beside it.
`subject_type`Required	string	What is approved: `payment`, or `agent_action` (a change the assistant proposed).

ApprovalDecide

Name	Type	Description
`comment`	string or null
`decision`Required	string	`approve` or `reject`.

DecisionOut

Name	Type	Description
`actor_id`Required	string or null	An id that starts with `usr_`.
`comment`Required	string or null
`decision`Required	string
`recorded_at`Required	string (date-time)