The Wire Object

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.

{
  "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.
`debtor`	object	Details of the debtor sending funds. See 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.
`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.
`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.
`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.
`creditor`	object	Details of the creditor receiving funds. See 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.
`ultimate_debtor`	object	The ultimate party on whose behalf the payment is made, if different from the debtor. See The party block.
`ultimate_creditor`	object	The ultimate party to which the payment is intended, if different from the creditor. See The party block.
`other_agents`	object	Details of any other agents involved in the wire transfer. See The other agents block.
`payment_identifiers`	object	Wire payment identifiers. See The payment identifiers block.
`remittance_details`	object	Wire remittance details. See The remittance details block.
`charges`	object	Information about any charges assessed during wire transfer processing. See The charges block.
`related_wires`	object	Related wire objects. See 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.
`return`	object	Return details associated with a returned wire. See The return block.
`rejection`	object	See 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

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 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.

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.

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.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

The party block

The address block

The agent block

The amounts block

The other agents block

The payment identifiers block

The remittance details block

The charges block

The return requests block

The return block

The rejection block

​Fields

​The party block

​The address block

​The agent block

​The amounts block

​The other agents block

​The payment identifiers block

​The remittance details block

​The charges block

​The related wires block

​The return requests block

​The return block

​The rejection block

Fields

The party block

The address block

The agent block

The amounts block

The other agents block

The payment identifiers block

The remittance details block

The charges block

The related wires block

The return requests block

The return block

The rejection block