API reference

Questions

A question about a transaction asked of one member, and their answer.

GET/v1/questionsList questions about records
POST/v1/questionsAsk a member a question
GET/v1/questions/{question_id}Get a question and its answer
POST/v1/questions/{question_id}/answerAnswer a question you were asked
POST/v1/questions/{question_id}/closeClose a question

Guides: Review and file transactions

List questions about records

GET/v1/questions

client.questions.list()

Questions, newest first: one record's, those waiting on someone, or every one in the books.

Parameters

Name	Type	Description
`about`Query	string	What the questions are about. One of `transaction`, `journal_entry`Default transaction
`subject_id`Query	string or null	An id. Which resource it names is given by the field beside it.
`status`Query	string or null	Only questions in this state. One of `open`, `answered`, `closed`
`asked_of`Query	string or null	Only those asked of this member; `me` for the caller.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200QuestionPage

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

Ask a member a question

POST/v1/questions· Idempotent

client.questions.create()

Ask a member a question about a record. They are told, and it waits on their Home until they answer.

The same question is never asked twice: a question about a transaction no person or rule has decided, that one of the books' rules covers, is not sent. The rule files it, and the answer is 200 with outcome: filed_by_rule naming the rule. ask_anyway sends it regardless.

Request body

NewQuestion

Response

201QuestionOut | FiledByRuleOut

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/questions" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"about":"transaction","asked_of":"…","body":"…","subject_id":"…"}'

Get a question and its answer

GET/v1/questions/{question_id}

client.questions.get()

One question, and its answer once there is one.

Parameters

Name	Type	Description
`question_id`Path · Required	string	An id that starts with `qst_`.

Response

200QuestionOut

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

Answer a question you were asked

POST/v1/questions/{question_id}/answer· Idempotent

client.questions.answer()

Answer a question you were asked. Whoever asked is told.

On a question about a transaction, the answer can also file it: with account_id the transaction is filed there, as filing it by hand does, and the question is closed. With rule ("Do this every time") a rule is written from the answer first — the transaction's counterparty, plus the memo words and paper given — so the next transaction like it is filed with no question and no model. The rule's account is checked when it is written: a header or closed account is refused, nothing is filed, and the answer is still kept, with filing_refused saying why. Filing needs books.post.

Parameters

Name	Type	Description
`question_id`Path · Required	string	An id that starts with `qst_`.

Request body

AnswerIn

Response

200QuestionOut

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/questions/{question_id}/answer" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"answer":"…"}'

Close a question

POST/v1/questions/{question_id}/close· Idempotent

client.questions.close()

Close a question nobody needs any more, answered or not.

Parameters

Name	Type	Description
`question_id`Path · Required	string	An id that starts with `qst_`.

Response

200QuestionOut

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/questions/{question_id}/close" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Objects

The objects these operations take and return.

QuestionPage

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

NewQuestion

Name	Type	Description
`about`Required	string	One of `transaction`, `journal_entry`
`ask_anyway`	boolean or null	Send it even when a rule covers the transaction. Without it, a question about a transaction no person or rule has decided, that a rule covers, is not sent: the rule files it.
`asked_of`Required	string	The member who should answer, by user id.
`body`Required	string
`subject_id`Required	string	An id. Which resource it names is given by the field beside it.

QuestionOut

Name	Type	Description
`about`Required	string
`answer`Required	string or null
`answered_at`Required	string (date-time) or null
`asked_by`Required	string or null	An id that starts with `usr_`.
`asked_by_email`Required	string or null
`asked_of`Required	string or null	An id that starts with `usr_`.
`asked_of_email`Required	string or null
`body`Required	string
`closed_at`Required	string (date-time) or null
`created_at`Required	string (date-time)
`filing_refused`	FilingRefusedOut or null	Only on the answer's own response: why the transaction was not filed, and no rule written, though the answer was kept. The code is the one filing or writing the rule alone is refused with (`account_not_usable` for a header or closed account, `rule_conflict`, `period_closed`, …). Null when nothing was refused.
`id`Required	string	An id that starts with `qst_`.
`rule_id`	string or null	An id that starts with `rule_`.
`status`Required	string	`open`, `answered` or `closed`.
`subject_id`Required	string	An id. Which resource it names is given by the field beside it.

FiledByRuleOut

What asking about a transaction a rule already covers answers: it was filed by that rule, and nobody was asked.

Name	Type	Description
`about`Required	string	Always `transaction`.
`category_account_id`Required	string	The GL account it was filed to.
`outcome`Required	filed_by_rule	Always `filed_by_rule`: what tells this answer from a question.
`rule_id`Required	string	The rule that filed it.
`rule_name`Required	string	That rule's name.
`subject_id`Required	string	The transaction, now filed.

AnswerIn

Name	Type	Description
`account_id`	string or null	An id that starts with `gla_`.
`answer`Required	string
`dimensions`	array of LineDimensionIn	The department, and any other dimension value, the transaction names when it is filed. A value it already names stands.
`rule`	AnswerRuleIn or null	"Do this every time": write a rule from this answer, so the same question is never asked again. The transaction is filed under the rule's account when `account_id` is absent. Validated when written: a header or closed account is refused, and the answer is kept with `filing_refused` saying why.

FilingRefusedOut

Why an answer filed nothing, though it was kept.

Name	Type	Description
`code`Required	string	The refusal's code, as filing or writing the rule alone returns it.
`message`Required	string

LineDimensionIn

Name	Type	Description
`dimension_id`Required	string	An id that starts with `dim_`.
`value_id`Required	string	A value of that dimension.

AnswerRuleIn

"Do this every time": the narrowest rule covering the transaction — its counterparty by name (or its description, when it names none), on the same event type — filing to account_id.

Name	Type	Description
`account_id`Required	string	The GL account every matching transaction is filed to.
`dimensions`	array of LineDimensionIn	The department, and any other dimension value, a matching transaction names.
`document_kind`	string or null	Only with this paper behind it: an `invoice` or `receipt` linked as evidence, or `none` for a transaction with no paper. Any when absent. One of `invoice`, `receipt`, `none`
`memo_pattern`	string or null	Only when the memo — the description, or the line the bank printed — holds these words.