# Update a sub-entity A sub-entity may need to be updated because their details have changed, they encounter issues when submitting their application, or to fulfill specific verification requirements. Use the API to update a sub-entity. > **Information** > > Upon updating a sub-entity, we may conduct further verification checks when necessary. During these checks, the sub-entity's payment and payout capabilities will remain unchanged. --- ## Update a sub-entity using the API The fields under the `contact_details`, `profile`, and `company` objects can be updated. > **Note** > > The `profile.default_holding_currency` field is not currently updatable. If you need to change it, [contact support](https://dashboard.checkout.com/support/). When updating a company or sole trader sub-entity, include `is_draft: true` to keep the sub-entity in `Draft` status without triggering due-diligence checks. This is useful for saving a sub-entity's progress before final submission. Call the [Update entity details](https://api-reference.checkout.com/tag/Platforms/#operation/updateEntityDetails) endpoint, and provide the sub-entity ID as the `{id}` path parameter. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `PUT` `https://{prefix}.api.checkout.com/accounts/entities/{id}` **Sandbox** `PUT` `https://{prefix}.api.sandbox.checkout.com/accounts/entities/{id}` ### Request examples **Company sub-entity** ```json { "seller_category":"Silver", "profile":{ "urls":[ "https://www.theonlineretailer.com" ], "mccs":[ "5551" ], "holding_currencies":[ "USD" ], "default_holding_currency":"USD" }, "processing_details":{ "annual_processing_volume":125000, "average_transaction_value":5000, "average_order_fulfillment_time":3, "currency":"USD", "target_countries":[ "US", "VI" ] }, "company":{ "business_type":"private_corporation", "principal_address":{ "country":"US", "address_line1":"123 Anywhere St.", "city":"Anytown", "zip":"12345", "state":"AL" }, "representatives":[ { "roles":[ "ubo" ], "individual":{ "first_name":"Toby", "last_name":"Arden", "address":{ "address_line1":"123 Anywhere St.", "country":"US", "state":"AL", "zip":"12345", "city":"Anytown" }, "date_of_birth":{ "day":23, "month":1, "year":1990 }, "place_of_birth":{ "country":"US" } } } ], "trading_name":"TheOnlineRetailer", "date_of_incorporation":{ "day":22, "month":2, "year":1990 } }, "contact_details":{ "phone":{ "number":"4155678900", "country_code":"US" }, "email_addresses":{ "primary":"theonlineretailer@example.com" } } } ``` **Sole trader sub-entity** ```json { "seller_category":"Silver", "profile":{ "urls":[ "https://www.theonlineretailer.com" ], "mccs":[ "5551" ], "holding_currencies":[ "USD" ], "default_holding_currency":"USD" }, "processing_details":{ "annual_processing_volume":12300, "average_transaction_value":12300, "average_order_fulfillment_time":3, "currency":"USD", "target_countries":[ "US", "VI" ] }, "company":{ "business_type":"individual_or_sole_proprietorship", "principal_address":{ "country":"US", "address_line1":"123 Anywhere St.", "city":"Anytown", "zip":"12345", "state":"AL" }, "representatives":[ { "roles":[ "ubo" ], "individual":{ "first_name":"Toby", "last_name":"Arden", "address":{ "address_line1":"123 Anywhere St.", "country":"US", "state":"AL", "zip":"12345", "city":"Anytown" }, "date_of_birth":{ "day":23, "month":1, "year":1990 }, "place_of_birth":{ "country":"US" } } } ], "trading_name":"TheOnlineRetailer" }, "contact_details":{ "phone":{ "number":"4155678900", "country_code":"US" }, "email_addresses":{ "primary":"theonlineretailer@example.com" } } } ``` ### Response examples When you call the [Update entity details](https://api-reference.checkout.com/tag/Platforms/#operation/updateEntityDetails) endpoint, you receive one of the following HTTP responses, depending on the outcome: - 200 - Sub-entity updated successfully - 422 - Invalid data was sent #### 200 - Sub-entity updated successfully If the request is successful, you receive a `200` response. The `status` is set to `pending` as the sub-entity needs to undergo verification checks again. ```json { "id": "ent_wxglze3wwywujg4nna5fb7ldli", "reference": "superhero1234", "status": "pending", "capabilities": { "payments": { "available": true, "enabled": false }, "payouts": { "available": true, "enabled": false }, "requirements_due": [], "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli" } } } } ``` > **Note** > > Capabilities are enabled after verification checks complete. If you have not received a `{check}_passed` or `{check}_failed` webhook, there may be outstanding requirements due. See [verification requirements](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/collect-verification-information.md) to confirm the sub-entity has provided all required information. If you confirm that the sub-entity has provided all required information and you still have not received the webhooks, we may conduct a manual review. #### 422 - Invalid data was sent In case of any issues in the request, you receive a `422` response. ```json { "request_id": "0HM1I9VJUDPHV:00000002", "error_type": "invalid_request", "error_codes": [ "profile_mccs_invalid_for_processing_scope", "principal_address_country_invalid_for_processing_scope" ] } ``` The response also returns the `error_codes` object with specific error details. See the following table for information on the different error codes. ##### Possible error codes | Name | Description | | --- | --- | | `profile_mccs_invalid_for_processing_scope` | The MCCs provided for the sub-entity are outside Checkout.com's processing scope via the platform. | | `principal_address_country_invalid_for_processing_scope` | The principal address country provided for the sub-entity is outside Checkout.com's processing scope via the platform. | | `company_or_individual_required` | The `company` or `individual` is missing in the request. Include this information and send the request again. | | `sub_entity_invalid` | Internal validation error. If you receive this error, [contact support](https://dashboard.checkout.com/support/). | | `existing_sub_entity_type_invalid` | The specified sub-entity type is invalid. This occurs when the company type is used in an individual request, and vice versa. | | `_invalid`
For example, `legal_name_invalid`, or `profile_urls_0_invalid`. | The specified field does not match the validation policies for minimum or maximum length, or formatting. The `company` or `individual` object must be provided in the request.
The only two exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`, which have different causes. | | `_required`
For example, `legal_name_required` or `representatives_0_first_name_required`. | The specified field is required but was not provided in the request. For example, the field is `null`, contains empty strings, or contains white spaces. |