Modern Treasury LegalEntity API

openapi: 3.2.0
info:
  title: Modern Treasury AccountCapability Legal Entity 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: LegalEntity
paths:
  /api/legal_entities:
    get:
      summary: list legal_entities
      tags:
      - LegalEntity
      operationId: listLegalEntities
      description: Get a list of all legal entities.
      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: legal_entity_type
        in: query
        schema:
          type: string
          enum:
          - business
          - individual
        required: false
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - active
          - suspended
          - denied
        required: false
      - name: show_deleted
        in: query
        required: false
        schema:
          type: string
      - 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
                - '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/legal_entity'
    post:
      summary: create legal_entity
      tags:
      - LegalEntity
      operationId: createLegalEntity
      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/legal_entity'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/legal_entity_create_request'
  /api/legal_entities/{id}:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    get:
      summary: get legal_entity
      tags:
      - LegalEntity
      operationId: getLegalEntity
      description: Get details on a single legal entity.
      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:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/legal_entity'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    patch:
      summary: update legal entity
      tags:
      - LegalEntity
      operationId: updateLegalEntity
      description: Update a legal entity.
      security:
      - basic_auth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/legal_entity'
        '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/legal_entity_update_request'
  /api/simulations/legal_entities/{id}/update_status:
    parameters:
    - name: id
      in: path
      description: Legal entity ID
      required: true
      schema:
        type: string
    patch:
      summary: update legal entity status
      tags:
      - LegalEntity
      operationId: updateLegalEntityStatus
      description: Update Legal Entity Status (sandbox only)
      security:
      - basic_auth: []
      parameters: []
      responses:
        '202':
          description: process started
        '405':
          description: not allowed in production
        '422':
          description: unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/legal_entity_update_status_request'
