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

# Submit an incorporation

> Submit a currently complete incorporation for Commenda review. The server refreshes validation before accepting the submit request. `incorporationValidation.isComplete` means eligible to submit; `SUBMITTED` or `IN_PROGRESS` is returned only after this endpoint succeeds.

Submits a complete incorporation and begins Commenda review.

Use this endpoint after the current incorporation state satisfies the incorporation requirements. `incorporationValidation.isComplete` means the incorporation is eligible to submit; it does not move to `SUBMITTED` or `IN_PROGRESS` until you call this endpoint.

This endpoint refreshes validation before accepting the submit request. If required intake fields, participants, ownership totals, or participant documents are still missing or invalid, the request returns `400` and the response includes validation details.

Submit is idempotent for an already-submitted, still-complete incorporation. Retrying submit returns the current incorporation resource instead of starting a second review.

## Incomplete submit response

```json theme={null}
{
  "statusCode": 400,
  "message": "Incorporation intake is incomplete and cannot be submitted for review",
  "error": "Bad Request",
  "incorporationValidation": {
    "isComplete": false,
    "missingRequirements": [
      {
        "code": "PARTICIPANT_REQUIRED",
        "path": "participants.directors",
        "message": "At least one director is required"
      }
    ],
    "invalidRequirements": []
  }
}
```

## Lifecycle effect

```text theme={null}
AWAITING_CUSTOMER_INPUT
  -> SUBMITTED    after POST /submit succeeds and before Commenda review work starts
  -> IN_PROGRESS  when Commenda review is in progress
  -> BLOCKED      when there are active partner-visible issues or review start/runtime failures
  -> COMPLETED    when the incorporation is complete
```


## OpenAPI

````yaml POST /partner/incorporation/{incorporationId}/submit
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}/submit:
    post:
      summary: Submit an incorporation
      description: >-
        Submit a currently complete incorporation for Commenda review. The
        server refreshes validation before accepting the submit request.
        `incorporationValidation.isComplete` means eligible to submit;
        `SUBMITTED` or `IN_PROGRESS` is returned only after this endpoint
        succeeds.
      operationId: submitPartnerIncorporation
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      responses:
        '200':
          description: Incorporation submitted for review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationResponse'
        '400':
          description: Incorporation is incomplete or has invalid requirements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationSubmitError'
        '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 not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    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'
    PartnerIncorporationSubmitError:
      type: object
      required:
        - statusCode
        - message
        - error
        - incorporationValidation
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: >-
            Incorporation intake is incomplete and cannot be submitted for
            review
        error:
          type: string
          example: Bad Request
        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
    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
    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
    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
    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
    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

````