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

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

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.

| 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 desired `roles` array. Omitted roles are removed.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```json theme={null}
{
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 17
  },
  "roles": [
    {
      "role": "DIRECTOR"
    }
  ]
}
```

## Response

The response returns the updated participant and the refreshed `incorporationValidation` for the incorporation.

```json theme={null}
{
  "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.


## OpenAPI

````yaml PATCH /partner/incorporation/{incorporationId}/participants/{participantId}
openapi: 3.0.1
info:
  title: Commenda Public APIs
  description: >-
    APIs for Commenda entity management, partner incorporation, indirect tax,
    compliance, and corporate operations.
  license:
    name: NONE
    url: NONE
  version: 1.0.0
servers:
  - url: https://api.prod.commenda.io/api/v1
    description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
  - url: https://transaction-tax.api.in.commenda.io/api/v1
    description: Global Indirect Tax API.
security:
  - bearerAuth: []
paths:
  /partner/incorporation/{incorporationId}/participants/{participantId}:
    patch:
      summary: Update an incorporation participant
      description: >-
        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.
      operationId: updatePartnerIncorporationParticipant
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: participantId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Incorporation-specific participant identifier returned by register,
            list, or read endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerPatchParticipantRequest'
      responses:
        '200':
          description: Participant updated successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PartnerIncorporationParticipantMutationResponse
        '400':
          description: >-
            Malformed participant update payload, neither `roles` nor `resource`
            provided, invalid role combination, missing shareholder ownership
            percentage, shareholder ownership exceeding the selected
            requirements total, or the supplied resource is already registered
            as another participant on this incorporation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: >-
            Incorporation is not accessible to the partner, or the supplied
            resource is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation or participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    PartnerPatchParticipantRequest:
      type: object
      description: >-
        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.
      properties:
        resource:
          allOf:
            - $ref: '#/components/schemas/PartnerIncorporationParticipantResource'
          description: >-
            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:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantRole'
          description: >-
            Full replacement set of roles for the participant. Omitted roles are
            removed.
      example:
        roles:
          - role: DIRECTOR
          - role: SHAREHOLDER
            ownershipPercentage: 40
    PartnerIncorporationParticipantMutationResponse:
      type: object
      required:
        - participant
        - incorporationValidation
      properties:
        participant:
          $ref: '#/components/schemas/PartnerIncorporationParticipant'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    AffiliatePublicError:
      type: object
      required:
        - statusCode
        - message
        - error
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Company does not belong to this affiliate firm
        error:
          type: string
          example: Forbidden
    PartnerIncorporationParticipantResource:
      type: object
      required:
        - resourceType
        - resourceId
      properties:
        resourceType:
          $ref: '#/components/schemas/PartnerIncorporationParticipantResourceType'
        resourceId:
          type: integer
          description: >-
            Numeric Commenda OS identifier. For `KEY_PERSON`, use the person id
            returned by Commenda OS. For `BUSINESS_ENTITY`, use the business
            entity id.
          example: 12
    PartnerIncorporationParticipantRole:
      type: object
      required:
        - role
      properties:
        role:
          $ref: '#/components/schemas/PartnerIncorporationParticipantRoleName'
        ownershipPercentage:
          type: number
          description: >-
            Required when the participant has a shareholder role and ownership
            is represented by percentage. Participant writes are rejected if
            shareholder ownership would exceed the selected requirements total.
          minimum: 0
          maximum: 100
          example: 100
    PartnerIncorporationParticipant:
      type: object
      required:
        - id
        - participantType
        - resource
        - roles
        - documents
      properties:
        id:
          type: string
          description: Incorporation-specific participant identifier.
          example: participant_123
        participantType:
          $ref: '#/components/schemas/PartnerIncorporationParticipantType'
        resource:
          $ref: '#/components/schemas/PartnerIncorporationParticipantResource'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantRole'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantDocument'
      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
    PartnerIncorporationValidationSummary:
      type: object
      required:
        - isComplete
        - missingRequirements
        - invalidRequirements
      properties:
        isComplete:
          type: boolean
          description: >-
            True when the current intake state satisfies the current
            incorporation requirements and is eligible to submit for review.
          example: false
        missingRequirements:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationValidationIssue'
        invalidRequirements:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationValidationIssue'
    PartnerIncorporationParticipantResourceType:
      type: string
      description: Commenda OS resource type represented by this participant.
      enum:
        - KEY_PERSON
        - BUSINESS_ENTITY
    PartnerIncorporationParticipantRoleName:
      type: string
      description: Role the participant holds in this incorporation.
      enum:
        - DIRECTOR
        - SHAREHOLDER
    PartnerIncorporationParticipantType:
      type: string
      description: Type of reusable Commenda OS resource registered to the incorporation.
      enum:
        - INDIVIDUAL
        - CORPORATE
    PartnerIncorporationParticipantDocument:
      type: object
      required:
        - documentId
        - participantId
        - documentKind
        - fileId
        - status
      properties:
        documentId:
          type: string
          description: Identifier for this participant document link.
          example: document_123
        participantId:
          type: string
          description: Participant this document belongs to.
          example: participant_123
        documentKind:
          $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
        fileId:
          type: integer
          description: Commenda file satisfying this document requirement.
          example: 456
        status:
          $ref: '#/components/schemas/PartnerIncorporationParticipantDocumentStatus'
    PartnerIncorporationValidationIssue:
      type: object
      required:
        - code
        - path
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable validation issue code.
          example: PARTICIPANT_DOCUMENT_REQUIRED
        path:
          type: string
          description: Dot/bracket path for the missing or invalid requirement.
          example: participants.participant_123.documents.PASSPORT_SCAN
        message:
          type: string
          example: Participant participant_123 requires a PASSPORT_SCAN document
        participantId:
          type: string
          description: Included when the issue belongs to a participant.
          example: participant_123
        documentKind:
          $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
        displayName:
          type: string
          description: >-
            Included when available so UIs can render useful labels without
            joining across responses.
          example: Jane Founder
    PartnerIncorporationDocumentKind:
      type: string
      description: Type of document linked to an incorporation participant.
      enum:
        - PASSPORT_SCAN
        - UTILITY_BILL
    PartnerIncorporationParticipantDocumentStatus:
      type: string
      description: Current status of the participant document link.
      enum:
        - SUBMITTED
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````