Skip to main content
POST
/
partner
/
incorporation
/
{incorporationId}
/
intake
Update incorporation intake
curl --request POST \
  --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"
      }
    ],
    "registeredAddressMode": "standardAddress"
  }
}
'
{
  "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"
        }
      ],
      "registeredAddressMode": "standardAddress"
    },
    "validation": {
      "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"
        }
      ]
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "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"
          }
        ]
      }
    ]
  }
}
Updates partial or complete non-participant requirement data for an incorporation. Each update is merged into the current intake state and validated against the current requirements DSL. Incomplete updates are accepted and return a structured validation summary. The Partner API does not expose a submission history endpoint. To read progress after an update, call GET /partner/incorporation/{incorporationId} and inspect intakeState. When intakeState.validation.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 address data. 
{
  "requirements": {
    "companyNameOptions": [
      { "name": "Acme Holdings" },
      { "name": "Acme Global" },
      { "name": "Acme Ventures" }
    ],
    "registeredAddressMode": "standardAddress"
  }
}
registeredAddressMode is a data choice, not UI rendering instruction:
  • standardAddress means Commenda should use its standard registered address service for this incorporation.
  • providedAddress means the partner is providing a reusable Commenda OS location.
If registeredAddressMode is providedAddress, include providedRegisteredAddress as a Commenda OS location reference. 
{
  "requirements": {
    "registeredAddressMode": "providedAddress",
    "providedRegisteredAddress": {
      "mode": "existingResource",
      "resourceId": "location_001"
    }
  }
}
The referenced location must belong to a partner-accessible Commenda OS business entity for the same company. If the existing location is missing a field required by the current requirements DSL, you can include supplemental data on the existingResource reference for incorporation validation. If you later switch registeredAddressMode back to standardAddress, any previously submitted providedRegisteredAddress 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 requirements DSL. 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. 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 DSL field keys.

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

Response

Intake update accepted and validated

​
intakeState
object
required
​
requirements
object
required

Requirements DSL 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 DSL.

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