Match bank transactions

Operation ID: matchBankTransactions

Group: Banking › Bank Transactions

Open in the interactive reference

POST /banking/bank-transactions/match

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Matches bank transactions. Name each document by its sfdType and sfdId. The documents must be in the same currency as the bank transactions and total the same amount, to two decimal places.

All the bank transactions must belong to the same bank account and legal entity. Each document must be unmatched and belong to that legal entity. It must also have a line that posts to the bank account's linked chart-of-accounts account, unless journalEntryLineId names the line to use.

A fund transfer is matched on its own. Send it as the only document, with one or both of its legs as the bank transactions. The legs can be on different bank accounts and in different legal entities. Each leg gets its own match, so matches has one item per leg sent. The sending and receiving amounts are each checked against the fund transfer.

To reverse a match, use POST banking/bank-transactions/:id/unmatch.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: matchBankTransactionsInput.

Field Type Required Description
bankTransactionIds array<string> yes The unique identifiers for the bank transactions to match. At least one is required. All of them must belong to the same bank account and legal entity, unless the only document is a fund transfer. A repeated identifier is counted once. Example: ["9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"].
documents array<object> yes The documents to match the bank transactions with. At least one is required, and a fund transfer must be the only document. Example: [{"sfdType":"bankEntryNew","sfdId":"c41d0b58-2e97-4f6a-8d13-7b5e9c204af6"}].
documents[].sfdType any yes The type of document. Accepted values: 'outboundPayment' (an outbound payment), 'customerPayment' (a customer payment), 'manualJournalEntry' (a manual journal entry), 'bankEntryNew' (a bank entry), 'creditCardEntry' (a credit card entry), 'fundTransfer' (a fund transfer), 'payroll' (a payroll detail). One of: "outboundPayment", "customerPayment", "manualJournalEntry", "bankEntryNew", "creditCardEntry", "fundTransfer", "payroll".
documents[].sfdId string yes The unique identifier for the document, of the type in sfdType. For a bank entry, for example, see id on GET banking/bank-entries/:id.
documents[].journalEntryLineId string no The unique identifier for one journal entry line of the document, to match that line only. Omit to match every line of the document that posts to the bank account's linked chart-of-accounts account. Not used for a fund transfer. 
{
  "bankTransactionIds": [
    "9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"
  ],
  "documents": [
    {
      "sfdType": "bankEntryNew",
      "sfdId": "c41d0b58-2e97-4f6a-8d13-7b5e9c204af6"
    }
  ]
}

Response

200 Success

Under data (matchBankTransactionsOutput):

Field Type Required Description
matches array<object> yes The matches created. Usually one. A fund transfer has one for each leg sent. Example: [{"matchId":"e93b7d15-2c48-4a60-9f31-5b7c8d9e0a12","status":"matched","bankTransactionIds":["9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"]}].
matches[].matchId string yes The unique identifier for the match.
matches[].status string yes The status of the match. Possible values: 'matched', 'pending' (a document has no posted journal entry line yet).
matches[].bankTransactionIds array<string> yes The unique identifiers for the bank transactions in this match.
matchedBankTransactionIds array<string> yes The unique identifiers for all the bank transactions matched, in the order sent, with repeats removed. Example: ["9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"].
matchedDocuments array<object> yes The documents matched, with the amount each one contributed. A fund transfer has one item for each leg. Example: [{"sfdType":"bankEntryNew","sfdId":"c41d0b58-2e97-4f6a-8d13-7b5e9c204af6","amount":"1200.00","currency":"USD"}].
matchedDocuments[].sfdType string yes The type of document, as sent.
matchedDocuments[].sfdId string yes The unique identifier for the document, as sent.
matchedDocuments[].amount string yes The amount this document contributed to the match, as a decimal in the bank transaction currency.
matchedDocuments[].currency string yes The currency of amount. Format ISO 4217, for example 'USD'. 
{
  "data": {
    "matches": [
      {
        "matchId": "e93b7d15-2c48-4a60-9f31-5b7c8d9e0a12",
        "status": "matched",
        "bankTransactionIds": [
          "9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"
        ]
      }
    ],
    "matchedBankTransactionIds": [
      "9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"
    ],
    "matchedDocuments": [
      {
        "sfdType": "bankEntryNew",
        "sfdId": "c41d0b58-2e97-4f6a-8d13-7b5e9c204af6",
        "amount": "1200.00",
        "currency": "USD"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
NOT_FOUND 400
ALREADY_MATCHED 400
NO_DOCUMENTS 400
NO_TRANSACTIONS 400
INVALID_DOCUMENT_REFERENCE 400
DOCUMENT_NOT_MATCHABLE 400
MULTIPLE_FUND_TRANSFERS 400
FUND_TRANSFER_MUST_BE_ALONE 400
TOO_MANY_FUND_TRANSFER_TRANSACTIONS 400
ACCOUNT_NOT_IN_RECONCILIATION_BOOK 400
AMOUNT_MISMATCH 400
TRANSACTIONS_SPAN_ACCOUNTS 400
CURRENCY_MISMATCH 400
BEFORE_RECONCILIATION_START_DATE 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses