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
    }
  ]
}
'

import requests

url = "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants"

payload = {
    "participantType": "INDIVIDUAL",
    "resource": {
        "resourceType": "KEY_PERSON",
        "resourceId": 12
    },
    "roles": [
        { "role": "DIRECTOR" },
        {
            "role": "SHAREHOLDER",
            "ownershipPercentage": 100
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    participantType: 'INDIVIDUAL',
    resource: {resourceType: 'KEY_PERSON', resourceId: 12},
    roles: [{role: 'DIRECTOR'}, {role: 'SHAREHOLDER', ownershipPercentage: 100}]
  })
};

fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participantType' => 'INDIVIDUAL',
    'resource' => [
        'resourceType' => 'KEY_PERSON',
        'resourceId' => 12
    ],
    'roles' => [
        [
                'role' => 'DIRECTOR'
        ],
        [
                'role' => 'SHAREHOLDER',
                'ownershipPercentage' => 100
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants"

	payload := strings.NewReader("{\n  \"participantType\": \"INDIVIDUAL\",\n  \"resource\": {\n    \"resourceType\": \"KEY_PERSON\",\n    \"resourceId\": 12\n  },\n  \"roles\": [\n    {\n      \"role\": \"DIRECTOR\"\n    },\n    {\n      \"role\": \"SHAREHOLDER\",\n      \"ownershipPercentage\": 100\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participantType\": \"INDIVIDUAL\",\n  \"resource\": {\n    \"resourceType\": \"KEY_PERSON\",\n    \"resourceId\": 12\n  },\n  \"roles\": [\n    {\n      \"role\": \"DIRECTOR\"\n    },\n    {\n      \"role\": \"SHAREHOLDER\",\n      \"ownershipPercentage\": 100\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participantType\": \"INDIVIDUAL\",\n  \"resource\": {\n    \"resourceType\": \"KEY_PERSON\",\n    \"resourceId\": 12\n  },\n  \"roles\": [\n    {\n      \"role\": \"DIRECTOR\"\n    },\n    {\n      \"role\": \"SHAREHOLDER\",\n      \"ownershipPercentage\": 100\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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",
        "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",
        "displayName": "Jane Founder"
      }
    ]
  }
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

POST

partner

incorporation

{incorporationId}

participants

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
    }
  ]
}
'

import requests

url = "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants"

payload = {
    "participantType": "INDIVIDUAL",
    "resource": {
        "resourceType": "KEY_PERSON",
        "resourceId": 12
    },
    "roles": [
        { "role": "DIRECTOR" },
        {
            "role": "SHAREHOLDER",
            "ownershipPercentage": 100
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    participantType: 'INDIVIDUAL',
    resource: {resourceType: 'KEY_PERSON', resourceId: 12},
    roles: [{role: 'DIRECTOR'}, {role: 'SHAREHOLDER', ownershipPercentage: 100}]
  })
};

fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participantType' => 'INDIVIDUAL',
    'resource' => [
        'resourceType' => 'KEY_PERSON',
        'resourceId' => 12
    ],
    'roles' => [
        [
                'role' => 'DIRECTOR'
        ],
        [
                'role' => 'SHAREHOLDER',
                'ownershipPercentage' => 100
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants"

	payload := strings.NewReader("{\n  \"participantType\": \"INDIVIDUAL\",\n  \"resource\": {\n    \"resourceType\": \"KEY_PERSON\",\n    \"resourceId\": 12\n  },\n  \"roles\": [\n    {\n      \"role\": \"DIRECTOR\"\n    },\n    {\n      \"role\": \"SHAREHOLDER\",\n      \"ownershipPercentage\": 100\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participantType\": \"INDIVIDUAL\",\n  \"resource\": {\n    \"resourceType\": \"KEY_PERSON\",\n    \"resourceId\": 12\n  },\n  \"roles\": [\n    {\n      \"role\": \"DIRECTOR\"\n    },\n    {\n      \"role\": \"SHAREHOLDER\",\n      \"ownershipPercentage\": 100\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participantType\": \"INDIVIDUAL\",\n  \"resource\": {\n    \"resourceType\": \"KEY_PERSON\",\n    \"resourceId\": 12\n  },\n  \"roles\": [\n    {\n      \"role\": \"DIRECTOR\"\n    },\n    {\n      \"role\": \"SHAREHOLDER\",\n      \"ownershipPercentage\": 100\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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",
        "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",
        "displayName": "Jane Founder"
      }
    ]
  }
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

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 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.

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

Show child attributes

roles

object[]

required

Minimum array length: 1

Show child attributes

Response

Participant registered successfully

participant

object

required

Show child attributes

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

Show child attributes

Participant object Update an incorporation participant

Overview

Customer setup

Partner Incorporation API

Commenda OS Partner API

Webhooks

Role and resource matrix

Role examples

Authorizations

Path Parameters

Body

Response

​Role and resource matrix

​Role examples

Authorizations

Path Parameters

Body

Response

Role and resource matrix

Role examples