Preview a reconciliation match

Previews matching a bank transaction to a purchase bill (candidate_type: bill), a filed VAT payable (reconcilable_payable) or a dividend (dividend) without booking anything, and returns the confirmation token the match needs. For a dividend the preview carries a dividend block: the gross, SDC, GeSY and net, the amount expected, the difference and settles (in_full, instalment, in_full_with_overpayment or in_full_with_difference). A declared dividend is frozen at its declaration; an interim paid in one event is rated at the bank line's date. Dividend refusals are named: dividend_not_payable (void, already paid, or a final not yet declared), dividend_paid_before_declaration, dividend_amount_mismatch, dividend_currency_mismatch, period_locked, dividends_not_in_plan and dividend_refused; matching a dividend also needs the dividends.pay permission. See the Dividends guide. For a bill whose open amount is not exactly the bank line, send (bank_transaction_ids and difference may go together; fx_confirm stands alone): difference (account_id or account_code, optional tax_rule_id/tax_code with no VAT, reason bank_fee, fx_difference or short_payment_write_off) to settle the bill in full and post the gap to that account, within the tolerance (the smaller of 25 in the bill's currency and 2 % of what the bill has open); bank_transaction_ids (every line of the payment, this path's included, e.g. a transfer and its separate fee line) when their sum is exactly what is open (a line whose provider target amount is in another currency than the bill's, a EUR transfer that delivered VND for a EUR bill, takes part by its own amount but never carries the difference); or fx_confirm (settles_in_full: true, bill_amount, bill_currency) for a line in another currency with no provider target amount that settles the bill in full. The response then carries settlement with the lines, the difference and the journal the booking will post (per account, base currency, balanced). Refusals name their code in error.code and at the start of the message: amount_mismatch (with expected, actual and difference), tolerance_exceeded, no_difference, not_one_tap_confirmable (with the reason), fx_confirm_mismatch, currency_mismatch, bank_line_already_booked (409, names the booking and the undo operation), bank_line_not_outgoing, bank_line_excluded, bank_line_has_target_amount (with the reason: target_in_bill_currency, target_currency_unknown or difference_on_target_line), bank_lines_on_different_accounts, bank_transaction_ids_duplicate, difference_reason_mismatch, bank_transaction_ids_missing_path_line, difference_needs_open_last_line, unsupported_combination, bill_not_payable, candidate_exchange_rate_missing (a foreign-currency bill with no exchange rate Cybooks can post with: give it the rate of its date with bill.correct and missing_exchange_rate, then match again), difference_account_required, difference_account_unavailable, difference_tax_rule_unavailable, period_locked, journal_preview_unavailable, journal_unbalanced. One bank line that pays several bills (money out) or several invoices (money in) sends candidates instead of candidate_type/candidate_id: [{type: bill|invoice, id, amount}], one kind per line, up to 25, every document in the line's currency, each amount at most what the document has open (less is a part payment), together exactly the bank line, or with a difference block for a small fee or gap (tolerance measured on what the documents take). The preview then carries allocation: each document's amount, open_before, open_after and settles, the difference and the journal. On money in, a gap short of what the invoices take needs write_off_receivables (write_off_not_permitted), and an invoice difference carries no tax rule; a difference while a document stays part paid is refused (difference_with_open_document). amount is a decimal string. Refusals: allocation_sum_mismatch, allocation_exceeds_open_amount, allocation_amount_invalid, candidate_duplicate, candidate_not_found, candidate_not_payable, mixed_candidate_types, candidate_direction_mismatch, currency_mismatch, bank_line_has_target_amount, difference_reason_unavailable, difference_with_open_document, period_locked; invoices need view_invoices. See Settling bills from bank lines. Requires Idempotency-Key (reuse it on the commit) and the reconciliation:action OAuth scope; If-Match with the bank transaction's ETag goes on the commit.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
Body Params

Proposed values used to preview a reconciliation match without persisting changes.

string
enum
Allowed:
string
length ≤ 64
string
enum
Allowed:
string
candidates
array of objects
length between 1 and 25

Or documents in the line's currency, amounts above zero, netting to it unless difference is sent: money in, invoice/vendor_credit add, bill/credit_note subtract; money out reversed. Mixing kinds: new Reconcile only.

candidates
bank_transaction_ids
array of strings
length between 1 and 10

Bills only: every line paying the bill (its transfer and fee), this one too, adding up to it unless difference is sent.

bank_transaction_ids
difference
object

Settle in full, the gap (at most the smaller of 25 and 2 % of the open amount) to an account.

fx_confirm
object

Bills only, a line in another currency with no provider target: echo the preview's bill amount and currency.

Headers
string
required
length ≤ 191

Required operation-specific request key. This requirement does not imply durable public API response replay.

Responses

Language
Credentials
OAuth2
Missing 1 required scope
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
*/*