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": "keyPerson",
    "resourceId": "12"
  },
  "roles": [
    {
      "role": "director"
    },
    {
      "role": "shareholder",
      "ownershipPercentage": 100
    }
  ]
}
'
{
  "participant": {
    "participantId": "participant_123",
    "participantType": "individual",
    "resource": {
      "resourceType": "keyPerson",
      "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"
      }
    ]
  }
}
Registers a reusable Commenda OS key 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 and can be used by future KYC, e-signature, and document-review workflows. The resource.resourceId value is the numeric Commenda OS person or business entity id encoded as a string. 
{
  "participantType": "individual",
  "resource": {
    "resourceType": "keyPerson",
    "resourceId": "12"
  },
  "roles": [
    {
      "role": "director"
    },
    {
      "role": "shareholder",
      "ownershipPercentage": 100
    }
  ]
}
The response determines which participant roles are required and which document requirements apply to those participants. 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 caseparticipantTyperesource.resourceTypeSupported role payloadOwnershipDocuments
Individual directorindividualkeyPerson{ "role": "director" }Not applicablepassport_scan and utility_bill when required.
Individual shareholderindividualkeyPerson{ "role": "shareholder", "ownershipPercentage": number }Required for percentage ownership. All shareholders must total 100.passport_scan and utility_bill when required.
Same individual director and shareholderindividualkeyPersonInclude 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 linked.
Corporate shareholdercorporatebusinessEntity{ "role": "shareholder", "ownershipPercentage": number }Required for percentage ownership. All shareholders must total 100.Follow documentRequirements for participantType: "corporate" and resourceType: "businessEntity" when present.
Corporate directorcorporatebusinessEntityNot supported for Singapore private limited companies.Not applicableNot applicable.
Create individual resources with POST /partner/commenda-os/companies/{companyId}/persons. Create corporate resources with POST /partner/commenda-os/companies/{companyId}/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": "keyPerson",
    "resourceId": "12"
  },
  "roles": [
    { "role": "director" }
  ]
}
Shareholder only: 
{
  "participantType": "individual",
  "resource": {
    "resourceType": "keyPerson",
    "resourceId": "13"
  },
  "roles": [
    {
      "role": "shareholder",
      "ownershipPercentage": 40
    }
  ]
}
Corporate shareholder: 
{
  "participantType": "corporate",
  "resource": {
    "resourceType": "businessEntity",
    "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:
{
  "participantId": "participant_123",
  "participantType": "individual",
  "resource": {
    "resourceType": "keyPerson",
    "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"
    }
  ]
}