Modern Treasury Counterparty API

openapi: 3.2.0
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
          - 'null'
        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
                - 'null'
              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
                - 'null'
              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:
    counterparty_create_request:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: A human friendly name for this counterparty.
        accounts:
          type: array
          items:
            type: object
            properties:
              account_type:
                $ref: '#/components/schemas/external_account_type'
              party_type:
                type:
                - string
                - 'null'
                enum:
                - business
                - individual
                description: Either `individual` or `business`.
              party_address:
                $ref: '#/components/schemas/address_request'
                description: Required if receiving wire payments.
              name:
                type:
                - string
                - 'null'
                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
                - 'null'
                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
          - 'null'
          format: email
          description: The counterparty's email.
        legal_entity_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The id of the legal entity.
        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
          - 'null'
          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
    contact_detail_create_request:
      type: object
      properties:
        contact_identifier:
          type: string
        contact_identifier_type:
          type: string
          enum:
          - email
          - phone_number
          - website
    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
          - 'null'
          format: date-time
        classification_type:
          type: string
          enum:
          - anzsic
          - bics
          - gics
          - hsics
          - icb
          - isic
          - mgecs
          - nace
          - naics
          - rbics
          - sic
          - sni
          - trbc
          - uksic
          - unspsc
          description: The classification system of the classification codes.
        classification_codes:
          type: array
          items:
            type: string
          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_collect_account_response:
      type: object
      properties:
        id:
          type: string
          description: The id of the existing counterparty.
        is_resend:
          type: boolean
          description: This field will be `true` if an email requesting account details has already been sent to this counterparty.
        form_link:
          type: string
          format: uri
          description: This is the link to the secure Modern Treasury form. By default, Modern Treasury will send an email to your counterparty that includes a link to this form. However, if `send_email` is passed as `false` in the body then Modern Treasury will not send the email and you can send it to the counterparty directly.
      additionalProperties: false
      minProperties: 3
      required:
      - id
      - is_resend
      - form_link
    address:
      type:
      - object
      - 'null'
      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
          - 'null'
        line2:
          type:
          - string
          - 'null'
        locality:
          type:
          - string
          - 'null'
          description: Locality or City.
        region:
          type:
          - string
          - 'null'
          description: Region or State.
        postal_code:
          type:
          - string
          - 'null'
          description: The postal code of the address.
        country:
          type:
          - string
          - 'null'
          description: Country code conforms to [ISO 3166-1 alpha-2]
      additionalProperties: false
      minProperties: 11
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - line1
      - line2
      - locality
      - region
      - postal_code
      - country
    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
          - 'null'
          format: date-time
        enable_backup_withholding:
          type:
          - boolean
          - 'null'
          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
          - 'null'
          description: The percentage of backup withholding to apply to the legal entity.
        privacy_opt_out:
          type:
          - boolean
          - 'null'
          description: Cross River Bank specific setting to opt out of privacy policy.
        regulation_o:
          type:
          - boolean
          - 'null'
          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
    address_request:
      type: object
      properties:
        line1:
          type:
          - string
          - 'null'
        line2:
          type:
          - string
          - 'null'
        locality:
          type:
          - string
          - 'null'
          description: Locality or City.
        region:
          type:
          - string
          - 'null'
          description: Region or State.
        postal_code:
          type:
          - string
          - 'null'
          description: The postal code of the address.
        country:
          type:
          - string
          - 'null'
          description: Country code conforms to [ISO 3166-1 alpha-2]
    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
          - 'null'
          format: date-time
        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
    third_party_verification:
      type: object
      properties:
        vendor_verification_id:
          type: string
          description: The identification of the third party verification in `vendor`'s system.
        vendor:
          type: string
          enum:
          - persona
          - middesk
          - alloy
          - sumsub
          - veriff
          description: The vendor that performed the verification, e.g. `persona`.
        verification_category:
          type: string
          enum:
          - legal_name
          - date_of_birth
          - address
          - government_id_number
          - adverse_media
          description: The category of verification performed.
        verification_method:
          type: string
          description: The method used to perform the verification.
        comment:
          type:
          - string
          - 'null'
          description: An optional comment about the verification.
        outcome:
          type: string
          enum:
          - passed
          - failed
          description: The outcome of the verification. One of `passed` or `failed`.
        verification_time:
          type: string
          format: date-time
          description: The timestamp when the verification was performed.
      required:
      - vendor_verification_id
      - vendor
      - verification_category
      - verification_method
      - outcome
      - verification_time
      additionalProperties: false
    legal_entity_association_inline_create_request:
      type: object
      properties:
        relationship_types:
          type: array
          items:
            type: string
            enum:
            - authorized_signer
            - beneficial_owner
            - control_person
            description: A list of relationship types for how the child entity relates to parent entity.
        title:
          type:
          - string
          - 'null'
          description: The job title of the child entity at the parent entity.
        ownership_percentage:
          type:
          - integer
          - 'null'
          description: The child entity's ownership percentage iff they are a beneficial owner.
        child_legal_entity:
          $ref: '#/components/schemas/child_legal_entity_create'
          description: The child legal entity.
        child_legal_entity_id:
          type: string
          description: The ID of the child legal entity.
      required:
      - relationship_types
    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
          - 'null'
          format: date-time
        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
    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
          - 'null'
          format: uuid
          description: The id of the legal entity.
        taxpayer_identifier:
          type: string
          description: Either a valid SSN or EIN.
        external_id:
          type:
          - string
          - 'null'
          description: An optional user-defined 180 character unique identifier.
    identification_create_request:
      type: object
      properties:
        id_number:
          type: string
          description: The ID number of identification document.
        documents:
          type: array
          description: A list of documents to attach to the identification.
          items:
            type: object
            properties:
              document_type:
                type: string
                enum:
                - articles_of_incorporation
                - certificate_of_good_standing
                - ein_letter
                - generic
                - identification_back
                - identification_front
                - proof_of_address
                description: A category given to the document, can be `null`.
              file_data:
                type: string
                description: Base64-encoded file content for the document.
              filename:
                type: string
                description: The original filename of the document.
            required:
            - document_type
            - file_data
        id_type:
          type: string
          enum:
          - ar_cuil
          - ar_cuit
          - br_cnpj
          - br_cpf
          - ca_sin
          - cl_run
          - cl_rut
          - co_cedulas
          - co_nit
          - drivers_license
          - hn_id
          - hn_rtn
          - ie_pps
          - in_lei
          - kr_brn
          - kr_crn
          - kr_rrn
          - passport
          - sa_tin
          - sa_vat
          - us_ein
          - us_itin
          - us_ssn
          - vn_tin
          description: The type of ID number.
        expiration_date:
          type:
          - string
          - 'null'
          format: date
          description: The date when the Identification is no longer considered valid by the issuing authority.
        issuing_country:
          type:
          - string
          - 'null'
          description: The ISO 3166-1 alpha-2 country code of the country that issued the identification
        issuing_region:
          type:
          - string
          - 'null'
          description: The region in which the identifcation was issued.
      required:
      - id_number
      - id_type
    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
          - 'null'
          format: date-time
        employment_status:
          type:
          - string
          - 'null'
          enum:
          - employed
          - retired
          - self_employed
          - student
          - unemployed
          description: The employment status of the individual.
        occupation:
          type:
          - string
          - 'null'
          enum:
          - consulting
          - executive
          - finance_accounting
          - food_services
          - government
          - healthcare
          - legal_services
          - manufacturing
          - other
          - sales
          - science_engineering
          - technology
          description: The occupation of the individual.
        industry:
          type:
          - string
          - 'null'
          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
          - trans

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-counterparty-api-openapi.yml