Modern Treasury ExternalAccount API
The ExternalAccount API from Modern Treasury — 4 operation(s) for externalaccount.
OpenAPI Specification
openapi: 3.0.1
info:
title: Modern Treasury AccountCapability ExternalAccount API
version: v1
contact:
name: Modern Treasury Engineering Team
url: https://moderntreasury.com
description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: ExternalAccount
paths:
/api/external_accounts/{id}/verify:
post:
summary: verify external account
tags:
- ExternalAccount
operationId: verifyExternalAccount
security:
- basic_auth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: This key should be something unique, preferably something like an UUID.
schema:
type: string
- name: id
in: path
schema:
type: string
description: external account id
required: true
responses:
'200':
description: successful
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/external_account'
- $ref: '#/components/schemas/external_account_verification_attempt'
'422':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/external_account_verify_request'
/api/external_accounts/{id}/complete_verification:
post:
summary: complete verification of external account
tags:
- ExternalAccount
operationId: completeVerificationExternalAccount
security:
- basic_auth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: This key should be something unique, preferably something like an UUID.
schema:
type: string
- name: id
in: path
schema:
type: string
description: external account id
required: true
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/external_account'
'422':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/external_account_complete_verification_request'
/api/external_accounts:
get:
summary: list external accounts
tags:
- ExternalAccount
operationId: listExternalAccounts
security:
- basic_auth: []
parameters:
- name: after_cursor
in: query
schema:
type: string
nullable: true
required: false
- name: per_page
in: query
required: false
schema:
type: integer
- name: party_name
in: query
required: false
description: Searches the ExternalAccount's party_name AND the Counterparty's party_name
schema:
type: string
- name: counterparty_id
in: query
schema:
type: string
required: false
- name: external_id
in: query
schema:
type: string
required: false
description: An optional user-defined 180 character unique identifier.
- $ref: '#/components/parameters/metadata_query'
responses:
'200':
description: successful
headers:
X-After-Cursor:
schema:
type: string
nullable: true
required: false
description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
X-Per-Page:
schema:
type: integer
nullable: true
description: The current `per_page`.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/external_account'
'401':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
post:
summary: create external account
tags:
- ExternalAccount
operationId: createExternalAccount
security:
- basic_auth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: This key should be something unique, preferably something like an UUID.
schema:
type: string
responses:
'201':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/external_account'
'422':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/external_account_create_request'
/api/external_accounts/{id}:
parameters:
- name: id
in: path
schema:
type: string
description: external account id
required: true
get:
summary: show external account
tags:
- ExternalAccount
operationId: getExternalAccount
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/external_account'
'404':
description: not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
patch:
summary: update external account
tags:
- ExternalAccount
operationId: updateExternalAccount
security:
- basic_auth: []
parameters: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/external_account'
'404':
description: not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
'409':
description: conflict
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
'422':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/external_account_update_request'
delete:
summary: delete external account
tags:
- ExternalAccount
operationId: deleteExternalAccount
security:
- basic_auth: []
responses:
'204':
description: successful
components:
schemas:
account_detail:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
account_number:
type: string
description: The account number for the bank account.
account_number_type:
type: string
enum:
- au_number
- base_address
- card_token
- clabe
- ethereum_address
- hk_number
- iban
- id_number
- nz_number
- other
- pan
- polygon_address
- sg_number
- solana_address
- wallet_address
description: One of `iban`, `clabe`, `wallet_address`, or `other`. Use `other` if the bank account number is in a generic format.
account_number_safe:
type: string
description: The last 4 digits of the account_number.
additionalProperties: false
minProperties: 8
maxProperties: 9
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- account_number_type
- account_number_safe
address:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
line1:
type: string
nullable: true
line2:
type: string
nullable: true
locality:
type: string
nullable: true
description: Locality or City.
region:
type: string
nullable: true
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
nullable: true
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
nullable: true
nullable: true
additionalProperties: false
minProperties: 11
required:
- id
- object
- live_mode
- created_at
- updated_at
- line1
- line2
- locality
- region
- postal_code
- country
external_account_verification_attempt:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
external_account_id:
type: string
format: uuid
description: The ID of the external account.
originating_account_id:
type: string
format: uuid
description: The ID of the internal account where the micro-deposits originate from.
payment_type:
type: string
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
description: The type of payment that can be made to this account. Can be `ach`, `eft`, or `rtp`.
priority:
type: string
enum:
- high
- normal
nullable: true
description: The priority of the payment. Can be `normal` or `high`.
status:
type: string
enum:
- cancelled
- failed
- pending_verification
- verified
description: The status of the verification attempt. Can be `pending_verification`, `verified`, `failed`, or `cancelled`.
additionalProperties: false
minProperties: 10
required:
- id
- object
- live_mode
- created_at
- updated_at
- external_account_id
- originating_account_id
- payment_type
- priority
- status
external_account_update_request:
type: object
properties:
party_type:
type: string
enum:
- business
- individual
nullable: true
description: Either `individual` or `business`.
account_type:
$ref: '#/components/schemas/external_account_type'
counterparty_id:
type: string
format: uuid
nullable: true
name:
type: string
nullable: true
description: A nickname for the external account. This is only for internal usage and won't affect any payments
party_name:
type: string
description: If this value isn't provided, it will be inherited from the counterparty's name.
party_address:
$ref: '#/components/schemas/address_request'
metadata:
type: object
additionalProperties:
type: string
description: Additional data in the form of key-value pairs. Pairs can be removed by passing an empty string or `null` as the value.
external_account_type:
type: string
enum:
- base_wallet
- cash
- checking
- crypto_wallet
- ethereum_wallet
- general_ledger
- loan
- non_resident
- other
- overdraft
- polygon_wallet
- savings
- solana_wallet
description: Can be `checking`, `savings` or `other`.
external_account_verify_request:
type: object
properties:
originating_account_id:
type: string
format: uuid
description: The ID of the internal account where the micro-deposits originate from. Both credit and debit capabilities must be enabled.
payment_type:
type: string
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
description: Can be `ach`, `eft`, or `rtp`.
currency:
$ref: '#/components/schemas/currency'
description: Defaults to the currency of the originating account.
fallback_type:
type: string
enum:
- ach
description: A payment type to fallback to if the original type is not valid for the receiving account. Currently, this only supports falling back from RTP to ACH (payment_type=rtp and fallback_type=ach)
priority:
type: string
enum:
- high
- normal
description: Either `normal` or `high`. For ACH payments, `high` represents a same-day ACH transfer. This will apply to both `payment_type` and `fallback_type`.
required:
- originating_account_id
- payment_type
contact_detail_create_request:
type: object
properties:
contact_identifier:
type: string
contact_identifier_type:
type: string
enum:
- email
- phone_number
- website
ledger_account_create_request:
type: object
properties:
name:
type: string
description: The name of the ledger account.
description:
type: string
description: The description of the ledger account.
nullable: true
normal_balance:
type: string
enum:
- credit
- debit
description: The normal balance of the ledger account.
_x-stainless-modelDefPath: $shared.transaction_direction
ledger_id:
type: string
format: uuid
description: The id of the ledger that this account belongs to.
currency:
type: string
description: The currency of the ledger account.
currency_exponent:
type: integer
description: The currency exponent of the ledger account.
nullable: true
ledger_account_category_ids:
type: array
items:
type: string
format: uuid
description: The array of ledger account category ids that this ledger account should be a child of.
ledgerable_id:
type: string
format: uuid
description: If the ledger account links to another object in Modern Treasury, the id will be populated here, otherwise null.
ledgerable_type:
type: string
enum:
- counterparty
- external_account
- internal_account
- virtual_account
description: If the ledger account links to another object in Modern Treasury, the type will be populated here, otherwise null. The value is one of internal_account or external_account.
metadata:
type: object
description: Additional data represented as key-value pairs. Both the key and value must be strings.
additionalProperties:
type: string
example:
key: value
foo: bar
modern: treasury
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
required:
- name
- normal_balance
- ledger_id
- currency
currency:
type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BCH
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTC
- BTN
- BWP
- BYN
- BYR
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNH
- CNY
- COP
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EEK
- EGP
- ERN
- ETB
- ETH
- EUR
- EURC
- FJD
- FKP
- GBP
- GBX
- GEL
- GGP
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- IMP
- INR
- IQD
- IRR
- ISK
- JEP
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LTL
- LVL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MRU
- MTL
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- OP
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- PYUSD
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SKK
- SLE
- SLL
- SOS
- SRD
- SSP
- STD
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMM
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- USDB
- USDC
- USDG
- USDP
- USDT
- UYU
- UZS
- VEF
- VES
- VND
- VUV
- WST
- XAF
- XAG
- XAU
- XBA
- XBB
- XBC
- XBD
- XCD
- XCG
- XDR
- XFU
- XOF
- XPD
- XPF
- XPT
- XTS
- YER
- ZAR
- ZMK
- ZMW
- ZWD
- ZWG
- ZWL
- ZWN
- ZWR
description: Three-letter ISO currency code.
error_message:
type: object
properties:
errors:
type: object
properties:
code:
type: string
enum:
- parameter_invalid
- parameter_missing
- resource_not_found
- not_found
- forbidden
- invalid_ip
- invalid_key
- header_invalid
- expired_key
- conflict
- too_many_requests
message:
type: string
parameter:
type: string
required:
- errors
contact_detail:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
contact_identifier:
type: string
contact_identifier_type:
type: string
enum:
- email
- phone_number
- website
additionalProperties: false
minProperties: 8
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- contact_identifier
- contact_identifier_type
external_account:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
account_type:
$ref: '#/components/schemas/external_account_type'
party_type:
type: string
enum:
- business
- individual
nullable: true
description: Either `individual` or `business`.
party_address:
$ref: '#/components/schemas/address'
description: The address associated with the owner or `null`.
name:
type: string
nullable: true
description: A nickname for the external account. This is only for internal usage and won't affect any payments
counterparty_id:
type: string
format: uuid
nullable: true
account_details:
type: array
items:
$ref: '#/components/schemas/account_detail'
routing_details:
type: array
items:
$ref: '#/components/schemas/routing_detail'
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
metadata:
type: object
additionalProperties:
type: string
example:
key: value
foo: bar
modern: treasury
description: Additional data represented as key-value pairs. Both the key and value must be strings.
party_name:
type: string
description: The legal name of the entity which owns the account.
contact_details:
type: array
items:
$ref: '#/components/schemas/contact_detail'
ledger_account_id:
type: string
format: uuid
nullable: true
description: If the external account links to a ledger account in Modern Treasury, the id of the ledger account will be populated here.
verification_status:
type: string
enum:
- pending_verification
- unverified
- verified
verification_source:
type: string
enum:
- ach_prenote
- microdeposits
- plaid
nullable: true
additionalProperties: false
minProperties: 20
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- account_type
- party_type
- party_address
- name
- counterparty_id
- account_details
- routing_details
- external_id
- metadata
- party_name
- contact_details
- ledger_account_id
- verification_status
- verification_source
external_account_complete_verification_request:
type: object
properties:
amounts:
type: array
items:
type: integer
maxItems: 2
example:
- 2
- 4
external_account_create_request:
type: object
properties:
account_type:
$ref: '#/components/schemas/external_account_type'
party_type:
type: string
enum:
- business
- individual
nullable: true
description: Either `individual` or `business`.
party_address:
$ref: '#/components/schemas/address_request'
description: Required if receiving wire payments.
name:
type: string
nullable: true
description: A nickname for the external account. This is only for internal usage and won't affect any payments
counterparty_id:
type: string
format: uuid
nullable: true
account_details:
type: array
items:
type: object
properties:
account_number:
type: string
account_number_type:
type: string
enum:
- au_number
- base_address
- card_token
- clabe
- ethereum_address
- hk_number
- iban
- id_number
- nz_number
- other
- pan
- polygon_address
- sg_number
- solana_address
- wallet_address
required:
- account_number
routing_details:
type: array
items:
type: object
properties:
routing_number:
type: string
routing_number_type:
type: string
enum:
- aba
- au_bsb
- br_codigo
- ca_cpa
- chips
- cnaps
- dk_interbank_clearing_code
- gb_sort_code
- hk_interbank_clearing_code
- hu_interbank_clearing_code
- id_sknbi_code
- il_bank_code
- in_ifsc
- jp_zengin_code
- my_branch_code
- mx_bank_identifier
- nz_national_clearing_code
- pl_national_clearing_code
- se_bankgiro_clearing_code
- sg_interbank_clearing_code
- swift
- za_national_clearing_code
payment_type:
type: string
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
required:
- routing_number
- routing_number_type
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
metadata:
type: object
additionalProperties:
type: string
example:
key: value
foo: bar
modern: treasury
description: Additional data represented as key-value pairs. Both the key and value must be strings.
party_name:
type: string
description: If this value isn't provided, it will be inherited from the counterparty's name.
party_identifier:
type: string
ledger_account:
$ref: '#/components/schemas/ledger_account_create_request'
description: Specifies a ledger account object that will be created with the external account. The resulting ledger account is linked to the external account for auto-ledgering Payment objects. See https://docs.moderntreasury.com/docs/linking-to-other-modern-treasury-objects for more details.
plaid_processor_token:
type: string
description: If you've enabled the Modern Treasury + Plaid integration in your Plaid account, you can pass the processor token in this field.
contact_details:
type: array
items:
$ref: '#/components/schemas/contact_detail_create_request'
required:
- counterparty_id
address_request:
type: object
properties:
line1:
type: string
nullable: true
line2:
type: string
nullable: true
locality:
type: string
nullable: true
description: Locality or City.
region:
type: string
nullable: true
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
nullable: true
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
nullable: true
routing_detail:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
routing_number:
type: string
description: The routing number of the bank.
routing_number_type:
type: string
enum:
- aba
- au_bsb
- br_codigo
- ca_cpa
- chips
- cnaps
- dk_interbank_clearing_code
- gb_sort_co
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-externalaccount-api-openapi.yml