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

import requests

url = "https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations"

payload = {
    "country": "SG",
    "countryOptions": { "corporationType": "PRIVATE_LIMITED_COMPANY" }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({country: 'SG', countryOptions: {corporationType: 'PRIVATE_LIMITED_COMPANY'}})
};

fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country' => 'SG',
    'countryOptions' => [
        'corporationType' => 'PRIVATE_LIMITED_COMPANY'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations"

	payload := strings.NewReader("{\n  \"country\": \"SG\",\n  \"countryOptions\": {\n    \"corporationType\": \"PRIVATE_LIMITED_COMPANY\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"SG\",\n  \"countryOptions\": {\n    \"corporationType\": \"PRIVATE_LIMITED_COMPANY\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country\": \"SG\",\n  \"countryOptions\": {\n    \"corporationType\": \"PRIVATE_LIMITED_COMPANY\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

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

import requests

url = "https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations"

payload = {
    "country": "SG",
    "countryOptions": { "corporationType": "PRIVATE_LIMITED_COMPANY" }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({country: 'SG', countryOptions: {corporationType: 'PRIVATE_LIMITED_COMPANY'}})
};

fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country' => 'SG',
    'countryOptions' => [
        'corporationType' => 'PRIVATE_LIMITED_COMPANY'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations"

	payload := strings.NewReader("{\n  \"country\": \"SG\",\n  \"countryOptions\": {\n    \"corporationType\": \"PRIVATE_LIMITED_COMPANY\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"SG\",\n  \"countryOptions\": {\n    \"corporationType\": \"PRIVATE_LIMITED_COMPANY\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/customers/{customerId}/incorporations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country\": \"SG\",\n  \"countryOptions\": {\n    \"corporationType\": \"PRIVATE_LIMITED_COMPANY\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

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

Country	Required options	Optional options
`US`	`corporationType`: `CORPORATION`, `LLC`	`state`: US state abbreviation
`CA`	`corporationType`: `CORPORATION`	None
`IN`	`corporationType`: `LLP`, `PRIVATE_LIMITED_COMPANY`	None
`AE`	`corporationType`: `FZC`	`corporationTypeOptions.freeZone`: `ADGM`, `DIFC`, `DMCC`, `IFZA`
`GB`, `IE`, `NZ`	`corporationType`: `LIMITED_COMPANY`	None
`KY`	`corporationType`: `EXEMPTED_COMPANY`	None
`SG`	`corporationType`: `PRIVATE_LIMITED_COMPANY`	None

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.

Show child attributes

Response

Incorporation created successfully

incorporation

object

required

Show child attributes

incorporationValidation

object

required

Show child attributes

intakeState

object

required

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

Show child attributes

participants

object[]

required

Participants registered to this incorporation, when requested or available.

Show child attributes

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

Incorporation validation object List incorporations

Overview

Customer setup

Partner Incorporation API

Commenda OS Partner API

Webhooks

Request shape

Singapore example

Initial partial intake example

Supported options

Response status

Authorizations

Path Parameters

Body

Response

​Request shape

​Singapore example

​Initial partial intake example

​Supported options

​Response status

Authorizations

Path Parameters

Body

Response

Request shape

Singapore example

Initial partial intake example

Supported options

Response status