Skip to main content
PATCH
/
partner
/
incorporation
/
{incorporationId}
/
intake
Update incorporation intake
curl --request PATCH \
  --url https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/intake \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "requirements": {
    "companyNameOptions": [
      {
        "name": "Acme SG Pte Ltd"
      },
      {
        "name": "Acme Asia Pte Ltd"
      },
      {
        "name": "Acme Global Pte Ltd"
      }
    ],
    "registeredOfficeAddressSource": "commendaService"
  }
}
'
{
  "intakeState": {
    "id": "state_123",
    "incorporationId": "0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91",
    "currentState": {
      "companyNameOptions": [
        {
          "name": "Acme SG Pte Ltd"
        },
        {
          "name": "Acme Asia Pte Ltd"
        },
        {
          "name": "Acme Global Pte Ltd"
        }
      ],
      "registeredOfficeAddressSource": "commendaService"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "incorporationValidation": {
    "isComplete": false,
    "missingRequirements": [
      {
        "code": "PARTICIPANT_DOCUMENT_REQUIRED",
        "path": "participants.participant_123.documents.PASSPORT_SCAN",
        "message": "Participant participant_123 requires a PASSPORT_SCAN document",
        "participantId": "participant_123",
        "displayName": "Jane Founder"
      }
    ],
    "invalidRequirements": [
      {
        "code": "PARTICIPANT_DOCUMENT_REQUIRED",
        "path": "participants.participant_123.documents.PASSPORT_SCAN",
        "message": "Participant participant_123 requires a PASSPORT_SCAN document",
        "participantId": "participant_123",
        "displayName": "Jane Founder"
      }
    ]
  },
  "requirements": {
    "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"
          }
        ]
      }
    ]
  }
}
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 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 shapeWhere to submit
Participant roles such as directors or shareholdersRegister an incorporation participant or Update an incorporation participant
Person resource fields such as residentialAddressUpdate a partner person using PATCH /partner/commenda-os/customers/{customerId}/persons/{personId}
Participant documents such as PASSPORT_SCANUpsert a participant document
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. 
{
  "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.
SourceUse whenRequired fields
commendaServiceCommenda should provide the registered office address service for this incorporation.registeredOfficeAddressSource
partnerProvidedLocationYou 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: 
{
  "requirements": {
    "registeredOfficeAddressSource": "commendaService"
  }
}
Use partnerProvidedLocation when you are providing a reusable Commenda OS location: 
{
  "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: 
{
  "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.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
incorporationId
string
required

Incorporation identifier returned by create or list endpoints.

Body

application/json
​
requirements
object
required

Partner-submitted requirement values keyed by requirements field keys.

Example:
{
  "companyNameOptions": [
    { "name": "Acme SG Pte Ltd" },
    { "name": "Acme Asia Pte Ltd" },
    { "name": "Acme Global Pte Ltd" }
  ],
  "registeredOfficeAddressSource": "commendaService"
}

Response

Intake updated and validated

​
intakeState
object
required
​
incorporationValidation
object
required
​
requirements
object
required

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.

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"
        }
      ]
    }
  ]
}