# Legal Entity Management ## Legal Entity Preparation ### Legal Entity Preparation Steps To prepare a legal entity, the partner should: 1. **Search Legal Entities (Optional)**: Partners can search for existing legal entities using `GET /entities/vendor/legal-entities`. This endpoint fetches data from the Legal Entity Data Provider based on country and company name parameters. 2. **Prepare Legal Entity (Optional)**: Partners can prepare data for a legal entity using `POST /entities/vendor/legal-entities`, which orders the data from an external provider. This returns a unique search ID for use in subsequent requests. The partner must wait until the data is ready before proceeding to the next step. This process may take some time as it depends on the external provider's data delivery timeframe. The preparation process goes through several statuses that partners can track: * **PREPARING** - Initial status when a legal entity search is initiated with the provider. * **WAITING\_FOR\_DATA** - The system is waiting for the provider to deliver the basic entity data. * **READY\_DATA** - Basic entity data has been received, but documents are still pending. * **WAITING\_FOR\_DOCUMENTS** - The system is waiting for the provider to deliver the entity documents. * **READY\_DOCUMENTS** - Documents have been received, but some data may still be processing. * **COMPLETED** - Both data and documents have been successfully collected and are ready for use. * **FAILED** - The provider was unable to retrieve the requested data or documents. * **ERROR** - An error occurred during the data collection process. Partners can check the current status using `GET /entities/vendor/legal-entities/{searchId}`. When the status is COMPLETED, partners can proceed to the next step of creating the legal entity. 3. **Create Legal Entity**: Create the legal entity using `POST /entities/legal-entities`. Partners have two options here: * Use data received from the provider (recommended) * Enter the data manually without using the provider If the partner decides to use the provider's data, they must include the `searchId` in the request. This searchId enables the system to automatically retrieve documents from the provider if they exist and helps with data validation. The searchId links the legal entity to the provider's data source. For detailed information about the legal entity creation process, including validation scenarios and business outcomes, see [Legal Entity Creation Process](/documentation/entity_role_management_after_refactor/legal_entity_create_process.md). For updates to existing legal entities, see [Legal Entity Update Process](/documentation/entity_role_management_after_refactor/legal_entity_update_process.md). 4. **Add Beneficial Owners**: Create beneficial owners for the legal entity using `POST /entities/{legalEntityId}/beneficial-owners`. Similar to the legal entity creation, the fields for beneficial owners can also be populated using data received from the provider. This ensures consistency between the legal entity data and its beneficial owners. For detailed information about the beneficial owner creation process, including validation scenarios and business outcomes, see [Beneficial Owner Creation Process](/documentation/entity_role_management_after_refactor/beneficial_owner_create_process.md). For updates to existing beneficial owners, see [Beneficial Owner Update Process](/documentation/entity_role_management_after_refactor/beneficial_owner_update_process.md). 5. **Add Legal Representatives**: Add legal representatives using `POST /entities/{legalEntityId}/legal-representatives`. Just like with beneficial owners, the fields for legal representatives can also be populated using data received from the provider. This maintains data consistency and accuracy across all aspects of the legal entity. For detailed information about the legal representative creation process, including validation scenarios and business outcomes, see [Legal Representative Creation Process](/documentation/entity_role_management_after_refactor/legal_representative_create_process.md). > **Important Note:** If no beneficial owners (type REAL\_UBO\_25) are added to the legal entity, during the onboarding process the system will automatically create fictive beneficial owners (type FICTIVE\_UBO) based on the legal representatives' data. This ensures the legal entity always has associated beneficial owners for compliance purposes. The partner will receive appropriate notifications when these fictive beneficial owners are automatically created. 6. **Upload Documents**: Upload required legal entity documents using `POST /v2/documents` with `resourceType` set to LEGAL\_ENTITY. > **Important Note:** If the legal entity was created using provider data with a searchId, some documents may have been automatically added to the legal entity. The partner will be notified about these documents through appropriate notifications. It's recommended to check which documents were automatically added and upload any missing documents that are required for the onboarding process. Required document types may include: * `CURRENT_REGISTRY_EXTRACT` * `SHAREHOLDER_LIST` * `PARTNERSHIP_AGREEMENT` * `TRANSPARENCY_REGISTER_EXTRACT` * `BUSINESS_REGISTRATION` * `STATUTE` For detailed information about legal entity customer onboarding process, including validation scenarios and sequence diagrams, see [Onboarding](/documentation/entity_role_management_after_refactor/onboarding.md). ## Legal Entity Document Types For detailed information about legal entity document types, including registry information, ownership documents, organizational documents, and tax documents, see [Document Management](/documentation/entity_role_management_after_refactor/document_management.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/legal_entity_management.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.