Skip to main content
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
    }
  ]
}
'
{
  "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"
      }
    ]
  }
}
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.

​
Request body

Provide roles, resource, or both. At least one of the two fields is required.
FieldTypeDescription
rolesarrayOptional. Full replacement set of roles for the participant. When provided, the supplied array fully replaces the existing roles and any omitted roles are removed.
resourceobjectOptional. 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 desired roles 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
  }
}
The new resource must not already be registered as another participant on the same incorporation. Conflicts are rejected with a 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 refreshed incorporationValidation 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"
      }
    ]
  }
}
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.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
incorporationId
string
required

Incorporation identifier returned by create or list endpoints.

​
participantId
string
required

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.

​
resource
object

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.

​
roles
object[]

Full replacement set of roles for the participant. Omitted roles are removed.

Minimum array length: 1

Response

Participant updated 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