# Get a financial instrument by ID (v3)

Retrieves one financial instrument associated with the specified identity.
In the current release, one instrument is retrieved at most because only a single instrument is allowed per identity.

Endpoint: GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
Version: 2026.03
Security: Bearer

## Path parameters:

  - `identity-id` (string, required)
    Unique identifier of the identity whose instruments you want to list.
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

  - `financial-instrument-id` (string, required)
    The ID of the financial instrument of the identity.
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

## Query parameters:

  - `version` (string)
    Version of the identity
    Example: "2"

  - `expand-identity` (boolean)
    Optional parameter to expand the financial instrument details.
If set to true, the details about the identity will be included in the response.
    Example: true

## Response 200 fields (application/json):

  - `financialInstrument` (object, required)
    Request to create a new financial instrument for an identity.

  - `financialInstrument.usAch` (object)
    Rails: RTP, ACH

Rail Definitions:

RTP:
  - Availability: 24/7/365
  - Limit: $5,000,000
  - Settlement: <5 minutes
  - Cut-off time: None
  - Banking holidays: Not applicable

ACH:
  - Availability: Business days only
  - Limit: $1,000,000
  - Settlement: Same-day
  - Cut-off time: 3:00 PM EST
  - Banking holidays: U.S. banking holidays apply

Routing Evaluation Order:

  1. RTP
     - Conditions: beneficiary account is RTP-addressable AND amount ≤ $5,000,000
  2. ACH
     - Conditions: otherwise applicable

  - `financialInstrument.usAch.bankName` (string, required)
    The name of the identity's bank

  - `financialInstrument.usAch.bankRoutingNumber` (string, required)
    The identity's bank routing number

  - `financialInstrument.usAch.accountNumber` (string, required)
    The identity's account number into which the funds must be credited

  - `financialInstrument.usAch.accountType` (string, required)
    The identity’s account type.

- CHECKING — Checking account  
- SAVINGS — Savings account

  - `financialInstrument.usFedwire` (object)
    Rails: FEDWIRE

Rail Definitions:

FEDWIRE:
  - Availability: U.S. business days and operating hours.
  - Limit: No limit
  - Settlement: Real-time gross settlement (typically within minutes).
  - Cut-off time: 5:00 p.m. ET; transfers submitted after cut-off queue for next business day.
  - Banking holidays: Follows the Federal Reserve holiday schedule.

  - `financialInstrument.usFedwire.bankName` (string, required)
    The name of the identity's bank.

  - `financialInstrument.usFedwire.bankRoutingNumber` (string, required)
    9-digit ABA Routing Transit Number (RTN) of the beneficiary’s bank.

  - `financialInstrument.usFedwire.accountNumber` (string, required)
    The identity's account number to be credited.

  - `financialInstrument.mxSpei` (object)
    Rails: SPEI

Rail Definitions:

SPEI:
- Availability: 24/7/365
- Limit: None
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

Routing Evaluation Order: Not applicable

  - `financialInstrument.mxSpei.clabe` (string, required)
    The identity's CLABE account identification code

  - `financialInstrument.euSepa` (object)
    Rails: SCT Inst, SCT

Rail Definitions:

SCT Inst:
- Availability: 24/7/365
- Limit: €100,000 (bank-dependent)
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

SCT:
- Availability: Business days only
- Limit: No limit
- Settlement: T+2 to T+5 
- Cut-off time: 3:00PM GMT/BST
- Banking holidays: TARGET2 holidays apply

Routing Evaluation Order:

  1. SCT Inst  
     - Conditions: beneficiary account is SCT Inst-addressable AND amount ≤ €100,000
  2. SCT  
     - Conditions: otherwise applicable

  - `financialInstrument.euSepa.iban` (string, required)
    The International Bank Account Number (IBAN) of the identity's account

  - `financialInstrument.gbFps` (object)
    Rails: FPS, CHAPS

Rail Definitions:

FPS:
- Availability: 24/7/365
- Limit: £1,000,000
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

CHAPS:
- Availability: Business days only
- Limit: No limit
- Settlement: Same-day
- Cut-off time: Typically 5:00 PM GMT/BST (bank-dependent)
- Banking holidays: UK banking holidays apply

Routing Evaluation Order:
  1. FPS  
     - Conditions: beneficiary account is FPS-addressable AND amount ≤ £1,000,000
  2. CHAPS  
     - Conditions: otherwise applicable

  - `financialInstrument.gbFps.sortCode` (string, required)
    The sort code of the identity's bank account

  - `financialInstrument.gbFps.accountNumber` (string, required)
    The account number of the identity's bank account

  - `financialInstrument.africaBankPayout` (object)
    Rails: Bank Payout

Rail Definitions:

