View and manage the representatives of your SaaS seller sub-entities, such as their UBOs, control person, and authorised signatories.
Representatives Operations
View and manage the representatives of your SaaS seller sub-entities, such as their UBOs, control person, and authorised signatories.
Retrieve the representatives of one of your sub-entities, onboarded through our Platforms solution.
Representatives are the individuals disclosed against the sub-entity, such as its ultimate beneficial owners (UBOs), control person, and authorised signatories. If a change to them is under review, this endpoint returns the submitted list with a pending status by default, so you can retrieve a change you've already submitted.
To retrieve the representatives currently in effect while a change is under review, send GET /accounts/entities/{id}/representatives?status=active. To retrieve only a change under review, send GET /accounts/entities/{id}/representatives?status=pending. The pending list includes the documents submitted with the change.
The sub-entity's ID.
The version of the sub-entity's representatives to return. Selects which version the endpoint returns, rather than filtering the list.
Use active to retrieve the representatives currently in effect. This shows you the list a pending change would replace once approved.
Use pending to retrieve the list submitted in a change that is still under review. The request returns 404 if no change is under review.
If you omit this parameter and a change is under review, the endpoint returns the pending list. Otherwise, it returns the active list.
Unauthorized
Sub-entity not found or not yet onboarded, or no change is under review when you request status=pending
Too many requests
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/representatives' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"status": "active",
"representatives": [
{
"id": "rep_76f79595dbdf575d554e41e5aa",
"roles": [
"ubo",
"control_person"
],
"ownership_percentage": 60,
"company_position": "ceo",
"individual": {
"first_name": "Toby",
"last_name": "Arden",
"email_address": "toby.arden@example.com",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"type": "citizenship",
"country": "US"
}
],
"national_id_type": "ssn",
"national_id_number": "123456789",
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Anywhere St.",
"address_line2": "Apt. 456",
"city": "Anytown",
"state": "AL",
"zip": "12345",
"country": "US"
}
}
},
{
"id": "rep_3c1a0b9e4f7d2e8a6b5c4d3e2f",
"roles": [
"authorised_signatory"
],
"individual": {
"first_name": "Hannah",
"last_name": "Bret",
"email_address": "hannah.bret@example.com",
"date_of_birth": {
"day": 22,
"month": 6,
"year": 1985
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"type": "citizenship",
"country": "US"
}
],
"national_id_type": "ssn",
"national_id_number": "987654321",
"phone": {
"country_code": "US",
"number": "4155671234"
},
"address": {
"address_line1": "444 Test Avenue",
"city": "Anytown",
"state": "FL",
"zip": "67890",
"country": "US"
}
}
}
]
}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.
The sub-entity's ID.
The representatives of a sub-entity. Only individuals are supported.
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.
Unauthorized
Sub-entity not found
Too many requests
We could not validate the change because an upstream service was unavailable. No change was created, so you can retry the request
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/representatives' \
--request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"representatives": [
{
"id": "rep_76f79595dbdf575d554e41e5aa",
"roles": [
"ubo",
"control_person"
],
"ownership_percentage": 60,
"company_position": "ceo",
"individual": {
"first_name": "Toby",
"last_name": "Arden",
"email_address": "toby.arden@example.com",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"type": "citizenship",
"country": "US"
}
],
"national_id_type": "ssn",
"national_id_number": "123456789",
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Anywhere St.",
"address_line2": "Apt. 456",
"city": "Anytown",
"state": "AL",
"zip": "12345",
"country": "US"
}
}
},
{
"roles": [
"authorised_signatory"
],
"individual": {
"first_name": "Ali",
"last_name": "Farid",
"email_address": "ali.farid@example.com",
"date_of_birth": {
"day": 3,
"month": 9,
"year": 1988
},
"place_of_birth": {
"country": "GB"
},
"citizenships": [
{
"type": "citizenship",
"country": "GB"
}
],
"national_id_type": "passport",
"national_id_number": "123456789",
"phone": {
"country_code": "US",
"number": "4155679876"
},
"address": {
"address_line1": "444 Test Avenue",
"city": "Anytown",
"state": "FL",
"zip": "67890",
"country": "US"
}
},
"documents": {
"identity_verification": {
"type": "passport",
"front": "file_6lbss42ezvoufcb2beo76rvwly"
}
}
}
]
}'
{
"status": "pending",
"representatives": [
{
"id": "rep_76f79595dbdf575d554e41e5aa",
"roles": [
"ubo",
"control_person"
],
"ownership_percentage": 60,
"company_position": "ceo",
"individual": {
"first_name": "Toby",
"last_name": "Arden",
"email_address": "toby.arden@example.com",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"type": "citizenship",
"country": "US"
}
],
"national_id_type": "ssn",
"national_id_number": "123456789",
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Anywhere St.",
"address_line2": "Apt. 456",
"city": "Anytown",
"state": "AL",
"zip": "12345",
"country": "US"
}
}
},
{
"id": "rep_9d2e7f4a1b8c3d6e5f0a9b8c7d",
"roles": [
"authorised_signatory"
],
"individual": {
"first_name": "Ali",
"last_name": "Farid",
"email_address": "ali.farid@example.com",
"date_of_birth": {
"day": 3,
"month": 9,
"year": 1988
},
"place_of_birth": {
"country": "GB"
},
"citizenships": [
{
"type": "citizenship",
"country": "GB"
}
],
"national_id_type": "passport",
"national_id_number": "123456789",
"phone": {
"country_code": "US",
"number": "4155679876"
},
"address": {
"address_line1": "444 Test Avenue",
"city": "Anytown",
"state": "FL",
"zip": "67890",
"country": "US"
}
},
"documents": {
"identity_verification": {
"type": "passport",
"front": "file_6lbss42ezvoufcb2beo76rvwly"
}
}
}
]
}