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