Bank Payout:
- Availability: Country-dependant
- Limit:
  - Ghana: ₵100,000
  - Nigeria: ₦5,000,000
  - Zambia: ZK 150,000
  - Uganda: UGX 20,000
  - Rwanda: RWF 10,000,000
  - South Africa: R 300,000
- Settlement: Real time to 48 hours
- Cut-off time: Real time
- Banking holidays: Country specific banking holidays apply
- Routing Evaluation Order: Not applicable

  - `financialInstrument.africaBankPayout.bankCode` (string, required)
    The bank code of the identity's bank

  - `financialInstrument.africaBankPayout.accountNumber` (string, required)
    The identity's account number associated with the Account Identification Scheme

  - `financialInstrument.africaBankPayout.country` (string, required)
    The country of the identity’s bank, using the Alpha-2 code as defined in ISO 3166-1.  
Allowed values are:

- GH  
- NG  
- RW  
- UG  
- ZA  
- ZM
    Example: "NG"

  - `financialInstrument.brPix` (object)
    Rails: PIX

Rail Definitions:

PIX:
- Availability: 24/7/365
- Limit: No limit
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

Routing Evaluation Order: Not applicable

  - `financialInstrument.brPix.bankCode` (string, required)
    The code of the identity's bank (BICFI code)

  - `financialInstrument.brPix.branchNumber` (string, required)
    The identity's bank branch number

  - `financialInstrument.brPix.pixKey` (string, required)
    The identity's PIX key, which can be an email, phone number, or a hash

  - `financialInstrument.brPix.pixKeyType` (string, required)
    The type of PIX key used by the identity.

- CPF  
- CNPJ  
- EMAIL  
- PHONE  
- EVP

  - `financialInstrument.coPse` (object)
    Rails: PSE

Rail Definitions:

PSE:
- Availability: Business days and banking hours only
- Limit: None
- Settlement: 
	- Major banks (Bancolombia, Davivienda, Banco de Bogotá, BBVA, Grupo Aval, Nequi): 35–100 min
	- Other banks (via ACH): Same-day or T+1 depending on cutoff
- Cut-off time: 3PM COT
- Banking holidays: Colombia banking holidays apply

Routing Evaluation Order: Not applicable

  - `financialInstrument.coPse.bankCode` (string, required)
    The identity's bank identifier code

  - `financialInstrument.coPse.accountType` (string, required)
    The type of account associated with the identity.

- CURRENT  
- SAVINGS

  - `financialInstrument.brTed` (object)
    Rails: TED

Rail Definitions:

TED:
- Availability: Business days only
- Limit: No limit
- Settlement: Same-day
- Cut-off time: ~5:00 PM BRT 
- Banking holidays: Brazil banking holidays apply

Routing Evaluation Order: Not applicable

  - `financialInstrument.brTed.branchNumber` (string, required)
    The branch number of the identity's bank account

  - `financialInstrument.brTed.accountType` (string, required)
    The identity's account type (Savings, Checking etc.):
    * CHECKING: Checking account
    * SAVINGS: Savings account
    Example: "SAVINGS"

  - `financialInstrument.caEft` (object)
    Rails: EFT

Rail Definitions:

EFT:
- Availability: Business days only
- Limit: CAD 1,000,000
- Settlement: T+1
- Cut-off time: ~4:30 PM EST
- Banking holidays: Canadian banking holidays apply

Routing Evaluation Order: Not applicable

  - `financialInstrument.caEft.institutionNumber` (string, required)
    The institution number of the identity's bank

  - `financialInstrument.caEft.transitNumber` (string, required)
    The transit number of the identity's bank account

  - `financialInstrument.currency` (string, required)
    The 3-letter ISO currency code of the financial instrument.
    Example: "MXN"

  - `financialInstrument.label` (string)
    A user-defined label for the financial instrument.
    Example: "mexico bank account"

  - `financialInstrument.financialInstrumentType` (string, required)
    The type of financial instrument or payment rail used for executing the transaction.
