# Sub-entity status Through its lifecycle, a sub-entity can transition through different statuses that define its payment capabilities. You can check the status of a sub-entity in the responses of the following API calls: - [Onboard a sub-entity](https://api-reference.checkout.com/tag/Platforms/#operation/onboardEntity) - [Retrieve a sub-entity's details](https://api-reference.checkout.com/tag/Platforms/#operation/getSubEntityDetails) - [Update a sub-entity's details](https://api-reference.checkout.com/tag/Platforms/#operation/putSubEntityDetails) You can also view your sub-entity's status in the Dashboard, by following these steps: 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Sub-entities_. 3. Find the required sub-entity in the list. You can use the search bar to search by the sub-entity's name, reference, or ID. 4. Check the status of the sub-entity in the _Status_ column. If you configure your [webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), you're notified of the status update through the [Status changed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/status_changed.md) webhook. Through its lifecycle, your sub-entity can have one of the following statuses: - Pending - Requirements due (_ACTION REQUIRED_ on the Dashboard) - Active - Rejected --- ## Pending We start verification checks only after we have all of the [required information](https://www.checkout.com/docs/platforms/onboard-sub-entities/collect-verification-information.md). Once we start the verification process, the sub-entity's status displays as: - `pending` – in API responses and webhooks - _PENDING_ – in the Dashboard > **Information** > > The outcome of the verification checks may affect the sub-entity's capabilities. --- ## Requirements due If we need additional information before we can start verification checks, the sub-entity's status displays as: - `requirements_due` – in API responses and webhooks - _ACTION REQUIRED_ – in the Dashboard We also send the [Status changed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/status_changed.md) and [Full DD failed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/full_dd_failed.md) webhooks. You can then take action to correct this and run the checks again. You can check the reason for this status either using the Dashboard or the Platforms API. To check the reason in the Dashboard: 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Sub-entities_. 3. Find the required sub-entity in the list. You can use the search bar to search by the sub-entity's name, reference, or ID. Alternatively, use the search filter to filter all sub-entities with the _Action required_ status. 4. Select the sub-entity. The _Sub-entity details_ page displays. The banner at the start of the page highlights the reasons for the Action required status and the actions you need to take. To check the reason using the API, call the [Get entity details](https://api-reference.checkout.com/tag/Platforms/#operation/getEntityDetails) endpoint. ### Response examples ```json { "id": "ent_sea5kqczeqvnznx5lqsbbsnlq4", "reference": "HEjzSLlfjLuvx5l", "status": "requirements_due", "instruments": [], "requirements_due": [ { "field": "company.document", "reason": "required" }, { "field": "company.financial_details.documents.bank_statement", "reason": "required" }, { "field": "company.representatives[0].identification.document", "reason": "document_expired" } ], "contact_details": { "phone": { "number": "1234 567890" } }, "profile": { "default_holding_currency": "GBP", "urls": ["https://www.exampleurl.com"], "mccs": ["5551"] }, "company": { "business_registration_number": "12345678", "legal_name": "Acme Corporation LTD", "trading_name": "Acme Corporation", "principal_address": { "address_line1": "111 Example Road", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "registered_address": { "address_line1": "111 Example Road", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "representatives": [ { "id": "rep_3ipq26zsxt3n24rh2vojjkfez4", "address": { "address_line1": "111 Example Road", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "phone": { "number": "1234 567890" }, "first_name": "Jane", "last_name": "Smith", "date_of_birth": { "day": 5, "month": 6, "year": 1995 }, "place_of_birth": { "country": "GB" }, "identification": { "document": { "type": "passport", "front": "file_a2waebevmihts7s74bie3w3nf4" } } } ] }, "capabilities": { "payments": { "enabled": false, "available": true }, "payouts": { "enabled": false, "available": true }, "issuing": { "enabled": false, "available": false } }, "_links": { "self": { "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_sea5kqczeqvnznx5lqsbbsnlq4" }, "schema": { "href": "https://{prefix}.api.checkout.com/accounts/entities/_schema?resource_type=Entity&type=Company&schema_version=&country=GB" } } } ``` The response returns a `requirements_due` object that lists the affected fields along with the `reason` each field was rejected. The following table lists the possible reasons for the `requirements_due` status, and describes the action you will need to take to continue the checks. | Reason | Action required | | --- | --- | | `required` | The document is required to start verification checks for the first time. Provide the document and resubmit. | | `document_expired` | The document provided is expired. Upload a new identification document for the individual or representative. | | `document_mismatch_submitted_address` | The address you have submitted for the representative is incorrect. Submit the correct address. | | `document_mismatch_submitted_date_of_birth` | The date of birth you have submitted for the representative is incorrect. Submit the correct date of birth. | | `document_mismatch_submitted_individual_name` | The first and/or last name for the representative is incorrect. Submit the correct first and last names. | | `document_submitted_mismatch_ssn` | The social security number (SSN) you have submitted for the representative is incorrect. Submit the correct SSN. | | `document_type_invalid` | The uploaded document is not from the [supported list of documents](https://www.checkout.com/docs/platforms/onboard-sub-entities/collect-verification-information.md). Upload documents that are from the list of document types shown. | | `document_unreadable` | The uploaded document is not readable. Upload documents that are legible, colored, and have all four corners showing. | | `document_unverifiable` | The uploaded document cannot be verified. For further assistance, [request support](https://dashboard.checkout.com/support?topic=case_feedback). | | `invalid_company_document` | The Certificate of Incorporation (COI) or Articles (AOA)/Memorandum of Association (MOA) document does not match the company details provided. Upload a valid company document. | | `invalid_company_name` | The legal company name you have submitted does not match the company verification document. Submit a legal company name that matches the uploaded company verification document. | | `ownership_data_missing` | Your submission is missing company Ultimate Beneficial Owners (UBOs). Submit details of all registered UBOs. | | `unidentified_details` | The individual details, such as address or date of birth, couldn't be verified against our provider databases. Upload an identification document for the individual or representative. | | `verification_failed` | The company details, such as legal name or registered address, couldn't be verified against our provider databases. Upload a new COI. | To add the missing information, you must [update the sub-entity](https://www.checkout.com/docs/platforms/manage-sub-entities/update-a-sub-entity.md). --- ## Active If the sub-entity passes verification checks, the sub-entity's status displays as: - `active` – in API responses and webhooks - _ACTIVE_ – in the Dashboard The sub-entity's payments or payouts capabilities are enabled, as determined by your [account type](https://www.checkout.com/docs/platforms/account-types.md). Active sub-entities don't have any outstanding requirements. > **Note** > > Updating a sub-entity information after verification completes, requires us to run a new verification. During this process, the sub-entity's status resets to `pending`. --- ## Rejected If the sub-entity fails verification checks, it's status displays as: - `rejected` – in API responses and webhooks - _REJECTED_ – in the Dashboard ```json { "id": "ent_sea5kqczeqvnznx5lqsbbsnlq4", "reference": "HEjzSLlfjLuvx5l", "status": "rejected", "instruments": [], "requirements_due": [], "contact_details": { "phone": { "number": "1234 567890" } }, "profile": { "default_holding_currency": "GBP", "urls": ["https://www.exampleurl.com"], "mccs": ["5551"] }, "company": { "business_registration_number": "12345678", "legal_name": "Acme Corporation", "trading_name": "Acme Corporation LTD", "principal_address": { "address_line1": "111 Example Road", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "registered_address": { "address_line1": "111 Example Road", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "representatives": [ { "id": "rep_3ipq26zsxt3n24rh2vojjkfez4", "address": { "address_line1": "111 Example Road", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "phone": { "number": "1234 567890" }, "first_name": "Jane", "last_name": "Smith", "date_of_birth": { "day": 5, "month": 6, "year": 1995 }, "place_of_birth": { "country": "GB" }, "identification": { "document": { "type": "passport", "front": "file_a2waebevmihts7s74bie3w3nf4" } } } ] }, "capabilities": { "payments": { "enabled": false, "available": true }, "payouts": { "enabled": false, "available": true }, "issuing": { "enabled": false, "available": false } }, "_links": { "self": { "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_sea5kqczeqvnznx5lqsbbsnlq4" }, "schema": { "href": "https://{prefix}.api.checkout.com/accounts/entities/_schema?resource_type=Entity&type=Company&schema_version=&country=GB" } } } ``` The sub-entity cannot process payments or payouts. The sub-entity will not be able to resume onboarding. To challenge the decision, contact your account manager. If you attempt to update a rejected sub-entity via the API, you receive a `442` response with the error code `status_invalid`. --- ## Related topics **[Update a sub-entity](https://www.checkout.com/docs/platforms/manage-sub-entities/update-a-sub-entity.md)** Learn how you can update a sub-entity on your platform. **[Handle webhooks](https://www.checkout.com/docs/platforms/onboard-sub-entities/handle-webhooks.md)** Learn about the different webhooks you receive when onboarding sub-entities.