---
title: "Create Connection Legal Entity"
method: POST
path: "/connection_legal_entities"
---

# Create Connection Legal Entity

`POST /connection_legal_entities`

## Request

- Base URL: `https://app.moderntreasury.com/api`
- URL: `https://app.moderntreasury.com/api/connection_legal_entities`
- Auth: HTTP basic

**Note: This is not supported in our sandbox environment**

## Request body

- object
  - `connection_id` string, required: The ID of the connection.
  - `legal_entity_id` string: The ID of the legal entity. Please provide this value or `legal_entity`.
  - `legal_entity` object: The legal entity. Please provide this value or `legal_entity_id`.
    - `legal_entity_type` string, required: The type of legal entity. One of: `individual`, `business`
    - `risk_rating` string: The risk rating of legal entity. One of: `low`, `medium`, `high`.
    - `prefix` string: An individual's prefix.
    - `first_name` string: An individual's first name.
    - `middle_name` string: An individual's middle name.
    - `last_name` string: An individual's last name.
    - `suffix` string: An individual's suffix.
    - `preferred_name` string: An individual's preferred name.
    - `citizenship_country` string: The ISO 3166-1 alpha-2 country code of the individual's citizenship country.
    - `politically_exposed_person` boolean: Whether the individual is a politically exposed person.
    - `date_of_birth` string, date: An individual's data of birth (YYYY-MM-DD).
    - `date_formed` string, date: The business's formation date (YYYY-MM-DD).
    - `business_name` string: The business's legal business name.
    - `doing_business_as_names` string[]: A list of "Doing Business As" (DBA) / trade names for a business, different than their legal business name.
    - `legal_structure` string: The business's legal structure. One of: `corporation`, `llc`, `non_profit`, `partnership`, `sole_proprietorship`, `trust`.
    - `phone_numbers` object[]: A list of phone numbers in E.164 format.
      - `phone_number` string: A phone number in E.164 format. This format is strictly validated: include a leading + and country code, followed by digits only (no spaces or dashes), e.g. +12025551234.
    - `bank_settings` object: Additional bank-specific settings for a legal entity.
      - `enable_backup_withholding` boolean: Whether backup withholding is enabled. See more here - https://www.irs.gov/businesses/small-businesses-self-employed/backup-withholding
      - `backup_withholding_percentage` integer: The percentage of backup withholding to apply to the legal entity.
      - `privacy_opt_out` boolean: Cross River Bank specific setting to opt out of privacy policy.
      - `regulation_o` boolean: 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.
    - `wealth_and_employment_details` object: Wealth and employment details for an individual.
      - `employment_status` '"employed"' | '"retired"' | '"self_employed"' | '"student"' | '"unemployed"': The employment status of the individual.
      - `occupation` '"consulting"' | '"executive"' | '"finance_accounting"' | '"food_services"' | '"government"' | '"healthcare"' | '"legal_services"' | '"manufacturing"' | '"other"' | '"sales"' | '"science_engineering"' | '"technology"': The occupation of the individual's employment.
      - `industry` '"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"': The industry of the individual's employment.
      - `income_source` '"family_support"' | '"government_benefits"' | '"inheritance"' | '"investments"' | '"rental_income"' | '"retirement"' | '"salary"' | '"self_employed"': The source of the individual's income.
      - `income_state` string: The state in which the individual's income is earned.
      - `income_country` string: The ISO 3166-1 alpha-2 country code in which the individual's income is earned.
      - `employer_name` string: The name of the employer.
      - `employer_state` string: The state in which the employer is located. This field is free-form text; for US states, we recommend a two-letter abbreviation (e.g. CA).
      - `employer_country` string: The ISO 3166-1 alpha-2 country code in which the employer is located.
      - `source_of_funds` '"alimony"' | '"annuity"' | '"business_owner"' | '"general_employee"' | '"government_benefits"' | '"homemaker"' | '"inheritance_gift"' | '"investment"' | '"legal_settlement"' | '"lottery"' | '"real_estate"' | '"retired"' | '"retirement"' | '"salary"' | '"self_employed"' | '"senior_executive"' | '"trust_income"': The source of the individual's funds.
      - `wealth_source` '"business_sale"' | '"family_support"' | '"government_benefits"' | '"inheritance"' | '"investments"' | '"other"' | '"rental_income"' | '"retirement"' | '"salary"' | '"self_employed"': The source of the individual's wealth.
      - `annual_income` integer: The annual income of the individual.
    - `email` string: The entity's primary email.
    - `website` string: The entity's primary website URL.
    - `primary_social_media_sites` string[]: A list of the entity's primary social media URLs.
    - `metadata` string, json: Additional data represented as key-value pairs. Both the key and value must be strings.
    - `addresses` object[]: A list of addresses for the entity.
      - `address_types` string[]: The types of this address. Possible values: `business`, `mailing`, `other`, `po_box`, `residential`.
      - `line1` string, required: Address line 1
      - `line2` string: Address line 2
      - `locality` string, required: Locality or City. Use the full city name rather than an abbreviation (e.g. San Francisco).
      - `region` string: Region or State. This field is free-form; for US states, we recommend a two-letter code (e.g. CA). Full state names are also accepted. Required for addresses in the US and US territories (AS, GU, MP, PR, UM, VI); optional for other countries.
      - `postal_code` string: The postal code of the address. Required for addresses in the US; optional for other countries.
      - `country` string, required: Country code conforms to [ISO 3166-1 alpha-2]
      - `primary` boolean: Designates if this is the primary address for the LegalEntity
    - `identifications` object[]: A list of identifications for the legal entity.
      - `id_number` string, required: The ID number of identification document.
      - `id_type` string, required: The type of ID number. See list of [Identifications](ref:identifications)
      - `issuing_country` string: The ISO 3166-1 alpha-2 country code of the country that issued the identification.
      - `issuing_region` string: The region in which the identification was issued.
      - `expiration_date` string, date: The date when the Identification is no longer considered valid by the issuing authority
    - `legal_entity_associations` object[]: The legal entity associations and its child legal entities.
      - `relationship_types` string[], required: A list of relationship types for how the child entity relates to parent entity.
      - `title` string: The job title of the child entity at the parent entity.
      - `ownership_percentage` integer: The child entity's ownership percentage if they are a beneficial owner.
      - `child_legal_entity` object: The child legal entity object.
        - `legal_entity_type` string, required: The type of legal entity. One of: `individual`, `business`
        - `risk_rating` string: The risk rating of legal entity. One of: `low`, `medium`, `high`.
        - `prefix` string: An individual's prefix.
        - `first_name` string: An individual's first name.
        - `middle_name` string: An individual's middle name.
        - `last_name` string: An individual's last name.
        - `suffix` string: An individual's suffix.
        - `preferred_name` string: An individual's preferred name
        - `citizenship_country` string: The ISO 3166-1 alpha-2 country code of the individual's citizenship country.
        - `politically_exposed_person` boolean: Whether the individual is a politically exposed person.
        - `date_of_birth` string, date: An individual's data of birth (YYYY-MM-DD).
        - `date_formed` string, date: The business's formation date (YYYY-MM-DD).
        - `business_name` string: The business's legal business name.
        - `doing_business_as_names` string[]: A list of "Doing Business As" (DBA) / trade names for a business, different than their legal business name.
        - `legal_structure` string: The business's legal structure. One of: `corporation`, `llc`, `non_profit`, `partnership`, `sole_proprietorship`, `trust`.
        - `phone_numbers` object[]: A list of phone numbers in E.164 format.
          - `phone_number` string: A phone number in E.164 format. This format is strictly validated: include a leading + and country code, followed by digits only (no spaces or dashes), e.g. +12025551234.
        - `bank_settings` object: Additional bank-specific settings for a legal entity.
          - `enable_backup_withholding` boolean: Whether backup withholding is enabled. See more here - https://www.irs.gov/businesses/small-businesses-self-employed/backup-withholding
          - `backup_withholding_percentage` integer: The percentage of backup withholding to apply to the legal entity.
          - `privacy_opt_out` boolean: Cross River Bank specific setting to opt out of privacy policy.
          - `regulation_o` boolean: 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.
        - `wealth_and_employment_details` object: Wealth and employment details for an individual.
          - `employment_status` '"employed"' | '"retired"' | '"self_employed"' | '"student"' | '"unemployed"': The employment status of the individual.
          - `occupation` '"consulting"' | '"executive"' | '"finance_accounting"' | '"food_services"' | '"government"' | '"healthcare"' | '"legal_services"' | '"manufacturing"' | '"other"' | '"sales"' | '"science_engineering"' | '"technology"': The occupation of the individual's employment.
          - `industry` '"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"': The industry of the individual's employment.
          - `income_source` '"family_support"' | '"government_benefits"' | '"inheritance"' | '"investments"' | '"rental_income"' | '"retirement"' | '"salary"' | '"self_employed"': The source of the individual's income.
          - `income_state` string: The state in which the individual's income is earned.
          - `income_country` string: The ISO 3166-1 alpha-2 country code in which the individual's income is earned.
          - `employer_name` string: The name of the employer.
          - `employer_state` string: The state in which the employer is located. This field is free-form text; for US states, we recommend a two-letter abbreviation (e.g. CA).
          - `employer_country` string: The ISO 3166-1 alpha-2 country code in which the employer is located.
          - `source_of_funds` '"alimony"' | '"annuity"' | '"business_owner"' | '"general_employee"' | '"government_benefits"' | '"homemaker"' | '"inheritance_gift"' | '"investment"' | '"legal_settlement"' | '"lottery"' | '"real_estate"' | '"retired"' | '"retirement"' | '"salary"' | '"self_employed"' | '"senior_executive"' | '"trust_income"': The source of the individual's funds.
          - `wealth_source` '"business_sale"' | '"family_support"' | '"government_benefits"' | '"inheritance"' | '"investments"' | '"other"' | '"rental_income"' | '"retirement"' | '"salary"' | '"self_employed"': The source of the individual's wealth.
          - `annual_income` integer: The annual income of the individual.
        - `email` string: The entity's primary email.
        - `website` string: The entity's primary website URL.
        - `primary_social_media_sites` string[]: A list of the entity's primary social media URLs.
        - `metadata` string, json: Additional data represented as key-value pairs. Both the key and value must be strings.
        - `addresses` object[]: A list of addresses for the entity.
          - `address_types` string[]: The types of this address. Possible values: `business`, `mailing`, `other`, `po_box`, `residential`.
          - `line1` string, required: Address line 1
          - `line2` string: Address line 2
          - `locality` string, required: Locality or City. Use the full city name rather than an abbreviation (e.g. San Francisco).
          - `region` string: Region or State. This field is free-form; for US states, we recommend a two-letter code (e.g. CA). Full state names are also accepted. Required for addresses in the US and US territories (AS, GU, MP, PR, UM, VI); optional for other countries.
          - `postal_code` string: The postal code of the address. Required for addresses in the US; optional for other countries.
          - `country` string, required: Country code conforms to [ISO 3166-1 alpha-2]
          - `primary` boolean: Designates if this is the primary address for the LegalEntity
        - `identifications` object[]: A list of identifications for the legal entity.
          - `id_number` string, required: The ID number of identification document.
          - `id_type` string, required: The type of ID number. See list of [Identifications](ref:identifications)
          - `issuing_country` string: The ISO 3166-1 alpha-2 country code of the country that issued the identification.
          - `issuing_region` string: The region in which the identification was issued.
          - `expiration_date` string, date: The date when the Identification is no longer considered valid by the issuing authority
      - `child_legal_entity_id` string: The ID of the child legal entity.

## Changes

- **2026-11-03** `e31c6638c72e`: 6 info
  - added the new optional request property `legal_entity/legal_entity_associations/items/child_legal_entity/primary_social_media_sites`
  - added the new optional request property `legal_entity/primary_social_media_sites`
  - the request property `legal_entity/addresses/items/postal_code` became optional
  - the request property `legal_entity/addresses/items/region` became optional
  - …2 more

[Operation history](https://skmtc.dev/modern-treasury/apis/modern-treasury-api/changes/connection_legal_entities/post.md)

---

[API](https://skmtc.dev/modern-treasury/apis/modern-treasury-api.md) - [All operations](https://skmtc.dev/modern-treasury/apis/modern-treasury-api/llms.txt) - [OpenAPI document](https://skmtc.dev/modern-treasury/apis/modern-treasury-api/revisions/e31c6638c72e?raw)