Skip to main content
POST
/
partner
/
incorporation
/
companies
/
{companyId}
/
incorporations
Create an incorporation
curl --request POST \
  --url https://api.prod.commenda.io/api/v1/partner/incorporation/companies/{companyId}/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",
    "incorporationId": "0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91",
    "companyId": 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",
    "corporationId": 44
  },
  "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"
          }
        ]
      }
    ]
  },
  "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"
  },
  "participants": [
    {
      "participantId": "participant_123",
      "participantType": "individual",
      "resource": {
        "resourceType": "keyPerson",
        "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"
        }
      ]
    }
  ]
}
Starts an incorporation for a company accessible to your partner account. This endpoint does not create a payment intent. The response returns the incorporation resource directly, plus the current requirements and intakeState when available. For a complete Singapore walkthrough with ID handoffs, 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.
  • companyId is the path parameter for the Commenda company 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

​
companyId
integer
required

Company 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
​
requirements
object

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"
        }
      ]
    }
  ]
}
​
intakeState
object
​
participants
object[]

Participants registered to this incorporation, when requested or available.