The ACH Object

Lead creates an ACH object for every entry your program sends and every entry it receives. You create outgoing entries with POST /v2/ach and read them with GET /v2/ach and GET /v2/ach/{ach_id}. Returns, dishonored returns, contested returns, reversals, rejections, and corrections are recorded on the same object. POST /v2/ach requires an Idempotency-Key header. See Idempotency. This example is an incoming debit. A gym pulled $50 from an Acme customer’s account number, and the entry posted. The customer told Acme the debit wasn’t authorized, so Acme returned it with POST /v2/ach/{ach_id}/return and return code R10. The return posted, and the entry is now returned.

{
  "id": "ach_3KrLe9Wc4OlYa7nZsU5xF2bR8t",
  "account_number_id": "account_number_2fTZ4St5HSJnxzv7jdevxQnev3U",
  "core_balance_id": "core_balance_2xYw9Kn3Jp7QuS2lY5mAbC0dE4f",
  "core_transaction_id": "core_transaction_2pR8Jt1Wc4OlYa7nZsU5xF2b",
  "created_at": "2026-10-08T14:11:05Z",
  "updated_at": "2026-10-10T12:30:44Z",
  "status": "returned",
  "amount": 5000,
  "currency_code": "USD",
  "direction": "incoming",
  "delivery_type": null,
  "transaction_type": "debit",
  "sec_code": "PPD",
  "statement_descriptor": "PEAK FITNESS",
  "record_details": {
    "transaction_code": "checking_debit",
    "company_name": "Peak Fitness LLC",
    "company_id": "9876543210",
    "company_discretionary_data": null,
    "effective_date": null,
    "settlement_date": "2026-10-09",
    "individual_id": "MBR-77102",
    "receiver_name": "Jordan Smith",
    "descriptive_date": null,
    "additional_information": null,
    "trace_number": "123456780000131"
  },
  "counterparty": {
    "name": "Peak Fitness LLC",
    "account_number": null,
    "routing_number": "123456789",
    "account_type": null
  },
  "returns": [
    {
      "type": "return",
      "status": "posted",
      "return_code": "R10",
      "reason": "Customer advises not authorized",
      "details": null,
      "trace_number": "123456780000512",
      "core_transaction_id": "core_transaction_2pS9Ku2Xd5PmZb8oAtV6yG3c"
    }
  ],
  "reversal": null,
  "rejection": null,
  "correction": null,
  "iat_details": null,
  "metadata": {}
}

The core balance has two core transactions: the debit from when the entry posted, linked at the top level, and the credit from when the return posted, linked on the returns[] entry.

Fields

The table lists each field on the object.

Field	Type	Description
`id`	string	Unique identifier, prefixed `ach_`.
`account_number_id`	string	The account number the entry is on. For outgoing entries, the one you named on create. For incoming entries, the one Lead matched from the entry.
`core_balance_id`	string	The core balance the entry posts to, resolved from the account number. For an account number on a user deposit balance, this is the FBO core balance behind it.
`core_transaction_id`	string or null	The core transaction for the original posting. `null` until the entry posts, and `null` on entries whose posting predates core transaction capture. Each return has its own in `returns[]`.
`created_at`, `updated_at`	timestamp	RFC 3339, UTC.
`status`	enum	See ACH Statuses.
`amount`	integer	Amount as an integer in minor units. 5000 is $50.00.
`currency_code`	string	ISO 4217. `USD`.
`direction`	enum	`outgoing` for entries you originate. `incoming` for entries received from another bank.
`delivery_type`	enum	`same_business_day` or `next_business_day`. You set it on outgoing entries. See ACH timing and availability.
`transaction_type`	enum	`credit` pushes funds to the counterparty. `debit` pulls funds from the counterparty.
`sec_code`	enum	`CCD`, `PPD`, `TEL`, `WEB`, `CIE`, or, on incoming entries only, `IAT`.
`statement_descriptor`	string	The description that appears on the counterparty’s statement. On a reversing entry Lead sets it to `REVERSAL`.
`record_details`	object	Fields from the Nacha entry and batch records. See The record details block.
`counterparty`	object	The other party’s bank account. See The counterparty block.
`returns`	array of objects	Every return, dishonored return, and contested return on the entry, oldest first. Empty when there are none. See The returns block.
`reversal`	object or null	Set on both sides of a reversal: the entry that was reversed and the entry that reversed it. See The reversal block.
`rejection`	object or null	Set when `status` is `rejected`. See The rejection block.
`correction`	object or null	Set when a Notification of Change has arrived for the entry. See The correction block.
`iat_details`	object or null	Set on incoming `IAT` entries only. See The IAT details block.
`metadata`	object	Key-value pairs for your own use. Lead doesn’t read them. Update with `PATCH`.

The record details block

The table lists the fields in the record details block.

Field	Type	Description
`transaction_code`	enum	The Nacha transaction code as a named value, for example `checking_credit` or `savings_debit`.
`company_name`	string	The originating company. Outgoing: set from the originator the account number sends under. Incoming: as received.
`company_id`	string	The originating company’s ACH company ID. Outgoing: set from the originator. Incoming: as received.
`company_discretionary_data`	string or null	Free text from the sender on incoming entries.
`effective_date`	date	Outgoing: the date Lead sets from `delivery_type`. Incoming: as received.
`settlement_date`	date	The date by which funds must be posted to the counterparty’s account.
`individual_id`	string or null	Your identifier for the receiver, if you sent one.
`receiver_name`	string or null	The receiver’s name as it appears in the entry.
`descriptive_date`	string or null	The descriptive date you sent, if any.
`additional_information`	string or null	The addenda text on the entry. This field mirrors the Nacha addenda record.
`trace_number`	string	The trace number assigned by the originating bank. Outgoing: generated by Lead at submission. Incoming: as received.

