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

# Create an incorporation

> Begin an incorporation for one of your customers.

Starts an incorporation for one of your customers.

The response returns the incorporation resource directly, plus `incorporationValidation`, current requirements, and `intakeState`. If no initial intake values are supplied, `intakeState.currentState` is `{}`.

For a complete Singapore walkthrough with the IDs to save, see [Build an incorporation flow](/engine/incorporation/partner-incorporation-build-flow).

## Request shape

Create requests use a `country` plus country-specific `countryOptions` instead of a flat product id.

* `country` is the ISO 3166-1 alpha-2 code for the jurisdiction.
* `countryOptions` is an object whose shape depends on `country`.
* `customerId` is the path parameter for the customer that owns the incorporation.
* `intake.requirements` is optional and can contain initial partial intake data.
* Unknown or unsupported options are rejected by this endpoint.

## Singapore example

```json theme={null}
{
  "country": "SG",
  "countryOptions": {
    "corporationType": "PRIVATE_LIMITED_COMPANY"
  }
}
```

Use `GET /partner/incorporation/jurisdiction-catalog` to see currently supported countries and option values. Use `GET /partner/incorporation/requirements` before building an intake UI.

## Initial partial intake example

```json theme={null}
{
  "country": "SG",
  "countryOptions": {
    "corporationType": "PRIVATE_LIMITED_COMPANY"
  },
  "intake": {
    "requirements": {
      "companyNameOptions": [
        { "name": "Acme SG Pte Ltd" }
      ]
    }
  }
}
```

## Supported options

| Country          | Required options                                    | Optional options                                                  |
| ---------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| `US`             | `corporationType`: `CORPORATION`, `LLC`             | `state`: US state abbreviation                                    |
| `CA`             | `corporationType`: `CORPORATION`                    | None                                                              |
| `IN`             | `corporationType`: `LLP`, `PRIVATE_LIMITED_COMPANY` | None                                                              |
| `AE`             | `corporationType`: `FZC`                            | `corporationTypeOptions.freeZone`: `ADGM`, `DIFC`, `DMCC`, `IFZA` |
| `GB`, `IE`, `NZ` | `corporationType`: `LIMITED_COMPANY`                | None                                                              |
| `KY`             | `corporationType`: `EXEMPTED_COMPANY`               | None                                                              |
| `SG`             | `corporationType`: `PRIVATE_LIMITED_COMPANY`        | None                                                              |

## Response status

New incorporations are returned with `incorporationStatus: "AWAITING_CUSTOMER_INPUT"`. Once required intake data, participant roles, and documents validate, call `POST /partner/incorporation/{incorporationId}/submit`; after submit succeeds, the status becomes `SUBMITTED` or `IN_PROGRESS` depending on workflow start state.


## OpenAPI

