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

# Register an incorporation participant

> Register an existing Commenda OS person or business entity as a participant in an incorporation, including details about their role.

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.

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

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

Shareholder only:

```json theme={null}
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 13
  },
  "roles": [
    {
      "role": "SHAREHOLDER",
      "ownershipPercentage": 40
    }
  ]
}
```

Corporate shareholder:

```json theme={null}
{
  "participantType": "CORPORATE",
  "resource": {
    "resourceType": "BUSINESS_ENTITY",
    "resourceId": 44
  },
  "roles": [
    {
      "role": "SHAREHOLDER",
      "ownershipPercentage": 60
    }
  ]
}
```


## OpenAPI

````yaml POST /partner/incorporation/{incorporationId}/participants
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:
    post:
      summary: Register an incorporation participant
      description: >-
        Register an existing Commenda OS person or business entity as a
        participant in an incorporation, including details about their role.
      operationId: registerPartnerIncorporationParticipant
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerRegisterParticipantRequest'
      responses:
        '201':
          description: Participant registered successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PartnerIncorporationParticipantMutationResponse
        '400':
          description: >-
            Malformed participant registration payload, invalid
            participant/resource/role combination, missing shareholder ownership
            percentage, or shareholder ownership exceeding the selected
            requirements total
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation or referenced Commenda OS resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    PartnerRegisterParticipantRequest:
      type: object
      required:
        - participantType
        - resource
        - roles
      properties:
        participantType:
          $ref: '#/components/schemas/PartnerIncorporationParticipantType'
        resource:
          $ref: '#/components/schemas/PartnerIncorporationParticipantResource'
        roles:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantRole'
      example:
        participantType: INDIVIDUAL
        resource:
          resourceType: KEY_PERSON
          resourceId: 12
        roles:
          - role: DIRECTOR
          - role: SHAREHOLDER
            ownershipPercentage: 100
    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
    PartnerIncorporationParticipantType:
      type: string
      description: Type of reusable Commenda OS resource registered to the incorporation.
      enum:
        - INDIVIDUAL
        - CORPORATE
    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
    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

````