Register an incorporation participant
Participants
Register an incorporation participant
Register an existing Commenda OS person or business entity as a participant in an incorporation, including details about their role.
POST
Register an incorporation participant
Registers a reusable Commenda OS person or business entity as a participant in an incorporation.
Participants are the incorporation-specific layer that assigns roles such as
The response returns the registered participant and the refreshed
Create individual resources with
Shareholder only:
Corporate shareholder:
DIRECTOR and SHAREHOLDER. The underlying person or business entity remains reusable across Commenda OS for customer records, documents, registrations, and other entity-management work.
The resource.resourceId value is the numeric Commenda OS person or business entity id.
incorporationValidation for the incorporation.
Registering a participant does not by itself make the underlying Commenda OS resource complete. The incorporation validation also checks required fields on the referenced person or business entity, such as legal names, email, nationality, date of birth, address, and corporate registration data when those fields are required by the selected jurisdiction.
Role and resource matrix
For Singapore private limited companies, use this matrix when mapping the requirements response into participant registration calls:| Participant scenario | participantType | resource.resourceType | Supported role payload | Ownership | Documents |
|---|---|---|---|---|---|
| Individual director | INDIVIDUAL | KEY_PERSON | { "role": "DIRECTOR" } | Not applicable | PASSPORT_SCAN and UTILITY_BILL when required. |
| Individual shareholder | INDIVIDUAL | KEY_PERSON | { "role": "SHAREHOLDER", "ownershipPercentage": number } | Required for percentage ownership. All shareholders must total 100. | PASSPORT_SCAN and UTILITY_BILL when required. |
| Same individual director and shareholder | INDIVIDUAL | KEY_PERSON | Include both role objects in one roles array. | Shareholder role still needs ownershipPercentage. | One participant record can satisfy both role document requirements once its required documents are upserted. |
| Corporate shareholder | CORPORATE | BUSINESS_ENTITY | { "role": "SHAREHOLDER", "ownershipPercentage": number } | Required for percentage ownership. All shareholders must total 100. | Follow documentRequirements for participantType: "CORPORATE" and resourceType: "BUSINESS_ENTITY" when present. |
| Corporate director | CORPORATE | BUSINESS_ENTITY | Not supported for Singapore private limited companies. | Not applicable | Not applicable. |
POST /partner/commenda-os/customers/{customerId}/persons. Create corporate resources with POST /partner/commenda-os/customers/{customerId}/business-entities.
For Singapore private limited companies, writes that would make shareholder ownership exceed 100 are rejected. Ownership below 100 is accepted while the customer is still entering shareholders, but incorporation validation remains incomplete until the total equals 100.
Use PATCH /partner/incorporation/{incorporationId}/participants/{participantId} to replace an existing participant’s roles or correct ownership percentages.
Role examples
Director only:Authorizations
Path Parameters
Incorporation identifier returned by create or list endpoints.
Body
application/json
Response
Participant registered successfully
Example:
{
"id": "participant_123",
"participantType": "INDIVIDUAL",
"resource": {
"resourceType": "KEY_PERSON",
"resourceId": 12
},
"roles": [
{ "role": "DIRECTOR" },
{
"role": "SHAREHOLDER",
"ownershipPercentage": 100
}
],
"documents": [
{
"documentId": "document_123",
"participantId": "participant_123",
"documentKind": "PASSPORT_SCAN",
"fileId": 456,
"status": "SUBMITTED"
},
{
"documentId": "document_124",
"participantId": "participant_123",
"documentKind": "UTILITY_BILL",
"fileId": 789,
"status": "SUBMITTED"
}
]
}