````yaml POST /partner/incorporation/customers/{customerId}/incorporations
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/customers/{customerId}/incorporations:
    post:
      summary: Create an incorporation
      description: Begin an incorporation for one of your customers.
      operationId: createPartnerIncorporation
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Customer that should own the incorporation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PartnerCreateCustomerScopedIncorporationRequest
            examples:
              singaporePrivateLimited:
                summary: Singapore private limited company
                value:
                  country: SG
                  countryOptions:
                    corporationType: PRIVATE_LIMITED_COMPANY
      responses:
        '201':
          description: Incorporation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationResponse'
        '400':
          description: Unsupported country or invalid country options
          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: Customer is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    PartnerCreateCustomerScopedIncorporationRequest:
      type: object
      required:
        - country
        - countryOptions
      properties:
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        countryOptions:
          $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
        intake:
          type: object
          description: Optional initial partial intake data.
          properties:
            requirements:
              $ref: '#/components/schemas/PartnerIncorporationRequirementValues'
    PartnerIncorporationResponse:
      type: object
      required:
        - incorporation
        - incorporationValidation
        - intakeState
        - participants
      properties:
        incorporation:
          $ref: '#/components/schemas/PartnerIncorporation'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirements'
        intakeState:
          $ref: '#/components/schemas/PartnerIncorporationIntakeState'
          description: >-
            Current intake state for the incorporation. Always returned; an
            empty intake state is initialized automatically when one does not
            yet exist.
        participants:
          type: array
          description: >-
            Participants registered to this incorporation, when requested or
            available.
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipant'
    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
    PartnerIncorporationCountry:
      type: string
      description: ISO 3166-1 alpha-2 country code for the incorporation jurisdiction.
      example: SG
      enum:
        - AE
        - CA
        - GB
        - IE
        - IN
        - KY
        - NZ
        - SG
        - US
    PartnerIncorporationCountryOptions:
      type: object
      description: >-
        Country-specific incorporation options. Use the jurisdiction catalog for
        the currently supported fields and values.
      additionalProperties: true
      example:
        corporationType: PRIVATE_LIMITED_COMPANY
    PartnerIncorporationRequirementValues:
      type: object
      description: Partner-submitted requirement values keyed by requirements field keys.
      additionalProperties: true
      example:
        companyNameOptions:
          - name: Acme SG Pte Ltd
          - name: Acme Asia Pte Ltd
          - name: Acme Global Pte Ltd
        registeredOfficeAddressSource: commendaService
    PartnerIncorporation:
      type: object
      required:
        - id
        - customerId
        - country
        - countryOptions
        - incorporationStatus
        - createdAt
        - updatedAt
        - businessEntityId
      properties:
        id:
          type: string
          description: Incorporation identifier.
          example: 0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91
        customerId:
          type: integer
          description: Customer that owns the incorporation.
          example: 77
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        countryOptions:
          $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
        incorporationStatus:
          $ref: '#/components/schemas/PartnerIncorporationStatus'
        createdAt:
          type: string
          format: date-time
          example: '2026-04-21T17:10:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-04-21T17:10:00.000Z'
        businessEntityId:
          type: integer
          nullable: true
          description: >-
            Target Commenda business entity id for the entity being
            incorporated. Corporate shareholder business entity ids are separate
            participant resource ids.
          example: 44
    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'
    PartnerIncorporationRequirements:
      type: object
      description: >-
        Requirements schema for the selected incorporation. Clients can use this
        to render their own intake UI, but intake updates are always validated
        against the current server-side incorporation requirements.
      additionalProperties: true
      example:
        schemaVersion: '2026-04-22'
        dslVersion: mvp-2026-04-22
        key: sg.private_limited_company
        country: SG
        countryOptions:
          corporationType: PRIVATE_LIMITED_COMPANY
        name: Singapore Private Limited Company Incorporation Requirements
        blocks:
          - key: companyNames
            name: Company name options
        participantRequirements:
          - key: directors
            name: Directors
            role: DIRECTOR
            allowedParticipantTypes:
              - INDIVIDUAL
            allowedResourceTypes:
              - KEY_PERSON
            resourceFieldsByParticipantType:
              INDIVIDUAL:
                - kind: resource
                  key: residentialAddress
                  name: Residential address
                  description: >-
                    The key person's current residential address. Store this on
                    the Commenda OS person as residentialAddress.
                  required: true
                  resourceKind: address
                  commendaOs:
                    entity: keyPerson
                    field: residentialAddress
                  fields:
                    - kind: scalar
                      key: addressLine1
                      name: Address line 1
                      required: true
                      commendaOs:
                        entity: keyPerson
                        field: residentialAddress.addressLine1
                    - kind: scalar
                      key: city
                      name: City
                      required: true
                      commendaOs:
                        entity: keyPerson
                        field: residentialAddress.city
                    - kind: scalar
                      key: country
                      name: Country
                      required: true
                      commendaOs:
                        entity: keyPerson
                        field: residentialAddress.country
            documentRequirements:
              - documentKind: PASSPORT_SCAN
                name: Passport scan
              - documentKind: UTILITY_BILL
                name: Utility bill
    PartnerIncorporationIntakeState:
      type: object
      required:
        - id
        - incorporationId
        - currentState
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: state_123
        incorporationId:
          type: string
          example: 0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91
        currentState:
          $ref: '#/components/schemas/PartnerIncorporationRequirementValues'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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
    PartnerIncorporationStatus:
      type: string
      description: Current top-level lifecycle status for the incorporation.
      enum:
        - AWAITING_CUSTOMER_INPUT
        - SUBMITTED
        - IN_PROGRESS
        - BLOCKED
        - COMPLETED
    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
    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
    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'
    PartnerIncorporationDocumentKind:
      type: string
      description: Type of document linked to an incorporation participant.
      enum:
        - PASSPORT_SCAN
        - UTILITY_BILL
    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
    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

````