Skip to main content
POST
/
partner
/
incorporation
/
customers
/
{customerId}
/
incorporations
Create an incorporation
curl --request POST \
  --url https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "country": "SG",
  "countryOptions": {
    "corporationType": "PRIVATE_LIMITED_COMPANY"
  }
}
'
{
  "incorporation": {
    "id": "0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91",
    "customerId": 77,
    "country": "SG",
    "countryOptions": {
      "corporationType": "PRIVATE_LIMITED_COMPANY"
    },
    "incorporationStatus": "AWAITING_CUSTOMER_INPUT",
    "createdAt": "2026-04-21T17:10:00.000Z",
    "updatedAt": "2026-04-21T17:10:00.000Z",
    "businessEntityId": 44
  },
  "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",
        "documentKind": "PASSPORT_SCAN",
        "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",
        "documentKind": "PASSPORT_SCAN",
        "displayName": "Jane Founder"
      }
    ]
  },
  "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"
  },
  "participants": [
    {
      "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"
        }
      ]
    }
  ],
  "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"
          }
        ]
      }
    ]
  }
}

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.

Starts an incorporation for one of your customers. The response returns the incorporation resource directly, plus incorporationValidation, current requirements, and intakeState. If no initial intake values are supplied, intakeState.currentState is {}. For a complete Singapore walkthrough with the IDs to save, see Build an incorporation flow.

​
Request shape

Create requests use a country plus country-specific countryOptions instead of a flat product id.
  • country is the ISO 3166-1 alpha-2 code for the jurisdiction.
  • countryOptions is an object whose shape depends on country.
  • customerId is the path parameter for the customer that owns the incorporation.
  • intake.requirements is optional and can contain initial partial intake data.
  • Unknown or unsupported options are rejected by this endpoint.

​
Singapore example

{
  "country": "SG",
  "countryOptions": {
    "corporationType": "PRIVATE_LIMITED_COMPANY"
  }
}
Use GET /partner/incorporation/jurisdiction-catalog to see currently supported countries and option values. Use GET /partner/incorporation/requirements before building an intake UI.

​
Initial partial intake example

{
  "country": "SG",
  "countryOptions": {
    "corporationType": "PRIVATE_LIMITED_COMPANY"
  },
  "intake": {
    "requirements": {
      "companyNameOptions": [
        { "name": "Acme SG Pte Ltd" }
      ]
    }
  }
}

​
Supported options

CountryRequired optionsOptional options
UScorporationType: CORPORATION, LLCstate: US state abbreviation
CAcorporationType: CORPORATIONNone
INcorporationType: LLP, PRIVATE_LIMITED_COMPANYNone
AEcorporationType: FZCcorporationTypeOptions.freeZone: ADGM, DIFC, DMCC, IFZA
GB, IE, NZcorporationType: LIMITED_COMPANYNone
KYcorporationType: EXEMPTED_COMPANYNone
SGcorporationType: PRIVATE_LIMITED_COMPANYNone

​
Response status

New incorporations are returned with incorporationStatus: "AWAITING_CUSTOMER_INPUT". Once required intake data, participant roles, and documents validate, call POST /partner/incorporation/{incorporationId}/submit; after submit succeeds, the status becomes SUBMITTED or IN_PROGRESS depending on workflow start state.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
customerId
integer
required

Customer that should own the incorporation.

Body

application/json
​
country
enum<string>
required

ISO 3166-1 alpha-2 country code for the incorporation jurisdiction.

Available options:
AE,
CA,
GB,
IE,
IN,
KY,
NZ,
SG,
US
Example:

"SG"

​
countryOptions
object
required

Country-specific incorporation options. Use the jurisdiction catalog for the currently supported fields and values.

Example:
{
  "corporationType": "PRIVATE_LIMITED_COMPANY"
}
​
intake
object

Optional initial partial intake data.

Response

Incorporation created successfully

​
incorporation
object
required
​
incorporationValidation
object
required
​
intakeState
object
required

Current intake state for the incorporation. Always returned; an empty intake state is initialized automatically when one does not yet exist.

​
participants
object[]
required

Participants registered to this incorporation, when requested or available.

​
requirements
object

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