--- title: "Create Legal Entity" method: POST path: "/legal_entities" --- # Create Legal Entity `POST /legal_entities` ## Request - Base URL: `https://app.moderntreasury.com/api` - URL: `https://app.moderntreasury.com/api/legal_entities` - Auth: HTTP basic Create a legal entity. For a full list of required fields, see [Required Fields for Individuals](https://docs.moderntreasury.com/payments/docs/required-fields-for-individuals) and [Required Fields for Businesses](https://docs.moderntreasury.com/payments/docs/required-fields-for-businesses). ## Request body - union - object - `legal_entity_type` 'individual', required: The type of legal entity. - `status` 'draft': Set to `draft` to create the legal entity as a draft. Omit to create it as `pending`. Inline child legal entities in `legal_entity_associations` take the parent's status and can't set their own `status`. - `prefix` string: An individual's prefix. - `first_name` string, required: An individual's first name. Required for individuals. - `middle_name` string: An individual's middle name. - `last_name` string, required: An individual's last name. Required for individuals. - `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. - `date_of_birth` string, date, required: An individual's date of birth (YYYY-MM-DD). Required for individuals. - `identifications` object[], required: A list of identifications for the legal entity. Required for both individuals and businesses. - `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 sub-national region (state, province, territory) that issued the identification document. For a US driver's license issued in California, this would be "CA". - `expiration_date` string, date: The date when the Identification is no longer considered valid by the issuing authority - `documents` object[]: A list of Documents to be created and associated with a given identification. Individuals require identification documents: - Driver's license: both `identification_front` and `identification_back` - Passport: only `identification_front` Use this location for identity-document types; entity-level documents belong in the top-level `documents` array. - `document_type` 'ein_letter' | 'identification_front' | 'identification_back' - `file_data` string, required: Base64-encoded bytes of the file to be uploaded. - `filename` string, required - `phone_numbers` object[], required: A list of phone numbers in E.164 format. Required for both individuals and businesses. - `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. - `wealth_and_employment_details` object: Wealth and employment details for an individual. Source of funds can be submitted for a business. - `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"' | 'business_revenue' | 'debt_financing' | 'intercompany_loan' | 'investor_funding' | 'retained_earnings_or_savings' | 'sale_of_business_assets' | 'sale_of_real_estate': The source of the business or individual's funds. - `wealth_source` '"business_sale"' | '"family_support"' | '"government_benefits"' | '"inheritance"' | '"investments"' | '"other"' | '"rental_income"' | '"retirement"' | '"salary"' | '"self_employed"': The source of the business or individual's wealth. - `annual_income` integer: The annual income of the individual in USD. - `email` string, required: The entity's primary email. Required for individuals. - `addresses` object[], required: A list of addresses for the entity. Required for both individuals and businesses. - `address_types` string[]: The types of this address. Possible values: `business`, `business_registered`, `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 - `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. - `intended_use` string: A description of the entity's intended use as related to any associated accounts or payments. - `expected_activity_volume` number: Monthly expected transaction volume in USD dollars. - `external_id` string: An optional user-defined unique identifier. - `documents` object[]: A list of Documents to be created and associated with the legal entity. Use this location for entity-level document types; identity documents belong under the relevant identification's `documents` array. - `document_type` 'articles_of_incorporation' | 'generic' | 'certificate_of_good_standing' | 'proof_of_address', required: A category given to the document. `proof_of_address` is accepted for individuals: a utility bill, bank statement, credit card statement, insurance document (liability, vehicle, home, or renters), NMLS listing, or W-9 showing the individual's full legal name and residential address, dated within the last 3 months. - `file_data` string, required: Base64-encoded bytes of the file to upload. - `filename` string, required: Name of the file to be uploaded. - `service_provider_legal_entity_id` string, uuid, nullable: Optional. The UUID of the service provider legal entity for this legal entity in the service provider tree. Used to identify which service provider owns this legal entity (e.g., for a customer of your customer, this would be the ID of the intermediate customer's legal entity). Note: This field requires enablement on your organization. - `terms_of_use` object, nullable: Acceptance of terms of use by the legal entity. - `accepted_at` string, date-time, required: The ISO 8601 timestamp indicating when the terms of use were accepted (e.g., `2026-04-09T00:11:07Z`). - `ip_address` string, required: The IP address from which the terms of use were accepted. Supports both IPv4 and IPv6 formats (e.g., `192.168.1.1` or `2001:0db8::1`). - object - `legal_entity_type` 'business', required: The type of legal entity. - `status` 'draft': Set to `draft` to create the legal entity as a draft. Omit to create it as `pending`. Inline child legal entities in `legal_entity_associations` take the parent's status and can't set their own `status`. - `business_name` string, required: The business's legal business name. - `date_formed` string, required: The business's formation date (YYYY-MM-DD). - `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` 'corporation' | 'llc' | 'non_profit' | 'partnership' | 'sole_proprietorship' | 'trust', required: The business's legal structure. - `identifications` object[], required: 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. - `issuing_country` string: The ISO 3166-1 alpha-2 country code of the country that issued the identification. - `issuing_region` string: The sub-national region (state, province, territory) that issued the identification document. For a US driver's license issued in California, this would be "CA". - `expiration_date` string, date: The date when the Identification is no longer considered valid by the issuing authority. - `documents` object[]: A list of Documents to be created and associated with a given identification. Use this location for identity-document types; businesses typically attach an `ein_letter` here. Entity-level documents belong in the top-level `documents` array. - `document_type` 'ein_letter' | 'identification_front' | 'identification_back', required: Classification of the document. - `file_data` string, required: Base64-encoded bytes of the file to be uploaded. - `filename` string, required - `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. - `wealth_and_employment_details` object: Information on wealth source or source of funds for a business. - `source_of_funds` 'legal_settlement' | 'real_estate' | 'trust_income' | 'business_revenue' | 'debt_financing' | 'intercompany_loan' | 'investor_funding' | 'reatained_earnings_or_savings' | 'sale_of_business_assets' | 'sale_of_real_estate': The source of the business or individual's funds. - `wealth_source` 'business_sale' | 'family_support' | 'government_benefits' | 'inheritance' | 'investments' | 'other' | 'rental_income' | 'retirement' | 'salary' | 'self_employed': The source of the business or individual's wealth. - `email` string: The entity's primary email. Required for individuals. - `addresses` object[], required - `address_types` 'business' | 'business_registered', required: The type of address. - `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` true | false: Designates if this is the primary address for the Legal Entity. - `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. - `legal_entity_associations` object[] - `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` string: The child entity's ownership percentage if they are a beneficial owner. - `child_legal_entity` object: The child legal entity object. - `legal_entity_type` 'individual', required: The type of legal entity. - `prefix` string: An individual's prefix. - `first_name` string, required: An individual's first name. Required for individuals. - `middle_name` string: An individual's middle name. - `last_name` string, required: An individual's last name. Required for individuals. - `suffix` string: An individual's suffix. - `preferred_name` string, date: An individual's preferred name. - `citizenship_country` string: The ISO 3166-1 alpha-2 country code of the individual's citizenship country. - `date_of_birth` string, date, required: An individual's date of birth (YYYY-MM-DD). Required for individuals. - `identifications` object[], required: A list of identifications for the legal entity. Required for both individuals and businesses. - `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 sub-national region (state, province, territory) that issued the identification document. For a US driver's license issued in California, this would be "CA". - `expiration_date` string, date: The date when the Identification is no longer considered valid by the issuing authority - `documents` object: A list of Documents to be created and associated with a given identification. - `document_type` 'generic' | 'identification_front' | 'identification_back' - `file_data` string, required - `filename` string, required - `phone_numbers` object[], required - `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. - `wealth_and_employment_details` object: Wealth and employment details for an individual. Source of funds can be submitted for a business. - `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' | '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_store' | 'laundry' | 'maintenance' | 'manufacturing' | 'merchant_wholesale' | 'mining' | 'performing_arts' | 'professional_arts' | 'public_administration' | 'publishing' | 'real_estate' | 'recreation_gambling' | 'religous_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_benfits' | '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_benfits' | 'homemaker' | 'inheritance_gift' | 'investments' | 'legal_settlement' | 'lottery' | 'real_estate' | 'retired' | 'retirement' | 'salary' | 'self_employed' | 'senior_executive' | 'trust_income' | 'business_revenue' | 'debt_financing' | 'intercompany_loan' | 'investor_funding' | 'retained_earnings_or_savings' | 'sale_of_business_assets' | 'sale_of_real_estate' - `wealth_source` 'business_sale' | 'family_support' | 'government_benefits' | 'inheritance' | 'investments' | 'other' | 'rental_income' | 'retirement' | 'salary' | 'self_employed': The source of the business or individual's wealth. - `annual_income` integer: The annual income of the individual in USD. - `email` string, required: The entity's primary email. Required for individuals. - `addresses` object[], required: A list of addresses for the entity. Required for both individuals and businesses. - `address_types` string[]: The types of this address. Possible values: `business`, `business_registered`, `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. - `primary` boolean: Designates if this is the primary address for the LegalEntity - `website` string: The entity's primary website URL. - `metadata` string, json: Additional data represented as key-value pairs. Both the key and value must be strings. - `intended_use` string: A description of the entity's intended use as related to any associated accounts or payments. - `expected_activity_volume` number: Monthly expected transaction volume in USD dollars. - `primary_social_media_sites` string[]: A list of the entity's primary social media URLs. - `external_id` string: An optional user-defined unique identifier. - `child_legal_entity_id` string: The ID of the child legal entity. - `business_description` string, required: A description of the business. Required for businesses. - `intended_use` string, required: A description of the intended use of the business. Required for businesses. - `expected_activity_volume` string, required: Monthly expected transaction volume in USD dollars. - `country_of_incorporation` string: The country where the business is incorporated, as an ISO 3166-1 alpha-2 country code (e.g. US). - `operating_jurisdictions` string[]: A list of countries where the business operates, as ISO 3166-1 alpha-2 country codes (e.g. ["US", "CA"]). - `ticker_symbol` string: Stock ticker symbol for a publicly traded business. - `listed_exchange` string: The ISO 10383 market identifier code of the business (e.g., XNAS for NASDAQ, XNYS for NYSE). - `connection_id` string: Defaults to the id of the connection designated with an is_default value of true, or the id of an existing, operational connection if only one is available. Defining the connection_id will associate this legal entity with the identified bank or external connection through the creation of a Connection Legal Entity, if the connection is a valid, operational connection for which downstream connection functionality is supported. Pass in a value of null to prevent the connection_id from being used. - `documents` object[]: A list of Documents to be created and associated with the legal entity. Required for businesses. Use this location for entity-level document types; identity documents belong under the relevant identification's `documents` array. - `document_type` 'articles_of_incorporation' | 'generic' | 'certificate_of_good_standing' | 'proof_of_address', required - `file_data` string, required: Base64-encoded bytes of the file to upload. - `filename` string, required: Name of the file to be uploaded. - `external_id` string: An optional user-defined unique identifier. - `service_provider_legal_entity_id` string: The UUID of the service provider legal entity for this legal entity in the service provider tree. Used to identify which service provider owns this legal entity (e.g., for a customer of your customer, this would be the ID of the intermediate customer's legal entity). Note: This field requires enablement on your organization. - `terms_of_use` object, nullable: Acceptance of terms of use by the legal entity. - `accepted_at` string, date-time, required: The ISO 8601 timestamp indicating when the terms of use were accepted (e.g., `2026-04-09T00:11:07Z`). - `ip_address` string, required: The IP address from which the terms of use were accepted. Supports both IPv4 and IPv6 formats (e.g., `192.168.1.1` or `2001:0db8::1`). - `business_designation` 'non_operating_business' | 'exempt_financial_institution': Legal designation associated with the business. ## Changes - **2026-11-03** `e31c6638c72e`: 2 breaking, 12 info - removed the enum value `generic` of the request property `oneOf[subschema #1: Individual]/identifications/items/documents/items/document_type` - removed the enum value `generic` of the request property `oneOf[subschema #2: Business]/identifications/items/documents/items/document_type` - added the new optional request property `oneOf[subschema #1: Individual]/documents` - added the new optional request property `oneOf[subschema #1: Individual]/status` - …10 more [Operation history](https://skmtc.dev/modern-treasury/apis/modern-treasury-api/changes/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)