Skip to main content
POST
/
partner
/
incorporation
/
{incorporationId}
/
participants
Register an incorporation participant
curl --request POST \
  --url https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 12
  },
  "roles": [
    {
      "role": "DIRECTOR"
    },
    {
      "role": "SHAREHOLDER",
      "ownershipPercentage": 100
    }
  ]
}
'
{
  "participant": {
    "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"
      }
    ]
  },
  "incorporationValidation": {
    "isComplete": false,
    "missingRequirements": [
      {
        "code": "PARTICIPANT_DOCUMENT_REQUIRED",
        "path": "participants.participant_123.documents.PASSPORT_SCAN",
        "message": "Participant participant_123 requires a PASSPORT_SCAN document",
        "participantId": "participant_123",
        "documentKind": "PASSPORT_SCAN",
        "displayName": "Jane Founder"
      }
    ],
    "invalidRequirements": [
      {
        "code": "PARTICIPANT_DOCUMENT_REQUIRED",
        "path": "participants.participant_123.documents.PASSPORT_SCAN",
        "message": "Participant participant_123 requires a PASSPORT_SCAN document",
        "participantId": "participant_123",
        "documentKind": "PASSPORT_SCAN",
        "displayName": "Jane Founder"
      }
    ]
  }
}

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.

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 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. 
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 12
  },
  "roles": [
    {
      "role": "DIRECTOR"
    },
    {
      "role": "SHAREHOLDER",
      "ownershipPercentage": 100
    }
  ]
}
The response returns the registered participant and the refreshed 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 scenarioparticipantTyperesource.resourceTypeSupported role payloadOwnershipDocuments
Individual directorINDIVIDUALKEY_PERSON{ "role": "DIRECTOR" }Not applicablePASSPORT_SCAN and UTILITY_BILL when required.
Individual shareholderINDIVIDUALKEY_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 shareholderINDIVIDUALKEY_PERSONInclude 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 shareholderCORPORATEBUSINESS_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 directorCORPORATEBUSINESS_ENTITYNot supported for Singapore private limited companies.Not applicableNot applicable.
Create individual resources with 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: 
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 12
  },
  "roles": [
    { "role": "DIRECTOR" }
  ]
}
Shareholder only: 
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 13
  },
  "roles": [
    {
      "role": "SHAREHOLDER",
      "ownershipPercentage": 40
    }
  ]
}
Corporate shareholder: 
{
  "participantType": "CORPORATE",
  "resource": {
    "resourceType": "BUSINESS_ENTITY",
    "resourceId": 44
  },
  "roles": [
    {
      "role": "SHAREHOLDER",
      "ownershipPercentage": 60
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
incorporationId
string
required

Incorporation identifier returned by create or list endpoints.

Body

application/json
​
participantType
enum<string>
required

Type of reusable Commenda OS resource registered to the incorporation.

Available options:
INDIVIDUAL,
CORPORATE
​
resource
object
required
​
roles
object[]
required
Minimum array length: 1

Response

Participant registered successfully

​
participant
object
required
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"
    }
  ]
}
​
incorporationValidation
object
required