# Update a sub-entity

You may need to update a sub-entity because some of their details have changed, your sub-entity encounters issues when submitting their application, or to fulfill specific verification requirements.

You can update a sub-entity using the Dashboard, or the API.

> **Information**
>
> When you update a sub-entity, we may conduct further verification checks when necessary. During these checks, your payment and payout capabilities will remain unchanged.

---

## Update a sub-entity in the Dashboard

1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Go to _Sub-entities_.
3. On the _Sub-entities_ page, select the sub-entity to edit.
4. On the _Activity_ page, select _Manage account_.
5. On the _Manage account_ page, select _Edit business details_.
5. On the _Account Activation_ page, edit the required details and select _Update_.

---

## Update a sub-entity using the API

You can update the fields under the `contact_details`, `profile`, and `company` objects.

> **Note**
>
> The `profile.default_holding_currency` field is not currently updatable. If you need to change it, [contact support](https://dashboard.checkout.com/support/).

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 - 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": "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": "hello@thecakeshop.com"
    }
  },
  "profile": {
    "urls": ["https://www.alis-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"
    },
    "date_of_birth": {
      "day": 5,
      "month": 6,
      "year": 1995
    }
  }
}
```

**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": {
    "business_registration_number": "452349600005",
    "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"
    },
    "registered_address": {
      "address_line1": "90 Tottenham Court Road",
      "city": "London",
      "zip": "W1T4TJ",
      "country": "GB"
    },
    "representatives": [
      {
        "first_name": "Chrisi",
        "last_name": "Webster",
        "address": {
          "address_line1": "123 ABC Close",
          "city": "London",
          "zip": "E1 5DP",
          "country": "GB"
        },
        "date_of_birth": {
          "day": 5,
          "month": 6,
          "year": 1995
        },
        "identification": {
          "document": {
            "type": "Passport",
            "front": "file_jxaps37jnfaupfu6bsei7rj5iu",
            "back": "file_zn6v47bgphjuljjvhlpk7dnpby"
          }
        }
      }
    ]
  }
}
```

**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"
    },
    "date_of_birth": {
      "day": 5,
      "month": 6,
      "year": 1995
    },
    "identification": {
      "document": {
        "type": "Passport",
        "front": "file_jxaps37jnfaupfu6bsei7rj5iu"
      }
    }
  }
}
```

### 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

**Lite**

If the request is successful, you receive a `200 - Sub-entity updated successfully` response.

```json
{
  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "reference": "CAKE12345",
  "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_wxglze3wwywujg4nna5fb7ldli"
      }
    }
  }
}
```

**Full**

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 have been completed. If you have not received a webhook – either `{check}_passed` or `{check}_failed` – it is likely there are outstanding requirements due. See [verification requirements](https://www.checkout.com/docs/platforms/onboard-sub-entities/collect-verification-information.md) to confirm you have sent all the required information.
>
> <br>If you have provided all the information, we may be completing a manual review.

#### 422 - Invalid data was sent

In case of any issues in your 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 that specifies the exact error. 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 the processing scope of the platform. |
| `principal_address_country_invalid_for_processing_scope` | The principal address country provided for the sub-entity is outside the processing scope of the platform. |
| `company_or_individual_required` | The `company` or `individual` is missing in your 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. |
| `<field_name>_invalid`<br>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 your request.<br>The only two exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`, which have different causes. |
| `<field_name>_required`<br>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. |

## Update a sub-entity in a hosted onboarding flow

If you're using the hosted onboarding flow, and your sub-entity encounters issues when submitting their application, or is missing required [verification](https://www.checkout.com/docs/platforms/onboard-sub-entities/collect-verification-information.md) information, you can update the sub-entity's details yourself using the API.

> **Note**
>
> You can only use the API to complete the sub-entity's application on their behalf, as the application is not accessible from the Dashboard.

To update a sub-entity in a hosted onboarding flow:

1. 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.
2. Make the required changes to the fields in the API request.
3. Depending on how you want the application to be submitted, set the `is_draft` field to one of the following:
    - `true` -  To allow the sub-entity to submit the application themselves at a later time.
    - `false` - To submit the application on the sub-entity's behalf.

> **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 example

```json
{
  "reference": "acme0123456",
  "is_draft": false,
  "contact_details": {
    "invitee": {
      "email": "jane.smith@example.com"
    },
    "phone": {
      "number": "1234567890"
    },
    "email_addresses": {
      "primary": "jane.smith@example.com"
    }
  },
  "profile": {
    "urls": ["https://www.acme-corp.com"],
    "mccs": ["5814"]
  },
  "individual": {
    "first_name": "Jane",
    "last_name": "Smith",
    "trading_name": "Acme Corporation",
    "national_tax_id": "1234567",
    "registered_address": {
      "address_line1": "123 High St.",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "date_of_birth": {
      "day": 1,
      "month": 1,
      "year": 1990
    }
  }
}
```

### Response example

```json
{
  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "reference": "acmeCorp1234",
  "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_wxglze3wwywujg4nna5fb7ldli"
      }
    }
  }
}
```