> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# The Wire Object

> Field-level reference for the V2 Wire object, including parties, agents, amounts, identifiers, charges, returns, and return requests.

Wire transfers move funds between financial institutions through wire payment networks such as Fedwire. Lead creates a wire object for every wire your program sends and every wire it receives, including returns. You create outgoing wires with `POST /v2/wires` and read them with `GET /v2/wires` and `GET /v2/wires/{wire_id}`. Returning a wire you received with `POST /v2/wires/{wire_id}/return` also creates a new outgoing return wire object.

```json theme={null}
{
  "id": "wire_3GxYBvr5Sb5w6gDyzdiDcLW0DCN",
  "account_number_id": "account_number_2fTZ4St5HSJnxzv7jdevxQnev3U",
  "core_transaction_id": "core_transaction_2pQ7Hs9Vb3NkXz6mYrT4wE1a",
  "created_at": "2026-10-07T15:02:11Z",
  "updated_at": "2026-10-07T15:04:38Z",
  "settlement_date": "2026-10-07",
  "direction": "outgoing",
  "type": "transfer",
  "corridor_type": "domestic",
  "status": "posted",
  "amounts": {
    "settlement_amount": 2500000,
    "settlement_currency_code": "USD",
    "instructed_amount": 2500000,
    "instructed_currency_code": "USD",
    "instructed_to_settlement_exchange_rate": "1"
  },
  "debtor": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other",
      "value": "1234567890"
    },
    "address": {
      "line_one": "100 Main Street",
      "town_name": "Kansas City",
      "country_sub_division": "MO",
      "post_code": "64105",
      "country": "US"
    }
  },
  "debtor_agent": {
    "name": "LEAD BK",
    "local_routing_identifier": {
      "scheme": "USABA",
      "value": "101019644"
    }
  },
  "instructing_agent": {
    "name": "LEAD BK",
    "local_routing_identifier": {
      "scheme": "USABA",
      "value": "101019644"
    }
  },
  "instructed_agent": {
    "name": "BK AMER NYC",
    "local_routing_identifier": {
      "scheme": "USABA",
      "value": "026009593"
    }
  },
  "creditor_agent": {
    "name": "BK AMER NYC",
    "local_routing_identifier": {
      "scheme": "USABA",
      "value": "026009593"
    }
  },
  "creditor": {
    "name": "Rivera Consulting LLC",
    "account_identifier": {
      "type": "other",
      "value": "9876543210"
    },
    "address": {
      "line_one": "450 Lexington Avenue",
      "town_name": "New York",
      "country_sub_division": "NY",
      "post_code": "10017",
      "country": "US"
    }
  },
  "initiating_party": {
    "name": "Acme Payments"
  },
  "payment_identifiers": {
    "message_identification": "20261007B1QDRCQR000401",
    "end_to_end_identification": "INV-12345",
    "uetr": "1f625168-8786-11f1-9605-82d7a3dd42cb",
    "instruction_identification": "instr-0042"
  },
  "remittance_details": {
    "message_to_creditor": "Invoice 12345",
    "transfer_purpose": {
      "type": "invoice_payment"
    }
  },
  "metadata": {
    "internal_reference": "ref_12345"
  }
}
```

## Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier of the wire object. |
| `account_number_id` | string | The ID of the Lead Bank Account Number object. |
| `core_transaction_id` | string, nullable | Linked core transaction ID associated with the wire. |
| `created_at` | timestamp | ISO 8601 format timestamp representing when the wire object was created. |
| `updated_at` | timestamp | ISO 8601 format timestamp representing when the wire object was last updated. |
| `settlement_date` | date | The ISO-8601 datestamp indicating the wire settlement date based on Fedwire's business day definition. |
| `direction` | enum | Who is initiating the transaction. outgoing: You are sending a wire transaction to a counterparty. incoming: You are receiving a wire transaction from a counterparty. |
| `type` | enum | Indicates the type of wire message that the object represents. |
| `corridor_type` | enum | Indicates whether the wire is domestic or international. |
| `status` | enum | `created`, `scheduled`, `processing`, `posted`, `under_review`, `rejected`, `canceled`, `cancel_pending`. See Wire Statuses. |
| `amounts` | object | See [The amounts block](#the-amounts-block). |
| `debtor` | object | Details of the debtor sending funds. See [The party block](#the-party-block). |
| `debtor_agent` | object | Details of the financial institution where the debtor holds their account. This object may be absent if the instructing agent does not provide this information. See [The agent block](#the-agent-block). |
| `instructing_agent` | object | The financial institution that transmitted the payment through Fedwire. In some cases, this may differ from the bank where the account is held. This object will always be populated. See [The agent block](#the-agent-block). |
| `instructed_agent` | object | The financial institution that received the payment through Fedwire. This may not always be the bank where the recipient's account is held. This object will always be populated. See [The agent block](#the-agent-block). |
| `creditor_agent` | object | Details of the financial institution where the creditor holds their account. This object may be absent if the instructing agent does not provide this information. See [The agent block](#the-agent-block). |
| `creditor` | object | Details of the creditor receiving funds. See [The party block](#the-party-block). |
| `initiating_party` | object | Details of the party that initiates the payment on behalf of the debtor. For outgoing wires, automatically populated with your organization's name. For incoming wires, populated from the ISO initiating party when provided by the sending institution. See [The party block](#the-party-block). |
| `ultimate_debtor` | object | The ultimate party on whose behalf the payment is made, if different from the debtor. See [The party block](#the-party-block). |
| `ultimate_creditor` | object | The ultimate party to which the payment is intended, if different from the creditor. See [The party block](#the-party-block). |
| `other_agents` | object | Details of any other agents involved in the wire transfer. See [The other agents block](#the-other-agents-block). |
| `payment_identifiers` | object | Wire payment identifiers. See [The payment identifiers block](#the-payment-identifiers-block). |
| `remittance_details` | object | Wire remittance details. See [The remittance details block](#the-remittance-details-block). |
| `charges` | object | Information about any charges assessed during wire transfer processing. See [The charges block](#the-charges-block). |
| `related_wires` | object | Related wire objects. See [The related wires block](#the-related-wires-block). |
| `return_requests` | array of objects | Return requests associated with the wire, sorted oldest first. Empty when no return requests exist. See [The return requests block](#the-return-requests-block). |
| `return` | object | Return details associated with a returned wire. See [The return block](#the-return-block). |
| `rejection` | object | See [The rejection block](#the-rejection-block). |
| `metadata` | object | A set of key-value pairs that can be used to store additional information related to this object. |

## The party block

Used by `debtor`, `creditor`, `initiating_party`, `ultimate_debtor`, and `ultimate_creditor`.

| Field | Type | Description |
| - | - | - |
| `name` | string | Name of the party. |
| `account_identifier` | object | Object representing the account that the party holds at its financial institution |
| `account_identifier.type` | enum | The type of account identifier. |
| `account_identifier.value` | string | The value of the account identifier where the wire is being sent. For U.S. domestic wires, this should always be the full account number. |
| `address` | object | Address of the party. See [The address block](#the-address-block). |

## The address block

Used by every party and every agent.

| Field | Type | Description |
| - | - | - |
| `department` | string | Identification of a division of a large organization or building. |
| `sub_department` | string | Identification of a sub-division of a large organization or building. |
| `street_name` | string | Name of a street or thoroughfare. |
| `building_number` | string | Number that identifies the position of a building on a street. |
| `building_name` | string | Name of the building or house. |
| `floor` | string | Floor or storey within a building. |
| `post_box` | string | Numbered box in a post office, assigned to a person or organisation, where letters are kept until called for. |
| `room` | string | Building room number. |
| `post_code` | string | Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. |
| `town_name` | string | Name of a built-up area, with defined boundaries, and a local government. |
| `town_location_name` | string | Specific location name within the town. Note that this field is not commonly used for US-based addresses. |
| `district_name` | string | Identifies a subdivision within a country sub-division. Note that this field is not commonly used for US-based addresses. |
| `country_sub_division` | string | Identifies a subdivision of a country such as state, region, county. |
| `country` | string | ISO 3166, alpha-2 code representing a nation with its own government. |
| `line_one` | string | Line one address of the party represented in an unstructured format. |
| `line_two` | string | Line two address of the party represented in an unstructured format. |
| `line_three` | string | Line three address of the party represented in an unstructured format. |

## The agent block

`instructing_agent` and `instructed_agent` carry every field below except `address`.

| Field | Type | Description |
| - | - | - |
| `business_identifier_code` | string | Business Identifier Code (BIC) of the financial institution. |
| `name` | string | Name of the financial institution. |
| `local_routing_identifier` | object | Routing or transit code used by the financial institution's local clearing system for international wire transfers, such as a sort code, IFSC, or BSB. |
| `local_routing_identifier.scheme` | string | The scheme or type of the local routing identifier (e.g. GBDSC for UK sort codes). |
| `local_routing_identifier.value` | string | The value of the local routing identifier. |
| `address` | object | Address of the financial institution. See [The address block](#the-address-block). |

## The amounts block

| Field | Type | Description |
| - | - | - |
| `settlement_amount` | integer | Amount of money that moved across the Fedwire network from the instructing agent to the instructed agent. |
| `settlement_currency_code` | enum | The currency code of the settlement amount. |
| `instructed_amount` | integer | Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. |
| `instructed_currency_code` | string | The currency code of the instructed amount. A three-letter currency code as defined in ISO 4217. |
| `instructed_to_settlement_exchange_rate` | string | Factor used to convert an amount from the instructed currency to the settlement currency. |

## The other agents block

Each field uses [The agent block](#the-agent-block).

| Field | Type | Description |
| - | - | - |
| `previous_instructing_agent_one` | object | Financial institution sitting in the payment chain between the Debtor Agent and the Instructing Agent. |
| `previous_instructing_agent_two` | object | Financial institution sitting in the payment chain between the Debtor Agent and the Instructing Agent. |
| `previous_instructing_agent_three` | object | Financial institution sitting in the payment chain between the Debtor Agent and the Instructing Agent. |
| `intermediary_agent_one` | object | Financial institution sitting in the payment chain between the Creditor Agent and the Instructed Agent. |
| `intermediary_agent_two` | object | Financial institution sitting in the payment chain between the Creditor Agent and the Instructed Agent. |
| `intermediary_agent_three` | object | Financial institution sitting in the payment chain between the Creditor Agent and the Instructed Agent. |

## The payment identifiers block

| Field | Type | Description |
| - | - | - |
| `message_identification` | string | Point to point reference, as assigned by the instructing party, and sent to the next party in the chain to unambiguously identify the message. Formerly known as the IMAD. |
| `end_to_end_identification` | string | Unique identification that the initiating party in a wire message can use to unambiguously identify the transaction. This is passed through, unchanged, throughout the entire wire chain. |
| `uetr` | string | Universally unique identifier to provide an end-to-end reference of a payment transaction. |
| `instruction_identification` | string | Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. |
| `return_identification` | string | Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the returned transaction. |

## The remittance details block

| Field | Type | Description |
| - | - | - |
| `payment_notification` | string | Information about the payment notification. |
| `message_to_creditor` | string | Information intended specifically for the creditor. |
| `message_to_receiving_fi` | string | Information intended specifically for the receiving financial institution. |
| `fi_to_fi_message` | string | Financial institution to financial institution information, most often used by a financial institution to explain additional detail of a wire. |
| `transfer_purpose` | object | The purpose or reason for which the wire is being sent. |
| `transfer_purpose.type` | enum | Code representing the purpose of the transfer. |
| `transfer_purpose.other_details` | string | Free-formatted text for wire sender if `other` is selected for `type`. |

## The charges block

| Field | Type | Description |
| - | - | - |
| `charge_bearer` | enum | Specifies which party bears the charges for the wire transfer. |
| `breakdown` | array of objects | Itemized list of charges assessed during wire transfer processing. |
| `breakdown[].amount` | string | The amount of the charge. |
| `breakdown[].currency_code` | string | ISO 4217 three-letter currency code for the charge. |
| `breakdown[].charging_agent` | object | Wire agent information. See [The agent block](#the-agent-block). |

## The related wires block

| Field | Type | Description |
| - | - | - |
| `original_wire_id` | string | If this wire is a return wire (i.e., returning a wire previously received), this field will provide the preceding wire's identifier (wire\_id). |
| `return_wire_ids` | array of strings | If this wire has been returned by any following wires, you can find the returning wire id(s) here. |

## The return requests block

A return request asks for the funds on a wire to be sent back. You can send one on a wire you sent; the counterparty can send you one on a wire you received. The underlying ISO 20022 message is a camt.056. See Return Requests.

| Field | Type | Description |
| - | - | - |
| `created_at` | timestamp | ISO 8601 timestamp when the return request was created. |
| `status` | enum | Current status of the return request. - For incoming return requests: `response_needed`, `accepted`, `rejected`. - For outgoing return requests: `pending`, `accepted`, `rejected`. `accepted` and `rejected` are terminal. |
| `reason` | enum | Reason for the return request. |
| `details` | string | Details of the reason for the return request including the 4-character ISO code when possible. |
| `deadline` | timestamp | The deadline by which a final response to the return request is expected. For incoming return requests, you must respond by 11:30PM ET on the 10th business day. If you do not respond, we will respond on your behalf with a rejection at midnight. For outgoing return requests, this field will not be populated. |
| `resolution` | object | Resolution details. Populated once the return request reaches a terminal status (`accepted` or `rejected`). |
| `resolution.resolved_at` | timestamp | ISO 8601 timestamp when the resolution occurred. |
| `resolution.resolved_by` | enum | The party that resolved the return request. - `lead` — Resolved by Lead through validation or manual review. - `client` — Resolved by the partner via API or by initiating a return. - `counterparty` — Resolved by the counterparty financial institution's response. Outgoing return requests only. |
| `resolution.rejection_reason` | enum | Reason the return request was rejected. |
| `resolution.rejection_details` | string | Free-text explanation of the rejection. For incoming responses, includes the original 4-character ISO code. |

## The return block

Present when the wire is a return (`type` is `return`).

| Field | Type | Description |
| - | - | - |
| `reason` | enum | If the wire is a return, this field indicates the reason for the return. When the return originates from a counterparty with an unmapped ISO code, this field is set to `other` and the raw ISO code is included in `additional_information` in the format `"ISO Code: <code>; <details>"`. |
| `additional_information` | string | If the return reason is `narrative`, an accompanying free-form explanation is required and will appear here. When the reason is `other`, this is populated with the raw ISO code in the format `"ISO Code: <code>; <details>"`. For other reasons, participants may optionally send additional information as well. |

## The rejection block

Present when the wire was rejected (`status` is `rejected`).

| Field | Type | Description |
| - | - | - |
| `reason` | enum | If a wire is rejected, this field will indicate the reason for the rejection. |
| `additional_information` | string | If the rejection reason is "narrative", then an accompanying free-form explanation is required and will appear here. For other reasons, participants may optionally send additional information as well. |
| `message_identification` | string | If Lead rejected an incoming wire on your behalf, this field contains the message identification of the return wire that we sent. Formerly known as the IMAD. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.