Update an incorporation participant
curl --request PATCH \
--url https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"roles": [
{
"role": "DIRECTOR"
},
{
"role": "SHAREHOLDER",
"ownershipPercentage": 40
}
]
}
'import requests
url = "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}"
payload = { "roles": [
{ "role": "DIRECTOR" },
{
"role": "SHAREHOLDER",
"ownershipPercentage": 40
}
] }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({roles: [{role: 'DIRECTOR'}, {role: 'SHAREHOLDER', ownershipPercentage: 40}]})
};
fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}', 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/{participantId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'roles' => [
[
'role' => 'DIRECTOR'
],
[
'role' => 'SHAREHOLDER',
'ownershipPercentage' => 40
]
]
]),
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/{participantId}"
payload := strings.NewReader("{\n \"roles\": [\n {\n \"role\": \"DIRECTOR\"\n },\n {\n \"role\": \"SHAREHOLDER\",\n \"ownershipPercentage\": 40\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"roles\": [\n {\n \"role\": \"DIRECTOR\"\n },\n {\n \"role\": \"SHAREHOLDER\",\n \"ownershipPercentage\": 40\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"roles\": [\n {\n \"role\": \"DIRECTOR\"\n },\n {\n \"role\": \"SHAREHOLDER\",\n \"ownershipPercentage\": 40\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",
"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"
}
]
}
}{
"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"
}Participants
Update an incorporation participant
Partially update an existing incorporation participant. Use this endpoint to correct director/shareholder roles, shareholder ownership percentages, or to re-point the participant at a different Commenda OS person or business entity. Provide roles, resource, or both. The underlying Commenda OS resource is not modified by this endpoint.
PATCH
/
partner
/
incorporation
/
{incorporationId}
/
participants
/
{participantId}
Update an incorporation participant
curl --request PATCH \
--url https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"roles": [
{
"role": "DIRECTOR"
},
{
"role": "SHAREHOLDER",
"ownershipPercentage": 40
}
]
}
'import requests
url = "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}"
payload = { "roles": [
{ "role": "DIRECTOR" },
{
"role": "SHAREHOLDER",
"ownershipPercentage": 40
}
] }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({roles: [{role: 'DIRECTOR'}, {role: 'SHAREHOLDER', ownershipPercentage: 40}]})
};
fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}', 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/{participantId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'roles' => [
[
'role' => 'DIRECTOR'
],
[
'role' => 'SHAREHOLDER',
'ownershipPercentage' => 40
]
]
]),
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/{participantId}"
payload := strings.NewReader("{\n \"roles\": [\n {\n \"role\": \"DIRECTOR\"\n },\n {\n \"role\": \"SHAREHOLDER\",\n \"ownershipPercentage\": 40\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"roles\": [\n {\n \"role\": \"DIRECTOR\"\n },\n {\n \"role\": \"SHAREHOLDER\",\n \"ownershipPercentage\": 40\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/participants/{participantId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"roles\": [\n {\n \"role\": \"DIRECTOR\"\n },\n {\n \"role\": \"SHAREHOLDER\",\n \"ownershipPercentage\": 40\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",
"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"
}
]
}
}{
"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"
}Partially updates an existing incorporation participant.
Use this endpoint when a customer needs to correct director/shareholder roles, shareholder ownership percentages, or to re-point a participant at a different Commenda OS person or business entity after the participant has already been registered. The underlying Commenda OS resource is not modified by this endpoint.
The new resource must not already be registered as another participant on the same incorporation. Conflicts are rejected with a
For Singapore private limited companies, shareholder ownership may not exceed 100 across registered shareholder participants. Updates below 100 are accepted, but incorporation validation remains incomplete until the shareholder total equals 100.
Request body
Provideroles, resource, or both. At least one of the two fields is required.
| Field | Type | Description |
|---|---|---|
roles | array | Optional. Full replacement set of roles for the participant. When provided, the supplied array fully replaces the existing roles and any omitted roles are removed. |
resource | object | Optional. Reusable Commenda OS resource the participant should reference. Provide resource.resourceType and resource.resourceId to re-point the participant at a different person or business entity. |
Update roles only
Send the full desiredroles array. Omitted roles are removed.
{
"roles": [
{
"role": "DIRECTOR"
},
{
"role": "SHAREHOLDER",
"ownershipPercentage": 40
}
]
}
Update the underlying resource only
Re-point the participant at a different Commenda OS person or business entity while keeping the existing roles in place.{
"resource": {
"resourceType": "KEY_PERSON",
"resourceId": 17
}
}
400 response. The new resource must also be accessible to the partner; otherwise the request is rejected with a 403 response.
Update both at once
{
"resource": {
"resourceType": "KEY_PERSON",
"resourceId": 17
},
"roles": [
{
"role": "DIRECTOR"
}
]
}
Response
The response returns the updated participant and the refreshedincorporationValidation for the incorporation.
{
"participant": {
"id": "participant_123",
"participantType": "INDIVIDUAL",
"resource": {
"resourceType": "KEY_PERSON",
"resourceId": 12
},
"roles": [
{
"role": "DIRECTOR"
},
{
"role": "SHAREHOLDER",
"ownershipPercentage": 40
}
],
"documents": []
},
"incorporationValidation": {
"isComplete": false,
"missingRequirements": [],
"invalidRequirements": [
{
"code": "SHAREHOLDER_OWNERSHIP_TOTAL_INVALID",
"path": "participants.shareholders",
"message": "Shareholders ownershipPercentage values must total 100"
}
]
}
}
Authorizations
Path Parameters
Incorporation identifier returned by create or list endpoints.
Incorporation-specific participant identifier returned by register, list, or read endpoints.
Body
application/json
Partially updates an existing incorporation participant. Provide roles, resource, or both. At least one of the two fields is required. When roles is provided, the supplied array fully replaces the existing roles and any omitted roles are removed. When resource is provided, the participant is re-pointed at a different Commenda OS person or business entity.
Reusable Commenda OS resource the participant should reference. Provide this when correcting which person or business entity is registered as this participant. The new resource must not already be registered as another participant on the same incorporation.
Show child attributes
Show child attributes
Full replacement set of roles for the participant. Omitted roles are removed.
Minimum array length:
1Show child attributes
Show child attributes
Response
Participant updated successfully
Show child attributes
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" } ] }
Show child attributes
Show child attributes
Was this page helpful?