# Submit application After you collect a sub-entity's [verification requirements](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/collect-verification-information.md), submit its information for onboarding using the [Platforms API](https://api-reference.checkout.com/#tag/Platforms). --- ## Before you start Before submitting the application, ensure that: - Checkout.com has configured your account to submit sub-entities for onboarding. - You have received your `client_id` and `client_secret`, which you need to generate access tokens with the required scopes. For more information, see [OAuth 2.0 client credentials](https://www.checkout.com/docs/resources/api-authentication/oauth-2-0-client-credentials.md). - You have received one or more processing channel IDs. - You have configured your [webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) and subscribed to the [relevant events](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/handle-webhooks.md). --- ## Onboard a sub-entity Call the [Onboard an entity](https://api-reference.checkout.com/tag/Platforms/#operation/onboardEntity) endpoint. In the request body, provide all the required fields applicable to the schema for your sub-entity type: - Company sub-entity – `US Company (SaaS)` - Sole trader sub-entity – `US Sole Trader (SaaS)` > **Information** > > You can only set `profile.mccs` and `company.principal_address.country` to the values that were configured for your scope when onboarding your platform. > **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** `POST` `https://{prefix}.api.checkout.com/accounts/entities` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/accounts/entities` ### Request examples > **Information** > > Automated Clearing House (ACH) fields are required only when ACH is enabled for your platform. Otherwise, these fields are optional and you can omit them. **Company sub-entity** ```json { "reference": "isv-seller-example001", "agreed_terms": { "date": "2026-07-02T10:30:00Z", "ip_address": "203.0.113.42", "name": "Toby Arden", "email": "toby.arden@example.com", "version": "cko-platform-terms-1.0.0" }, "seller_category": "cat_retail_001", "processing_details": { "annual_processing_volume": 1000, "average_transaction_value": 2000, "average_order_fulfillment_time": 3, "target_countries": [ "US" ], "currency": "USD", "payments": { "ach": { "annual_ach_volume": 100000, "average_ach_transaction_size": 5000, "estimated_monthly_credit_volume": 50000, "average_credit_amount": 2500 } } }, "contact_details": { "phone": { "number": "5551234567", "country_code": "US" }, "email_addresses": { "primary": "toby.arden@example.com", "pci_compliance_contact": "ali.farid@example.com" } }, "profile": { "urls": [ "https://www.example.com" ], "mccs": [ "5551" ], "holding_currencies": [ "USD" ], "default_holding_currency": "USD" }, "company": { "business_registration_number": "12-3456789", "business_type": "private_corporation", "legal_name": "The Online Retailer Inc", "trading_name": "The Online Retailer", "registered_address": { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" }, "principal_address": { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" }, "date_of_incorporation": { "year": 2025, "month": 10, "day": 1 }, "representatives": [ { "roles": [ "ubo", "control_person" ], "ownership_percentage": 25, "company_position": "ceo", "individual": { "first_name": "Toby", "last_name": "Arden", "email_address": "toby.arden@example.com", "national_id_type": "ssn", "national_id_number": "123456789", "date_of_birth": { "day": 15, "month": 1, "year": 1990 }, "place_of_birth": { "country": "US" }, "citizenships": [ { "country": "US" } ], "phone": { "country_code": "US", "number": "5551234568" }, "address": { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" } } }, { "roles": [ "authorised_signatory" ], "individual": { "first_name": "Jia", "last_name": "Tsang", "email_address": "jia.tsang@example.com", "national_id_type": "ssn", "national_id_number": "987654321", "date_of_birth": { "day": 22, "month": 6, "year": 1985 }, "place_of_birth": { "country": "US" }, "citizenships": [ { "country": "US" } ], "phone": { "country_code": "US", "number": "5551234569" }, "address": { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" } } } ] } } ``` **Sole trader sub-entity** > **Information** > > For a sole trader sub-entity, you must: > > - Set `is_registered_company` to `false`. > - Set `business_type` to `individual_or_sole_proprietorship`. > - Specify only one representative in `representatives`, the individual themselves with their role set to `ubo`. ```json { "reference": "isv-sole-trader-example001", "agreed_terms": { "date": "2026-07-02T10:30:00Z", "ip_address": "203.0.113.42", "name": "Hannah Bret", "email": "hannah.bret@example.com", "version": "cko-platform-terms-1.0.0" }, "seller_category": "cat_retail_001", "processing_details": { "annual_processing_volume": 1000, "average_transaction_value": 2000, "average_order_fulfillment_time": 3, "target_countries": [ "US" ], "currency": "USD", "payments": { "ach": { "annual_ach_volume": 100000, "average_ach_transaction_size": 5000, "estimated_monthly_credit_volume": 50000, "average_credit_amount": 2500 } } }, "contact_details": { "phone": { "number": "5551234567", "country_code": "US" }, "email_addresses": { "primary": "hannah.bret@example.com", "pci_compliance_contact": "ali.farid@example.com" } }, "profile": { "urls": [ "https://www.example.net" ], "mccs": [ "5551" ], "holding_currencies": [ "USD" ], "default_holding_currency": "USD" }, "company": { "business_type": "individual_or_sole_proprietorship", "is_registered_company": false, "trading_name": "Hannah's Goods", "date_of_incorporation": { "year": 2025, "month": 10, "day": 1 }, "principal_address": { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" }, "representatives": [ { "roles": [ "ubo" ], "ownership_percentage": 100, "individual": { "first_name": "Hannah", "last_name": "Bret", "email_address": "hannah.bret@example.com", "national_id_type": "ssn", "national_id_number": "123456789", "date_of_birth": { "day": 15, "month": 1, "year": 1990 }, "place_of_birth": { "country": "US" }, "citizenships": [ { "country": "US" } ], "phone": { "country_code": "US", "number": "5551234568" }, "address": { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" } } } ] } } ``` ### Response examples You can receive one of the following HTTP responses: - `201` – Application submitted successfully - `400` – Bad Request - `401` – Unauthorized - `409` – Conflict - `422` – Invalid data was sent #### 201 – Application submitted successfully ```json { "id": "ent_nofjig36ypra6236f4tfm5bvui", "reference": "isv-seller-example001", "requirements_due": [ { "field": "individual.identification.document", "reason": "required", "message": "required" } ], "_links": { "self": { "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_nofjig36ypra6236f4tfm5bvui" } } } ``` A successful response returns `id` field – The sub-entity ID, which you need for future requests. For a list of all possible statuses, see [Sub-entity status](https://www.checkout.com/docs/platforms/for-saas/manage-sub-entities/sub-entity-status.md). You also receive a [Sub-entity created](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/sub_entity_created.md) webhook. #### 409 – Conflict ```json { "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_lcvk7ay5zcglzvda6n7o5ws2hq" } } } ``` If you receive a `409` response, you provided a `reference` that has already been used for another sub-entity. The `reference` must be a unique value of up to 50 characters. Try again with a different `reference`. #### 422 – Invalid data was sent ```json { "request_id": "0HM72UMS6H39C:00000003", "error_type": "invalid_request", "error_codes": ["reference_required"] } ``` If you receive a `422` response, ensure you've provided all required fields in the request. The response also returns an `error_codes` array with one or more specific errors. For more information, see [Possible error codes](#Possible_error_codes). --- ## Possible error codes If there's an issue when Checkout.com attempts to onboard a sub-entity, you can receive one of the following error codes: | Error code | Description | | --- | --- | | `profile_mccs_invalid_for_processing_scope` | The Merchant Category Codes (MCC) provided for the sub-entity are outside Checkout.com's processing scope for your platform. | | `profile_default_holding_currency_invalid_for_currency_scope` | The default holding currency provided for the sub-entity is outside your platform's currency scope. | | `principal_address_country_invalid_for_processing_scope` | The principal address country provided for the sub-entity is outside Checkout.com's processing scope for your platform. | | `client_entity_cannot_onboard_subentities` | Your platform is not permitted to onboard new sub-entities. | | `company_or_individual_required` | You must provide the `company` or `individual` object in the request. | | `sub_entity_invalid` | There was an internal validation error. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). | | `_invalid` | The specified field uses invalid formatting, or an invalid minimum or maximum length.

For example, `legal_name_invalid`, or `profile_urls_0_invalid`.

The exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`. | | `_required` | The specified field is required, but was not provided in the request.

For example, `legal_name_required` or `representatives_0_first_name_required`.

You receive this error if the field is `null`, or contains empty strings or white spaces. | --- ## Test your integration To test your integration, simulate different onboarding scenarios in the sandbox environment using the Onboarding simulator API. For more information, see [Simulate onboarding scenarios](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/simulate-onboarding-scenarios.md). --- ## Next steps **[Add supporting documents](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/add-supporting-documents.md)** Add supporting documents for sub-entity verification.