# Onboard a sub-entity using the API

You can submit an application to onboard a sub-entity using the [Platforms API](https://api-reference.checkout.com/#tag/Platforms).

> **Information**
>
> You can also onboard sub-entities without code using [the Dashboard](https://www.checkout.com/docs/platforms/onboard-sub-entities/onboard-with-the-dashboard.md).

---

## Before you start

Ensure you've completed the following steps before submitting the application.

- Your account is able to onboard sub-entities.
- You have received your `client_id` and `client_secret`, which you need to generate access tokens with the required scopes. See [OAuth 2.0 client credentials](https://www.checkout.com/docs/resources/api-authentication/oauth-2-0-client-credentials.md) for more information.
- 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/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 region and sub-entity type:

**Lite account**

| Region | Sub-entity type | API schema |
| --- | --- | --- |
| Great Britain | Company | `GB Company - Lite (2.0)` |
| Great Britain | Sole trader | `GB Sole Trader - Lite (2.0)` |
| European Union | Company | `EEA Company - Lite (2.0)` |
| European Union | Sole trader | `EEA Sole Trader - Lite (2.0)` |
| United States | Company | `US Company - Lite (2.0)` |
| United States | Sole trader | `US Sole Trader - Lite (2.0)` |

**Full account**

| Region | Sub-entity type | API schema |
| --- | --- | --- |
| Great Britain | Company | `GB Company - Full (3.0)` |
| Great Britain | Sole trader | `GB Sole Trader - Full (3.0)` |
| European Union | Company | `EEA Company - Full (3.0)` |
| European Union | Sole trader | `EEA Sole Trader - Full (3.0)` |
| United States | Company | `US Company - Full (3.0)` |
| United States | Sole trader | `US Sole Trader - Full (3.0)` |

> **Information**
>
> You can only set `profile.mccs` and either `company.principal_address.country` or `individual.principal_address.country` (depending on the platform type) 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

**Company - Lite**

```json
{
  "reference": "CAKE12345",
  "contact_details": {
    "phone": {
      "number": "7700900000"
    },
    "email_addresses": {
      "primary": "hello@thecakeshop.com"
    }
  },
  "profile": {
    "urls": [ "https://www.thecakeshop.com" ],
    "mccs": [ "5814" ]
  },
  "company": {
    "business_registration_number": "12345678",
    "legal_name": "The Cake Shop Inc.",
    "trading_name": "The Cake Shop",
    "principal_address": {
      "address_line1": "654 Example St.",
      "city": "Edinburgh",
      "zip": "EH9 2XY",
      "country": "GB"
    },
    "registered_address": {
      "address_line1": "123 High St.",
      "city": "London",
      "zip": "W1T4TJ",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "representatives": [
      {
        "first_name": "Ali",
        "last_name": "Farid",
        "address": {
          "country": "GB"
        }
      }
    ]
  }
}
```

**Sole trader - Lite**

```json
{
  "reference": "DONUTS12345",
  "contact_details": {
    "phone": {
      "number": "7700900000"
    },
    "email_addresses": {
      "primary": "ali.farid@example.com"
    }
  },
  "profile": {
    "urls": ["https://www.ali-donuts.com"],
    "mccs": ["5814"]
  },
  "individual": {
    "first_name": "Ali",
    "last_name": "Farid",
    "trading_name": "Ali's Donuts",
    "national_tax_id": "1234567",
    "registered_address": {
      "address_line1": "123 High St.",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    }
  }
}
```

**Company - Full**

```json
{
  "reference": "cakeshop678910",
  "contact_details": {
    "phone": {
      "number": "111222333"
    },
    "email_addresses": {
      "primary": "hello@thecakeshop.com"
    }
  },
  "profile": {
    "urls": ["https://www.thecakeshop.com"],
    "mccs": ["5814"]
  },
  "company": {
    "legal_name": "The Cake Shop Inc.",
    "trading_name": "The Cake Shop",
    "principal_address": {
      "address_line1": "90 Tottenham Court Road",
      "city": "London",
      "zip": "W1T4TJ",
      "country": "GB"
    }
  }
}
```

**Sole trader - Full**

```json
{
  "reference": "cakeshop0123456",
  "contact_details": {
    "phone": {
      "number": "2345678910"
    },
    "email_addresses": {
      "primary": "hello@thecakeshop.com"
    }
  },
  "profile": {
    "urls": ["https://www.daniels-donuts.com"],
    "mccs": ["5814"]
  },
  "individual": {
    "first_name": "Daniel",
    "last_name": "Yubi",
    "trading_name": "Daniel's Donuts",
    "national_tax_id": "1234567",
    "registered_address": {
      "address_line1": "90 Tottenham Court Road",
      "city": "London",
      "zip": "W1T4TJ",
      "country": "GB"
    }
  }
}
```

### Response examples

You can receive one of the following HTTP responses:

- `201` – Application submitted successfully
- `409` – Conflict
- `422` – Invalid data was sent

#### 201 – Application submitted successfully

**Lite**

```json
{
  "id": "ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
  "reference": "0123456",
  "status": "pending",
  "capabilities": {
    "payments": {
      "available": true,
      "enabled": false
    },
    "payouts": {
      "available": false,
      "enabled": false
    }
  },
  "requirements_due": [],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_vv2jjkuf2gzj5tcw2x7ptua7zy"
    }
  }
}
```

A successful response returns:

- `id` field – The sub-entity ID, which you need for future requests.

- `capabilities` object – Indicates whether the sub-entity’s capabilities are enabled. Capabilities are only enabled after the sub-entity passes the verification checks.

- `status` field – The status is `pending`, while awaiting the verification checks. For a list of all possible statuses, see [Sub-entity status](https://www.checkout.com/docs/platforms/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.

**Full**

```json
{
  "id": "ent_nofjig36ypra6236f4tfm5bvui",
  "reference": "678910",
  "status": "requirements_due",
  "capabilities": {
    "payments": {
      "enabled": false
    },
    "payouts": {
      "enabled": false
    }
  },
  "requirements_due": [
    {
      "field": "company.representatives[0].identification.document",
      "reason": "required"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_nofjig36ypra6236f4tfm5bvui"
    }
  }
}
```

A successful response returns:

- `id` field – The sub-entity ID, which you need for future requests.

- `capabilities` object – Indicates whether the sub-entity’s capabilities are enabled. Capabilities are only enabled after the sub-entity passes the verification checks.

- `status` field – The status is `requirements_due`. You must now [add supporting documentation](https://www.checkout.com/docs/platforms/onboard-sub-entities/add-supporting-documents.md) so that Checkout.com can start the verification checks.

For all possible statuses, see [Sub-entity status](https://www.checkout.com/docs/platforms/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 alphanumeric value . 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 have provided all required fields in your request.

The response also returns an `error_codes` array with one or more specific errors. For more information, see [Possible error codes](https://www.checkout.com/docs/platforms/onboard-sub-entities/submit-application/onboard-with-the-api.md#Possible_error_codes).

---

## Possible error codes

You can receive the following error codes when onboarding a sub-entity:

| Error code | Description |
| --- | --- |
| `profile_mccs_invalid_for_processing_scope` | The Merchant Category Codes (MCC) you provided for the sub-entity are outside your platforms's processing scope. |
| `profile_default_holding_currency_invalid_for_currency_scope` | The default holding currency you provided for the sub-entity is outside your platform's currency scope. |
| `principal_address_country_invalid_for_processing_scope` | The principal address country you provided for the sub-entity is outside your platform's processing scope. |
| `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 your 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). |
| `<field_name>_invalid` | The specified field has uses invalid formatting, or an invalid minimum or maximum length. <br><br>For example, `legal_name_invalid`, or `profile_urls_0_invalid`.<br><br>The exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`.<br><br>You must provide the `company` or `individual` object in your request. |
| `<field_name>_required` | The specified field is required, but was not provided in the request. <br><br>For example, `legal_name_required` or `representatives_0_first_name_required`.<br><br>The field can be `null`, contain empty strings, or contain white spaces. |

---

## Test your integration

You can test your integration by simulating different onboarding scenarios in the sandbox environment by 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-payfac/onboard-sub-entities/add-supporting-documents.md)**

For Full accounts, add supporting documents for sub-entity verification.