components:
  schemas:
    legal_entity_update_request:
      type: object
      properties:
        risk_rating:
          type:
          - string
          - 'null'
          enum:
          - low
          - medium
          - high
          description: The risk rating of the legal entity. One of low, medium, high.
        prefix:
          type:
          - string
          - 'null'
          description: An individual's prefix.
        first_name:
          type:
          - string
          - 'null'
          description: An individual's first name.
        middle_name:
          type:
          - string
          - 'null'
          description: An individual's middle name.
        last_name:
          type:
          - string
          - 'null'
          description: An individual's last name.
        suffix:
          type:
          - string
          - 'null'
          description: An individual's suffix.
        preferred_name:
          type:
          - string
          - 'null'
          description: An individual's preferred name.
        citizenship_country:
          type:
          - string
          - 'null'
          description: The country of citizenship for an individual.
        politically_exposed_person:
          type:
          - boolean
          - 'null'
          description: Whether the individual is a politically exposed person.
        date_of_birth:
          type:
          - string
          - 'null'
          format: date
          description: An individual's date of birth (YYYY-MM-DD).
        date_formed:
          type:
          - string
          - 'null'
          format: date
          description: A business's formation date (YYYY-MM-DD).
        business_name:
          type:
          - string
          - 'null'
          description: The business's legal business name.
        doing_business_as_names:
          type: array
          items:
            type: string
            description: A list of "Doing Business As" (DBA) / trade names for a business, different than their legal business name.
        legal_structure:
          type:
          - string
          - 'null'
          enum:
          - corporation
          - llc
          - non_profit
          - partnership
          - sole_proprietorship
          - trust
          description: The business's legal structure.
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              phone_number:
                type: string
            description: A list of phone numbers in E.164 format.
        email:
          type:
          - string
          - 'null'
          description: The entity's primary email.
        website:
          type:
          - string
          - 'null'
          description: The entity's primary website URL.
        business_description:
          type:
          - string
          - 'null'
          description: A description of the business.
        intended_use:
          type:
          - string
          - 'null'
          description: A description of the intended use of the legal entity.
        expected_activity_volume:
          type:
          - integer
          - 'null'
          description: Monthly expected transaction volume in USD.
        country_of_incorporation:
          type:
          - string
          - 'null'
          description: The country code where the business is incorporated in the ISO 3166-1 alpha-2 or alpha-3 formats.
        operating_jurisdictions:
          type: array
          items:
            type: string
          description: A list of countries where the business operates (ISO 3166-1 alpha-2 or alpha-3 codes).
        primary_social_media_sites:
          type: array
          items:
            type: string
          description: A list of primary social media URLs for the business.
        listed_exchange:
          type:
          - string
          - 'null'
          description: ISO 10383 market identifier code.
        ticker_symbol:
          type:
          - string
          - 'null'
          description: Stock ticker symbol for publicly traded companies.
        regulators:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/legal_entity_regulator'
          description: Array of regulatory bodies overseeing this institution.
        third_party_verification:
          $ref: '#/components/schemas/third_party_verification'
          deprecated: true
          description: Deprecated. Use `third_party_verifications` instead.
        third_party_verifications:
          type: array
          items:
            $ref: '#/components/schemas/third_party_verification'
          description: A list of third-party verifications run by external vendors.
          title: Third Party Verfications
        service_provider_legal_entity_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The UUID of the parent legal entity in the service provider tree.
        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
          - 'null'
          description: An optional user-defined 180 character unique identifier.
        bank_settings:
          $ref: '#/components/schemas/legal_entity_bank_setting'
        wealth_and_employment_details:
          $ref: '#/components/schemas/legal_entity_wealth_employment_detail'
        addresses:
          type: array
          description: A list of addresses for the entity.
          items:
            $ref: '#/components/schemas/legal_entity_address_create_request'
        identifications:
          type: array
          description: A list of identifications for the legal entity.
          items:
            $ref: '#/components/schemas/identification_create_request'
        industry_classifications:
          type: array
          description: A list of industry classifications for the legal entity.
          items:
            $ref: '#/components/schemas/legal_entity_industry_classification'
    legal_entity_association:
      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
        parent_legal_entity_id:
          type: string
          description: The ID of the parent legal entity. This must be a business or joint legal entity.
        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'
          description: The child legal entity.
      additionalProperties: false
      minProperties: 11
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - parent_legal_entity_id
      - relationship_types
      - title
      - ownership_percentage
      - child_legal_entity
    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
    document_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
        document_identifier_type:
          type: string
        document_identifier:
          type: string
      additionalProperties: false
      minProperties: 8
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - document_identifier_type
      - document_identifier
    legal_entity_update_status_request:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - active
          - suspended
          - denied
          description: The target status for the legal entity. One of `active`, `suspended`, or `denied`. Valid transitions depend on the current status.
    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
    document:
      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
        document_type:
          type:
          - string
          - 'null'
          description: A category given to the document, can be `null`.
        source:
          type: string
          description: The source of the document. Can be `vendor`, `customer`, or `modern_treasury`.
        documentable_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The unique identifier for the associated object.
        documentable_type:
          type:
          - string
          - 'null'
          enum:
          - connection
          - counterparty
          - expected_payment
          - external_account
          - identification
          - incoming_payment_detail
          - internal_account
          - legal_entity
          - organization
          - payment_order
          - transaction
          description: The type of the associated object. Currently can be one of `payment_order`, `transaction`, `expected_payment`, `counterparty`, `organization`, `case`, `internal_account`, `decision`, or `external_account`.
        document_details:
          type: array
          items:
            $ref: '#/components/schemas/document_detail'
        file:
          type: object
          properties:
            size:
              type: integer
              description: The size of the document in bytes.
            filename:
              type: string
              description: The original filename of the document.
            content_type:
              type: string
              description: The MIME content type of the document.
          additionalProperties: false
          minProperties: 3
      additionalProperties: false
      minProperties: 12
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - document_type
      - source
      - documentable_id
      - documentable_type
      - document_details
      - file
    child_legal_entity:
      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
        legal_entity_type:
          type: string
          enum:
          - business
          - individual
          - joint
          description: The type of legal entity.
        risk_rating:
          type:
          - string
          - 'null'
          enum:
          - low
          - medium
          - high
          description: The risk rating of the legal entity. One of low, medium, high.
        status:
          type:
          - string
          - 'null'
          enum:
          - active
          - denied
          - pending
          - suspended
          description: The activation status of the legal entity. One of pending, active, suspended, or denied.
        prefix:
          type:
          - string
          - 'null'
          description: An individual's prefix.
        first_name:
          type:
          - string
          - 'null'
          description: An individual's first name.
        middle_name:
          type:
          - string
          - 'null'
          description: An individual's middle name.
        last_name:
          type:
          - string
          - 'null'
          description: An individual's last name.
        suffix:
          type:
          - string
          - 'null'
          description: An individual's suffix.
        preferred_name:
          type:
          - string
          - 'null'
          description: An individual's preferred name.
        citizenship_country:
          type:
          - string
          - 'null'
          description: The country of citizenship for an individual.
        politically_exposed_person:
          type:
          - boolean
          - 'null'
          description: Whether the individual is a politically exposed person.
        date_of_birth:
          type:
          - string
          - 'null'
          format: date
          description: An individual's date of birth (YYYY-MM-DD).
        date_formed:
          type:
          - string
          - 'null'
          format: date
          description: A business's formation date (YYYY-MM-DD).
        business_name:
          type:
          - string
          - 'null'
          description: The business's legal business name.
        doing_business_as_names:
          type: array
          items:
            type: string
            description: A list of "Doing Business As" (DBA) / trade names for a business, different than their legal business name.
        legal_structure:
          type:
          - string
          - 'null'
          enum:
          - corporation
          - llc
          - non_profit
          - partnership
          - sole_proprietorship
          - trust
          description: The business's legal structure.
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              phone_number:
                type: string
            description: A list of phone numbers in E.164 format.
        email:
          type:
          - string
          - 'null'
          description: The entity's primary email.
        website:
          type:
          - string
          - 'null'
          description: The entity's primary website URL.
        business_description:
          type:
          - string
          - 'null'
          description: A description of the business.
        intended_use:
          type:
          - string
          - 'null'
          description: A description of the intended use of the legal entity.
        expected_activity_volume:
          type:
          - integer
          - 'null'
          description: Monthly expected transaction volume in USD.
        country_of_incorporation:
          type:
          - string
          - 'null'
          description: The country code where the business is incorporated in the ISO 3166-1 alpha-2 or alpha-3 formats.
        operating_jurisdictions:
          type: array
          items:
            type: string
          description: A list of countries where the business operates (ISO 3166-1 alpha-2 or alpha-3 codes).
        primary_social_media_sites:
          type: array
          items:
            type: string
          description: A list of primary social media URLs for the business.
        listed_exchange:
          type:
          - string
          - 'null'
          description: ISO 10383 market identifier code.
        ticker_symbol:
          type:
          - string
          - 'null'
          description: Stock ticker symbol for publicly traded companies.
        regulators:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/legal_entity_regulator'
          description: Array of regulatory bodies overseeing this institution.
        third_party_verification:
          $ref: '#/components/schemas/third_party_verification'
          deprecated: true
          description: Deprecated. Use `third_party_verifications` instead.
        third_party_verifications:
          type: array
          items:
            $ref: '#/components/schemas/third_party_verification'
          description: A list of third-party verifications run by external vendors.
          title: Third Party Verfications
        service_provider_legal_entity_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The UUID of the parent legal entity in the service provider tree.
        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
          - 'null'
          description: An optional user-defined 180 character unique identifier.
        bank_settings:
          $ref: '#/components/schemas/legal_entity_bank_setting'
        compliance_details:
          type:
          - object
          - 'null'
          deprecated: true
        wealth_and_employment_details:
          $ref: '#/components/schemas/legal_entity_wealth_employment_detail'
        addresses:
          type: array
          description: A list of addresses for the entity.
          items:
            $ref: '#/components/schemas/legal_entity_address'
        identifications:
          type: array
          description: A list of identifications for the legal entity.
          items:
            $ref: '#/components/schemas/identification'
        industry_classifications:
          type: array
          description: A list of industry classifications for the legal entity.
          items:
            $ref: '#/components/schemas/legal_entity_industry_classification'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/document'
        legal_entity_associations:
          type:
          - array
          - 'null'
          description: The legal entity associations and its child legal entities.
          items:
            $ref: '#/components/schemas/legal_entity_association'
      additionalProperties: false
      minProperties: 47
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - legal_entity_type
      - risk_rating
      - status
      - prefix
      - first_name
      - middle_name
      - last_name
      - suffix
      - preferred_name
      - citizenship_country
      - politically_exposed_person
      - date_of_birth
      - date_formed
      - business_name
      - doing_business_as_names
      - legal_structure
      - phone_numbers
      - email
      - website
      - business_description
      - intended_use
      - expected_activity_volume
      - country_of_incorporation
      - operating_jurisdictions
      - primary_social_media_sites
      - listed_exchange
      - ticker_symbol
      - regulators
      - third_party_verification
      - third_party_verifications
      - service_provider_legal_entity_id
      - metadata
      - external_id
      - bank_settings
      - compliance_details
      - wealth_and_employment_details
      - addresses
      - identifications
      - industry_classifications
      - documents
      - legal_entity_associations
    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.
   

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