> ## 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 incorporation intake

> Partially update incorporation intake details. Each write returns the updated intake state and incorporation validation summary.

Use this endpoint to save the details required to prepare an incorporation, such as proposed company names, registered office address preference, share capital, and business activities. The available fields depend on the selected country and incorporation options.

Each request can be partial. Include only the values you want to add or change in `requirements`. Commenda merges them into the current intake state, validates the full incorporation, and returns the updated `intakeState` plus `incorporationValidation`.

The Partner API does not expose a submission history endpoint. To read progress after an update, call `GET /partner/incorporation/{incorporationId}` or `GET /partner/incorporation/{incorporationId}/validation`.

The incorporation is ready to submit when `incorporationValidation.isComplete` is `true`. Call `POST /partner/incorporation/{incorporationId}/submit` to hand the incorporation to Commenda for review.

Participant roles, participant resource fields, and participant documents are managed outside this intake payload. Register participant roles with the participant endpoints, complete required person or business entity fields through the Commenda OS Partner API, and upsert participant documents through the document endpoint.

## Accepted requirement keys

`requirements` only accepts incorporation-level requirement keys defined under `blocks[].fields` in the [requirements response](/engine/incorporation/partner-incorporation-requirements-GET) for the current incorporation type.

If you send a key that is not declared at the incorporation level, the request returns `400 Bad Request` with an `Unknown intake requirement key(s)` message and the intake state is not updated. This includes participant-shaped payloads such as `participants`, `directors`, `shareholders`, top-level `residentialAddress`, or a nested `resource` object. Submit those values through the appropriate endpoint instead:

| Payload shape                                           | Where to submit                                                                                                                                                                                                    |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Participant roles such as `directors` or `shareholders` | [Register an incorporation participant](/engine/incorporation/partner-incorporation-participants-POST) or [Update an incorporation participant](/engine/incorporation/partner-incorporation-participants-id-PATCH) |
| Person resource fields such as `residentialAddress`     | [Update a partner person](/engine/partner-api/conventions) using `PATCH /partner/commenda-os/customers/{customerId}/persons/{personId}`                                                                            |
| Participant documents such as `PASSPORT_SCAN`           | [Upsert a participant document](/engine/incorporation/partner-incorporation-participant-documents-PUT)                                                                                                             |

This validation runs before the intake state is merged, so rejected payloads cannot leave stale participant-shaped values behind in `currentState`.

## Intake fields

Use this endpoint for incorporation-level requirements such as company name options and registered office address choice.

### Company name options

Submit preferred legal names under `companyNameOptions`.

```json theme={null}
{
  "requirements": {
    "companyNameOptions": [
      { "name": "Acme Holdings" },
      { "name": "Acme Global" },
      { "name": "Acme Ventures" }
    ]
  }
}
```

### Registered office address

Most incorporations require a registered office address. Choose how that address should be satisfied with `registeredOfficeAddressSource`.

| Source                    | Use when                                                                              | Required fields                                                       |
| ------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `commendaService`         | Commenda should provide the registered office address service for this incorporation. | `registeredOfficeAddressSource`                                       |
| `partnerProvidedLocation` | You already have a Commenda OS location to use as the registered office address.      | `registeredOfficeAddressSource` and `registeredOfficeAddressLocation` |

Use `commendaService` when Commenda should provide the registered office address service:

```json theme={null}
{
  "requirements": {
    "registeredOfficeAddressSource": "commendaService"
  }
}
```

Use `partnerProvidedLocation` when you are providing a reusable Commenda OS location:

```json theme={null}
{
  "requirements": {
    "registeredOfficeAddressSource": "partnerProvidedLocation",
    "registeredOfficeAddressLocation": {
      "mode": "existingResource",
      "resourceId": "location_001"
    }
  }
}
```

The referenced location must be attached to a Commenda OS business entity on the same customer record as the incorporation. If the existing location is missing a field required by the current incorporation requirements, you can include supplemental `data` on the `existingResource` reference for incorporation validation.

If you later switch `registeredOfficeAddressSource` back to `commendaService`, any previously submitted `registeredOfficeAddressLocation` value may remain in `currentState`, but it is no longer applicable and will not block validation.

## Validation notes

Country-specific validation rules are determined by the current incorporation requirements.

If a selected incorporation requires shareholder ownership totals, address details, participant resource fields, or participant documents, the response returns `missingRequirements` and `invalidRequirements` until the current incorporation state satisfies those rules.

Example validation details:

```json theme={null}
{
  "incorporationValidation": {
    "isComplete": false,
    "missingRequirements": [
      {
        "code": "PARTICIPANT_REQUIRED",
        "path": "participants.directors",
        "message": "At least one director is required"
      }
    ],
    "invalidRequirements": [
      {
        "code": "COMPANY_NAME_OPTIONS_INCOMPLETE",
        "path": "companyNames.companyNameOptions",
        "message": "Provide at least 3 company name options"
      }
    ]
  }
}
```

For participant-specific requirements, register participants with roles and upsert documents to each participant:

* Use `POST /partner/incorporation/{incorporationId}/participants` for director/shareholder roles.
* Use `POST /partner/commenda-os/customers/{customerId}/persons` or `PATCH /partner/commenda-os/customers/{customerId}/persons/{personId}` for required person fields such as `residentialAddress`.
* Use `PUT /partner/incorporation/{incorporationId}/participants/{participantId}/documents/{documentKind}` for participant document requirements.


## OpenAPI

````yaml PATCH /partner/incorporation/{incorporationId}/intake
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}/intake:
    patch:
      summary: Update incorporation intake
      description: >-
        Partially update incorporation intake details. Each write returns the
        updated intake state and incorporation validation summary.
      operationId: updatePartnerIncorporationIntake
      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/PartnerUpdateIntakeRequest'
      responses:
        '200':
          description: Intake updated and validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationIntakeResponse'
        '400':
          description: Malformed intake payload
          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 not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    PartnerUpdateIntakeRequest:
      type: object
      required:
        - requirements
      properties:
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirementValues'
    PartnerIncorporationIntakeResponse:
      type: object
      required:
        - intakeState
        - incorporationValidation
        - requirements
      properties:
        intakeState:
          $ref: '#/components/schemas/PartnerIncorporationIntakeState'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirements'
    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
    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
    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
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````