--- title: "Update a sub-entity's representatives" method: PUT path: "/accounts/entities/{id}/representatives" tags: ["Representatives"] --- # Update a sub-entity's representatives `PUT /accounts/entities/{id}/representatives` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/accounts/entities/{id}/representatives` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `accounts` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Submit a change to the representatives of one of your sub-entities, onboarded through our Platforms solution. Use this endpoint to add, update, or remove representatives. This endpoint opens a change request for review. The sub-entity keeps its current representatives until the review completes, and the response returns the list you submitted with a `pending` status. Provide the complete list of representatives, built from a recent `GET` request. Include a representative with its `id` and all its details to keep or update it, without an `id` to add it, or leave it out to remove it. To replace a company's only authorised signatory, add the new one and remove the old one in the same request. You cannot change an existing representative's `individual.date_of_birth` or `individual.place_of_birth.country`. To correct either, remove the representative and add them again without an `id`. You can have only one change under review at a time. You cannot currently amend a change after you submit it. Until the change has been assessed, a further `PUT` request returns `409`. To retrieve the change in progress, send a `GET` request with `status=pending`. If you submitted an incorrect list, wait for the assessment outcome and submit the corrected list as a new change, or resolve any requirements the assessment raises, which you can retrieve from `GET /accounts/entities/{id}/requirements`. Support for amending a change that is under review is planned. ## Path parameters - `id` string, required ## Request body - SubEntityRepresentatives: The representatives of a sub-entity. Only individuals are supported. - `status` 'active' | 'pending': The status of the representatives. This describes the data in this response, not the sub-entity's own status. `active` means the list is live. `pending` means a change has been submitted and is still under review, so the list shown is the one you submitted, not the one currently in effect. Read-only on input. You can send a response body back unchanged in a `PUT` request, and this field is ignored. - `representatives` object[], required: The complete list of the sub-entity's representatives. When you submit a change, any current representative you leave out of this list is removed. - `id` string: The representative's unique identifier. Include the `id` to keep or update an existing representative. Leave it out to add a new representative, and an `id` is assigned when you submit the change. - `roles` string[], required: The individual's roles within the company. - `ownership_percentage` integer: The representative's percentage ownership of the company. Provide for representatives with the `ubo` role. - `company_position` 'ceo' | 'cfo' | 'coo' | 'managing_member' | 'general_partner' | 'president' | 'vice_president' | 'treasurer' | 'other_senior_management' | 'other_executive_officer' | 'other_non_executive_non_senior': The representative's position within the company. Provide for representatives with the `control_person` role. - `individual` object, required: The representative's personal details. - `first_name` string, required: The representative's first name. - `middle_name` string: The representative's middle name. Provide if it appears in official documents. - `last_name` string, required: The representative's last name. - `email_address` string, email, required: The representative's email address. - `date_of_birth` object, required: The representative's date of birth according to the Gregorian calendar. Cannot be changed for an existing representative. Include it unchanged when you keep or update the representative. To correct it, remove the representative and add them again without an `id`. - `day` integer, required: The calendar day of the month they were born. - `month` integer, required: The month of the year they were born. - `year` integer, required: The year they were born. - `address` object, required: The representative's residential address. - `address_line1` string, required: The first line of the address. - `address_line2` string: The second line of the address. - `city` string, required: The address city. - `state` string: The address state. For US addresses, provide the two-letter ISO 3166-2 code. - `zip` string, required: The address ZIP code or postal code. - `country` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code. For more information, see Country codes. - `place_of_birth` object, required: The representative's place of birth. - `country` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code. Cannot be changed for an existing representative. Include it unchanged when you keep or update the representative. To correct it, remove the representative and add them again without an `id`. - `citizenships` object[], required: The representative's citizenships or legal statuses. If the representative is a US citizen, `national_id_type` must be `ssn` or `itin`. If they are not a US citizen, provide `documents.identity_verification`. - `type` string: The type of citizenship or legal status. For example, `citizenship` or `residency`. - `country` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code. - `national_id_type` 'ssn' | 'itin' | 'passport' | 'driving_license' | 'national_id_card' | 'residence_permit' | 'other', required: The type of national identification number provided. Must be `ssn` or `itin` for US citizens. - `national_id_number` string, required: When `national_id_type` is `ssn` or `itin`, provide the SSN or ITIN. Otherwise, provide the identifier from the chosen document type. - `phone` object, required: The representative's phone number. - `country_code` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered. - `number` string, required: The phone number, without the country calling code. - `documents` object: The representative's verification documents. - `identity_verification` object: The document used to confirm the representative's identity. Provide if the representative isn't a US citizen. - `type` 'passport' | 'national_identity_card' | 'driving_license' | 'citizen_card' | 'residence_permit' | 'electoral_id', required: The type of document used for identity verification. - `front` string, required: The ID of the front side of the document. - `back` string: The ID of the back side of the document. - `certified_authorised_signatory` object: A power of attorney for a representative with the `authorised_signatory` role. Optional. - `type` 'power_of_attorney', required: The type of document. - `front` string, required: The ID of the front side of the document. ## Response `200` Change submitted successfully and is now under review - SubEntityRepresentatives: The representatives of a sub-entity. Only individuals are supported. - `status` 'active' | 'pending': The status of the representatives. This describes the data in this response, not the sub-entity's own status. `active` means the list is live. `pending` means a change has been submitted and is still under review, so the list shown is the one you submitted, not the one currently in effect. Read-only on input. You can send a response body back unchanged in a `PUT` request, and this field is ignored. - `representatives` object[], required: The complete list of the sub-entity's representatives. When you submit a change, any current representative you leave out of this list is removed. - `id` string: The representative's unique identifier. Include the `id` to keep or update an existing representative. Leave it out to add a new representative, and an `id` is assigned when you submit the change. - `roles` string[], required: The individual's roles within the company. - `ownership_percentage` integer: The representative's percentage ownership of the company. Provide for representatives with the `ubo` role. - `company_position` 'ceo' | 'cfo' | 'coo' | 'managing_member' | 'general_partner' | 'president' | 'vice_president' | 'treasurer' | 'other_senior_management' | 'other_executive_officer' | 'other_non_executive_non_senior': The representative's position within the company. Provide for representatives with the `control_person` role. - `individual` object, required: The representative's personal details. - `first_name` string, required: The representative's first name. - `middle_name` string: The representative's middle name. Provide if it appears in official documents. - `last_name` string, required: The representative's last name. - `email_address` string, email, required: The representative's email address. - `date_of_birth` object, required: The representative's date of birth according to the Gregorian calendar. Cannot be changed for an existing representative. Include it unchanged when you keep or update the representative. To correct it, remove the representative and add them again without an `id`. - `day` integer, required: The calendar day of the month they were born. - `month` integer, required: The month of the year they were born. - `year` integer, required: The year they were born. - `address` object, required: The representative's residential address. - `address_line1` string, required: The first line of the address. - `address_line2` string: The second line of the address. - `city` string, required: The address city. - `state` string: The address state. For US addresses, provide the two-letter ISO 3166-2 code. - `zip` string, required: The address ZIP code or postal code. - `country` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code. For more information, see Country codes. - `place_of_birth` object, required: The representative's place of birth. - `country` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code. Cannot be changed for an existing representative. Include it unchanged when you keep or update the representative. To correct it, remove the representative and add them again without an `id`. - `citizenships` object[], required: The representative's citizenships or legal statuses. If the representative is a US citizen, `national_id_type` must be `ssn` or `itin`. If they are not a US citizen, provide `documents.identity_verification`. - `type` string: The type of citizenship or legal status. For example, `citizenship` or `residency`. - `country` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code. - `national_id_type` 'ssn' | 'itin' | 'passport' | 'driving_license' | 'national_id_card' | 'residence_permit' | 'other', required: The type of national identification number provided. Must be `ssn` or `itin` for US citizens. - `national_id_number` string, required: When `national_id_type` is `ssn` or `itin`, provide the SSN or ITIN. Otherwise, provide the identifier from the chosen document type. - `phone` object, required: The representative's phone number. - `country_code` string, iso-3166-1-alpha-2, required: The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered. - `number` string, required: The phone number, without the country calling code. - `documents` object: The representative's verification documents. - `identity_verification` object: The document used to confirm the representative's identity. Provide if the representative isn't a US citizen. - `type` 'passport' | 'national_identity_card' | 'driving_license' | 'citizen_card' | 'residence_permit' | 'electoral_id', required: The type of document used for identity verification. - `front` string, required: The ID of the front side of the document. - `back` string: The ID of the back side of the document. - `certified_authorised_signatory` object: A power of attorney for a representative with the `authorised_signatory` role. Optional. - `type` 'power_of_attorney', required: The type of document. - `front` string, required: The ID of the front side of the document. ## Other responses - `401`: Unauthorized - `404`: Sub-entity not found - `409`: The sub-entity is not active, or a change to its representatives is already under review - `422`: Unable to process the request. A field is invalid or missing, is not part of this resource, or the list breaks a representative rule. If the list breaks one of these rules, the request fails with a `422` error that names it: - Sole trader – exactly one representative, with only the `ubo` role (`representatives_sole_trader_must_be_single`, `representatives_sole_trader_roles_must_be_ubo_only`). - Company – at least one authorised signatory (`representatives_min_1_authorised_signatory`), at most one control person (`representatives_min_0_max_1_control_person`), and one to four UBOs (`representatives_min_1_max_4_ubo`). A non-profit needs exactly one control person (`representatives_min_1_max_1_control_person`) and up to four UBOs (`representatives_min_0_max_4_ubo`). - Company – UBO ownership totals 100 or less (`representatives_ubo_ownership_exceeds_100`). - No individual appears twice (`representatives_individual_already_exists`), and every `id` belongs to a current representative (`representatives_unknown_id`). - An existing representative's date of birth and country of birth are unchanged (`representatives_date_of_birth_immutable`, `representatives_place_of_birth_country_immutable`). - `national_id_number` is valid for its `national_id_type` (`representatives_national_id_number_invalid`). - `429`: Too many requests - `502`: We could not validate the change because an upstream service was unavailable. No change was created, so you can retry the request --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)