Modern Treasury Counterparty API
The Counterparty API from Modern Treasury — 3 operation(s) for counterparty.
OpenAPI Specification
openapi: 3.0.1
info:
title: Modern Treasury AccountCapability Counterparty 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: Counterparty
paths:
/api/counterparties/{id}/collect_account:
post:
summary: collect account details
tags:
- Counterparty
operationId: collectAccountDetails
description: Send an email requesting account details.
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: counterparty id
required: true
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/counterparty_collect_account_response'
'422':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/counterparty_collect_account_request'
/api/counterparties:
get:
summary: list counterparties
tags:
- Counterparty
operationId: listCounterparties
description: Get a paginated list of all counterparties.
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: name
in: query
required: false
description: Performs a partial string match of the name field. This is also case insensitive.
schema:
type: string
- name: email
in: query
schema:
type: string
format: email
required: false
description: Performs a partial string match of the email field. This is also case insensitive.
- name: external_id
in: query
schema:
type: string
required: false
description: An optional user-defined 180 character unique identifier.
- name: legal_entity_id
in: query
schema:
type: string
required: false
description: Filters for counterparties with the given legal entity ID.
- $ref: '#/components/parameters/metadata_query'
- name: created_at_lower_bound
in: query
schema:
type: string
format: date-time
required: false
description: Used to return counterparties created after some datetime.
- name: created_at_upper_bound
in: query
schema:
type: string
format: date-time
required: false
description: Used to return counterparties created before some datetime.
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/counterparty'
'400':
description: bad_request
'401':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
post:
summary: create counterparty
tags:
- Counterparty
operationId: createCounterparty
description: Create a new counterparty.
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/counterparty'
'415':
description: unsuccessful
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/counterparty_create_request'
/api/counterparties/{id}:
parameters:
- name: id
in: path
schema:
type: string
description: The id of an existing counterparty.
required: true
get:
summary: show counterparty
tags:
- Counterparty
operationId: getCounterparty
description: Get details on a single counterparty.
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/counterparty'
'404':
description: not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
patch:
summary: update counterparty
tags:
- Counterparty
operationId: updateCounterparty
description: Updates a given counterparty with new information.
security:
- basic_auth: []
parameters: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/counterparty'
'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/counterparty_update_request'
delete:
summary: delete counterparty
tags:
- Counterparty
operationId: deleteCounterparty
description: Deletes a given counterparty.
security:
- basic_auth: []
responses:
'204':
description: successful
components:
schemas:
legal_entity_regulator:
type: object
properties:
name:
type: string
description: Full name of the regulatory body.
jurisdiction:
type: string
description: The country code where the regulator operates in the ISO 3166-1 alpha-2 format (e.g., "US", "CA", "GB").
registration_number:
type: string
description: Registration or identification number with the regulator.
required:
- name
- jurisdiction
- registration_number
additionalProperties: false
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`.
counterparty_update_request:
type: object
properties:
name:
type: string
description: A new name for the counterparty. Will only update if passed.
email:
type: string
format: email
description: A new email for the counterparty.
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.
send_remittance_advice:
type: boolean
description: If this is `true`, Modern Treasury will send an email to the counterparty whenever an associated payment order is sent to the bank.
legal_entity_id:
type: string
format: uuid
description: The id of the legal entity.
nullable: true
taxpayer_identifier:
type: string
description: Either a valid SSN or EIN.
external_id:
type: string
description: An optional user-defined 180 character unique identifier.
nullable: true
legal_entity_industry_classification:
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
classification_type:
type: string
enum:
- anzsic
- bics
- gics
- hsics
- icb
- isic
- mgecs
- nace
- naics
- rbics
- sic
- sni
- trbc
- uksic
- unspsc
nullable: false
description: The classification system of the classification codes.
classification_codes:
type: array
items:
type: string
nullable: false
description: The industry classification codes for the legal entity.
additionalProperties: false
minProperties: 8
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- classification_type
- classification_codes
counterparty:
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
name:
type: string
description: A human friendly name for this counterparty.
nullable: true
accounts:
type: array
items:
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
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: 19
description: The accounts for this counterparty.
email:
type: string
format: email
description: The counterparty's email.
nullable: true
legal_entity_id:
type: string
format: uuid
description: The id of the legal entity.
nullable: true
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.
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
send_remittance_advice:
type: boolean
description: Send an email to the counterparty whenever an associated payment order is sent to the bank.
verification_status:
type: string
deprecated: true
description: The verification status of the counterparty.
additionalProperties: false
minProperties: 14
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- name
- accounts
- email
- legal_entity_id
- metadata
- external_id
- send_remittance_advice
- verification_status
counterparty_create_request:
type: object
properties:
name:
type: string
description: A human friendly name for this counterparty.
nullable: true
accounts:
type: array
items:
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
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'
description: The accounts for this counterparty.
email:
type: string
format: email
description: The counterparty's email.
nullable: true
legal_entity_id:
type: string
format: uuid
description: The id of the legal entity.
nullable: true
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.
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
send_remittance_advice:
type: boolean
description: Send an email to the counterparty whenever an associated payment order is sent to the bank.
verification_status:
type: string
deprecated: true
description: The verification status of the counterparty.
accounting:
type: object
deprecated: true
properties:
type:
type: string
enum:
- customer
- vendor
description: An optional type to auto-sync the counterparty to your ledger. Either `customer` or `vendor`.
ledger_type:
type: string
enum:
- customer
- vendor
description: An optional type to auto-sync the counterparty to your ledger. Either `customer` or `vendor`.
deprecated: true
taxpayer_identifier:
type: string
description: Either a valid SSN or EIN.
legal_entity:
$ref: '#/components/schemas/legal_entity_create_request'
required:
- name
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
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
legal_entity_bank_setting:
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
enable_backup_withholding:
type: boolean
nullable: true
description: Whether backup withholding is enabled. See more here - https://www.irs.gov/businesses/small-businesses-self-employed/backup-withholding.
backup_withholding_percentage:
type: integer
nullable: true
description: The percentage of backup withholding to apply to the legal entity.
privacy_opt_out:
type: boolean
nullable: true
description: Cross River Bank specific setting to opt out of privacy policy.
regulation_o:
type: boolean
nullable: true
description: It covers, among other types of insider loans, extensions of credit by a member bank to an executive officer, director, or principal shareholder of the member bank; a bank holding company of which the member bank is a subsidiary; and any other subsidiary of that bank holding company.
additionalProperties: false
minProperties: 10
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- enable_backup_withholding
- backup_withholding_percentage
- privacy_opt_out
- regulation_o
legal_entity_wealth_employment_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
employment_status:
type: string
enum:
- employed
- retired
- self_employed
- student
- unemployed
nullable: true
description: The employment status of the individual.
occupation:
type: string
enum:
- consulting
- executive
- finance_accounting
- food_services
- government
- healthcare
- legal_services
- manufacturing
- other
- sales
- science_engineering
- technology
nullable: true
description: The occupation of the individual.
industry:
type: string
enum:
- accounting
- agriculture
- automotive
- chemical_manufacturing
- construction
- educational_medical
- food_service
- finance
- gasoline
- health_stores
- laundry
- maintenance
- manufacturing
- merchant_wholesale
- mining
- performing_arts
- professional_non_legal
- public_administration
- publishing
- real_estate
- recreation_gambling
- religious_charity
- rental_services
- retail_clothing
- retail_electronics
- retail_food
- retail_furnishing
- retail_home
- retail_non_store
- retail_sporting
- transportation
- travel
- utilities
nullable: true
description: The industry of the individual.
income_source:
type: string
enum:
- family_support
- government_benefits
- inheritance
- investments
- rental_income
- retirement
- salary
- self_employed
nullable: true
description: The source of the individual's income.
income_state:
type: string
nullable: true
description: The state in which the individual's income is earned.
income_country:
type: string
nullable: true
description: The country in which the individual's income is earned.
employer_name:
type: string
nullable: true
description: The name of the employer.
employer_state:
type: string
nullable: true
description: The state in which the employer is located.
employer_country:
type: string
nullable: true
description: The country in which the employer is located.
source_of_funds:
type: string
enum:
- alimony
- annuity
- business_owner
- business_revenue
- debt_financing
- general_employee
- government_benefits
- homemaker
- inheritance_gift
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-counterparty-api-openapi.yml