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": [
      {
        "path": "participants.participant_123.documents.passport_scan",
        "message": "Participant participant_123 requires a passport_scan document"
      }
    ],
    "invalidRequirements": [
      {
        "path": "participants.participant_123.documents.passport_scan",
        "message": "Participant participant_123 requires a passport_scan document"
      }
    ]
  },
  "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": [
          "keyPerson"
        ],
        "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 and participant documents are managed through the participant and document endpoints, not by sending array indexes or document files inside this intake payload.

​
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, or participant documents, the response returns missingRequirements and invalidRequirements until the current incorporation state satisfies those rules. Example validation details: 
{
  "incorporationValidation": {
    "isComplete": false,
    "missingRequirements": [
      {
        "path": "participants.directors",
        "message": "At least one director is required"
      }
    ],
    "invalidRequirements": [
      {
        "path": "companyNames.companyNameOptions",
        "message": "Provide at least 3 company name options"
      }
    ]
  }
}
For participant-specific requirements, register participants with roles and link documents to each participant:
  • Use POST /partner/incorporation/{incorporationId}/participants for director/shareholder roles.
  • Use POST /partner/incorporation/{incorporationId}/documents 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": ["keyPerson"],
      "documentRequirements": [
        {
          "documentKind": "passport_scan",
          "name": "Passport scan"
        },
        {
          "documentKind": "utility_bill",
          "name": "Utility bill"
        }
      ]
    }
  ]
}