Access1

Address Document Verification8

Agentic Commerce Protocol1

AML Screening2

Apple Pay3

Applicants4

Bacs Direct Debit1

Balances2

Business details2

Card metadata1

Card testing5

Cardholder access tokens1

Cardholders4

Cards11

Compliance requests2

Control groups4

Control profiles7

Controls5

Customers4

Digital cards1

Disputes12

Face Authentication7

Financial actions1

Flow3

Forex1

Forward6

Google Pay4

Hosted Payments Page2

ID Document Verification8

Identity Verification9

Instruments5

Inventory15

Issuing disputes6

Network Tokens4

Onboarding6

Onboarding Simulator5

Out-of-band authentication simulator1

Payment Context2

Payment instruments4

Payment Links2

Payment Methods1

Payment Setups4

Payments11

Payout schedules2

platforms4

Platforms4

Reports3

Representatives2

Standalone5

Standalone Account Updater1

Tokens2

Transactions2

Transfers2

Workflows21

Representatives

Update a sub-entity's representatives

Submit a change to the representatives of one of your sub-entities, onboarded through our <a href="https://www.checkout.com/docs/platforms" target="_blank">Platforms solution</a>. 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.

put/accounts/entities/{id}/representatives

Request

Base URL
https://{prefix}.api.sandbox.checkout.com
Auth
- OAuth 2
  Client credentials
  Token URLstring
  Scopesaccounts
- or API key in header Authorization
TypeScript
https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/accounts/entities/:id/representatives/put.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

idstring required

The sub-entity's ID.

Request body

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.

Example request

{
  "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": "GB"
        },
        "citizenships": [
          {
            "type": "citizenship",
            "country": "GB"
          }
        ],
        "national_id_type": "passport",
        "national_id_number": "987654321",
        "phone": {
          "country_code": "US",
          "number": "4155671234"
        },
        "address": {
          "address_line1": "444 Test Avenue",
          "city": "Anytown",
          "state": "FL",
          "zip": "67890",
          "country": "US"
        }
      },
      "documents": {
        "identity_verification": {
          "type": "passport",
          "front": "file_5h6ss42ezvoufcb2beo76rv4fg"
        }
      }
    }
  ]
}

Response

Change submitted successfully and is now under review