> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Participant object

> Field reference for an incorporation-specific participant registration.

The participant object represents a reusable Commenda OS person or business entity registered to one incorporation. The participant stores incorporation-specific roles, ownership data, and linked participant documents. It does not duplicate or replace the underlying Commenda OS resource.

## Attributes

| Attribute               | Type    | Description                                                                                                                                 |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string  | Incorporation-specific participant identifier. Use this value as `{participantId}` when updating or removing the participant.               |
| `participantType`       | string  | Whether the participant represents an `INDIVIDUAL` or `CORPORATE` participant.                                                              |
| `resource`              | object  | Pointer to the reusable Commenda OS resource represented by this participant.                                                               |
| `resource.resourceType` | string  | Type of reusable resource. Supported values are `KEY_PERSON` and `BUSINESS_ENTITY`.                                                         |
| `resource.resourceId`   | integer | Numeric Commenda OS identifier. For `KEY_PERSON`, use a Commenda OS person id. For `BUSINESS_ENTITY`, use a Commenda OS business entity id. |
| `roles`                 | array   | Incorporation roles assigned to this participant.                                                                                           |
| `documents`             | array   | Participant document links attached to this participant.                                                                                    |

## Participant types

| Value        | Meaning                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `INDIVIDUAL` | A natural person registered to the incorporation through a Commenda OS person resource.        |
| `CORPORATE`  | A legal entity registered to the incorporation through a Commenda OS business entity resource. |

## Resource types

| Value             | Use with                        | Description                                                                       |
| ----------------- | ------------------------------- | --------------------------------------------------------------------------------- |
| `KEY_PERSON`      | `participantType: "INDIVIDUAL"` | References a person created or read through the Commenda OS Partner API.          |
| `BUSINESS_ENTITY` | `participantType: "CORPORATE"`  | References a business entity created or read through the Commenda OS Partner API. |

## Roles

Each role object includes a `role` value and, when required, role-specific fields.

| Field                 | Type   | Description                                                                                                                                                                                             |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role`                | string | Role the participant holds in this incorporation. Supported values are `DIRECTOR` and `SHAREHOLDER`.                                                                                                    |
| `ownershipPercentage` | number | Required when the participant has a shareholder role and ownership is represented by percentage. Participant writes are rejected if shareholder ownership would exceed the selected requirements total. |

One participant can hold multiple roles when the same reusable resource satisfies multiple incorporation requirements.

## Documents

The `documents` array contains participant document links created or replaced through [Upsert a participant document](/engine/incorporation/partner-incorporation-participant-documents-PUT).

| Attribute       | Type    | Description                                                                                              |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `documentId`    | string  | Identifier for the participant document link.                                                            |
| `participantId` | string  | Participant this document belongs to.                                                                    |
| `documentKind`  | string  | Type of document linked to the participant. Supported values include `PASSPORT_SCAN` and `UTILITY_BILL`. |
| `fileId`        | integer | Commenda file satisfying this document requirement.                                                      |
| `status`        | string  | Current status of the participant document link. Current value is `SUBMITTED`.                           |

## Endpoints

| Action                   | Endpoint                                                                                                  |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| Register                 | [Register an incorporation participant](/engine/incorporation/partner-incorporation-participants-POST)    |
| List                     | [List incorporation participants](/engine/incorporation/partner-incorporation-participants-GET)           |
| Update roles or resource | [Update an incorporation participant](/engine/incorporation/partner-incorporation-participants-id-PATCH)  |
| Remove                   | [Remove an incorporation participant](/engine/incorporation/partner-incorporation-participants-id-DELETE) |
| Upsert document          | [Upsert a participant document](/engine/incorporation/partner-incorporation-participant-documents-PUT)    |