This determines the structure and validation of account details required for the payout.
    Example: "BR_PIX"

  - `financialInstrument.country` (string)
    The country of the financial instrument.
    Example: "MX"

  - `financialInstrument.financialInstrumentId` (string)
    The unique identifier of the financial instrument.
    Example: "3fc74743-e7f3-414a-9fcf-eb8c1d52356a"

  - `financialInstrument.createdAt` (string)
    The time at which the financial instrument was created
    Example: "2023-11-02T18:26:00.000Z"

  - `financialInstrument.updatedAt` (string)
    The time at which the financial instrument was last updated
    Example: "2023-11-03T18:26:00.000Z"

  - `identity` (object)

  - `identity.identityId` (string)
    Server-generated unique identifier of the identity.
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

  - `identity.identityState` (string)
    The state of the identity.
    Example: "ACTIVE"

  - `identity.nickName` (string)
    Optional human-readable alias set by the client.
    Example: "nickName"

  - `identity.tags` (array)
    Optional labels used to categorize or filter identities.
    Example: ["tag1"]

  - `identity.validatePayoutRails` (array)
    List of payout methods where this identity is considered valid. Use this to indicate which payout methods (for example, US_ACH, EU_SEPA) the identity can be used with in payments.
    Example: ["BR_PIX"]

  - `identity.version` (string)
    Sequential version number. Each successful PUT creates a higher version.
    Example: 2

  - `identity.schemaVersion` (string)
    Schema version used to validate this identity, for example 1.0.0.
    Example: "1.0.0"

  - `identity.createdAt` (string)
    RFC 3339 timestamp when the identity was created.
    Example: "2023-11-02T18:26:00.000Z"

  - `identity.updatedAt` (string)
    RFC 3339 timestamp when the identity was last updated.
    Example: "2023-11-03T18:26:00.000Z"

  - `identity.identityType` (string, required)
    The type of the identity
    Example: "BUSINESS"

  - `identity.paymentRole` (string, required)
    The payment role of the identity
    Example: "BENEFICIARY"

  - `identity.internalId` (string)
    Client-provided unique identifier for this identity. Required for Originators, optional for Beneficiaries.
    Example: "customer-12345-uuid"

  - `identity.business` (object)
    PII data to support business and institutional identities

  - `identity.business.businessName` (string, required)
    Business Legal Name
    Example: "Widgets Org"

  - `identity.business.address` (object, required)
    Holds general information about the business

  - `identity.business.address.streetAddress` (array, required)
    Allows the street address of the business to be held
    Example: ["123 Example St. Boston, MA"]

  - `identity.business.address.country` (string, required)
    Allows the country of the business to be held. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.
    Example: "US"

  - `identity.business.address.city` (string, required)
    City
    Example: "Boston"

  - `identity.business.address.stateOrProvince` (string, required)
    Information that locates and identifies the state / county for the individual, as defined by postal services.
    Example: "Massachusetts"

  - `identity.business.address.postalCode` (string, required)
    Postal code for the business
    Example: "12345"

  - `identity.business.email` (string)
    Address for electronic mail (e-mail).
    Example: "fake@example.com"

  - `identity.business.phone` (string)
    Phone Number
    Example: 1234567890

  - `identity.business.registration` (array)
    Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.

  - `identity.business.registration.number` (string, required)
    The unique identifier of the organization
    Example: "123ABC"

  - `identity.business.registration.type` (string, required)
    Type of business identification document. Accepted values are:

- INCORPORATION_CERTIFICATE — Certificate of Incorporation Number  
- TAX_ID — Tax Identification Number
    Example: "INCORPORATION_CERTIFICATE"

  - `identity.business.incorporationCountry` (string)
    Information that locates and identifies the country, as defined by postal services where the organization was incorporated. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
    Example: "US"

  - `identity.individual` (object)
    Data for an individual

  - `identity.individual.firstName` (string, required)
    First name of the individual
    Example: "John"

  - `identity.individual.lastName` (string, required)
    Last name of the individual
    Example: "Smith"

  - `identity.individual.address` (object, required)
    Holds general information about the individual

  - `identity.individual.address.streetAddress` (array, required)
    Allows the street address of the individual to be held
    Example: ["123 Example St. Boston, MA"]

  - `identity.individual.address.country` (string, required)
    Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.
    Example: "US"

  - `identity.individual.address.stateOrProvince` (string, required)
    Information that locates and identifies the state / county for the party, as defined by postal services
    Example: "Massachusetts"

  - `identity.individual.address.postalCode` (string, required)
    Postal code for the individual's address
    Example: "12345"

  - `identity.individual.identityDocuments` (array)
    Gathers identifying documentation

  - `identity.individual.identityDocuments.idNumber` (string, required)
    Identification Number.
    Example: "123ABC"

  - `identity.individual.identityDocuments.idType` (string, required)
    The type of identification document used to identify the identity.

- ALIEN_REGISTRATION — Alien Registration Number  
- CUSTOMER_ID — Customer Identification Number  
- DRIVERS_LICENSE — Driver’s License Number  
- PASSPORT — Passport Number  
- EMPLOYEE_ID — Employee ID  
- NATIONAL_ID_NUMBER — National ID  
- SSN — Social Security Number  
- TAX_ID — Tax ID

  - `identity.individual.dateOfBirth` (string)
    Date of Birth.
    Example: "2001-01-24"

  - `identity.individual.countryOfBirth` (string)
    Country of Birth. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.
    Example: "US"

  - `identity.individual.citizenship` (string)
    Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
    Example: "US"

  - `identity.individual.gender` (string)
    Gender of the identity.

- MALE — Male identity  
- FEMALE — Female identity  
- OTHER — Other identity

## Response 400 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"

## Response 404 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"

## Response 500 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"