The counterparty block

The table lists the fields in the counterparty block.

Field	Type	Description
`name`	string	The counterparty’s name.
`account_number`	string	The counterparty’s account number.
`routing_number`	string	The counterparty’s routing number.
`account_type`	enum	`checking` or `savings`.

The returns block

Each entry in returns[] is one return event on the ACH. A return, a dishonored return, and a contested return are all returns. The return_code tells you which.

Field	Type	Description
`type`	enum	`return`, `dishonored_return`, or `contested_return`. Determined by `return_code`.
`status`	enum	The status of this return event. Uses the same values as the ACH `status`. A return Lead declined after review is `rejected` here while the parent entry stays `posted`.
`return_code`	string	The Nacha return reason code, for example `R01`. `R61` to `R70` are dishonored returns. `R71` to `R77` are contested returns.
`reason`	string	Short description of the return code.
`details`	string or null	Free text from the return addenda, when the returning party provided it.
`trace_number`	string or null	The trace number of the return entry, assigned by the bank that sent it.
`core_transaction_id`	string or null	The core transaction this return posted. `null` until it posts, and `null` on a return that was declined.

The reversal block

The table lists the fields in the reversal block.

Field	Type	Description
`reason`	enum	Why the entry was reversed: `duplicate`, `receiver_incorrect`, `amount_incorrect`, `debit_too_early`, or `credit_too_late`.
`linked_ach_id`	string	On the original entry, the ID of the reversing entry. On the reversing entry, the ID of the original.

POST /v2/ach/{ach_id}/reverse takes reason with the same values and creates a new outgoing entry in the opposite direction for the same amount. There is no free-text field, because Nacha reversals don’t have one.

The rejection block

The table lists the fields in the rejection block.

Field	Type	Description
`reason`	enum	Why Lead rejected the entry. A closed set of values owned by Lead, with `other` for conditions that fit nothing else.
`details`	string or null	Free text about the rejection, for example which account number was inactive.

The correction block

Set when the counterparty’s bank sends a Notification of Change. Update your counterparty records from it before your next entry to that counterparty.

Field	Type	Description
`account_number`	string or null	The corrected account number.
`routing_number`	string or null	The corrected routing number.
`account_type`	enum or null	The corrected account type, `checking` or `savings`.

The IAT details block

Set on incoming IAT entries only. Lead doesn’t originate IAT.

Field	Type	Description
`transaction_type_code`	enum	The IAT transaction type, for example `business`.
`destination_country`	string	ISO 3166 alpha-2.
`originator_currency_code`, `destination_currency_code`	string	ISO 4217.
`foreign_trace_number`	string or null	The trace number assigned by the foreign gateway.
`additional_information`	string or null	The IAT addenda text. This field mirrors the Nacha addenda record.
`originator`, `receiver`	object	Name and address of each party as they appear in the IAT addenda.
`originating_financial_institution`, `receiving_financial_institution`	object	Name, identifier type, identifier code, and branch country of each bank.
`foreign_correspondent_banks`	array of objects	Any correspondent banks in the chain, each with name, identifier type, identifier code, and branch country.

Listing entries

GET /v2/ach returns a list (objects, has_more) sorted newest first. Filters:

Filter	Matches
`account_number_id`	Entries on the account number.
`account_number`	Entries on the account number with that number.
`counterparty_account_number`	Entries whose counterparty has that account number.
`core_transaction_id`	The entry whose top-level `core_transaction_id` or any `returns[].core_transaction_id` equals the value. This is how you go from a core transaction back to the ACH.
`direction`	`incoming` or `outgoing`.
`status`	One status value.
`transaction_type`	`credit` or `debit`.
`created_at`	Entries created in the range.

Coming from v1

A v2 ACH object replaces the v1 ACH object. Entries created on /v1/ach are readable on /v2/ach. The create request body is unchanged.

v1	v2	Notes
`POST /v1/ach` and sub-paths	`POST /v2/ach` and sub-paths	Same request body.
`account_id` on the response and as a list filter	Removed	Filter by `account_number_id`.
No balance field	`core_balance_id`	Added in v2. The core balance the entry posts to.
No ledger link	`core_transaction_id` at the top level and on each `returns[]` entry	Added in v2. One per posting. `null` until posted.
No `core_transaction_id` filter	`core_transaction_id` list filter	Added in v2. Matches the top level or any return.
`returns[].return_reason`	`returns[].reason`	Renamed. Same content.
`returns[].additional_information`	`returns[].details`	Renamed. Same content.
`reversal.reversal_reason`	`reversal.reason`	Renamed. Same values.
`POST /v1/ach/{ach_id}/reverse` takes `reversal_reason`	`POST /v2/ach/{ach_id}/reverse` takes `reason`	Renamed. Same values.
`rejection.reason` is free text	`rejection.reason` is a closed enum with `other`	Entries rejected on v1 return the mapped value when read on v2. `rejection.details` is unchanged.
`POST /v1/simulate/ach/{ach_id}/incoming_return` takes `return_additional_information`	`POST /v2/simulate/ach/{ach_id}/incoming_return` takes `details`	The value you send comes back as `returns[].details`.
Errors in the v1 shape	Errors in the v2 shape	Same validations.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

The record details block

The counterparty block

The returns block

The reversal block

The rejection block

The correction block

The IAT details block

Listing entries

Coming from v1

​Fields

​The record details block

​The counterparty block

​The returns block

​The reversal block

​The rejection block

​The correction block

​The IAT details block

​Listing entries

​Coming from v1

​Related

Fields

The record details block

The counterparty block

The returns block

The reversal block

The rejection block

The correction block

The IAT details block

Listing entries

Coming from v1

Related