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.
The requirements response is the form contract for one incorporation type. Use it to decide which fields to render, which participant roles to collect, which Commenda OS records must be completed, and which document uploads are required.
Do not send the requirements response back unchanged. Render from requirements, save values through the endpoint family that owns each requirement, and use incorporationValidation to decide whether the incorporation is ready to submit.
| Question | Where to look | What your integration should do |
|---|
| What incorporation-level fields do I ask for? | blocks[].fields | Render these fields and submit values through PATCH /partner/incorporation/{incorporationId}/intake under requirements. |
| Who must be attached to the incorporation? | participantRequirements | Create or reuse Commenda OS people/business entities, then register them as participants. |
| What data must exist on a participant’s person or business entity? | resourceFieldsByParticipantType | Render these fields on the participant form and submit them through the relevant Commenda OS Partner API endpoint. |
| What files must be attached to a participant? | documentRequirements | Upload a customer file, then upsert it into the participant’s required document slot. |
| Why is validation still incomplete? | missingRequirements and invalidRequirements | Follow each validation path back to the field, participant, resource field, or document slot that needs attention. |
documentKind, one upsert for that participant and documentKind satisfies the overlapping requirement.
Renderer model
Build your renderer around each field’s kind.
kind | Render as | Value shape | Submit through |
|---|
scalar | One input control using input.type | Primitive string, number, or boolean | Parent destination. For blocks[].fields, send under requirements.{key}. |
object | A nested group of fields | Object keyed by child field keys | Parent destination. Object fields can appear anywhere a field is accepted; the current Singapore requirements use them as collection items. |
collection | Repeating items | Array of item objects or resource objects | Parent destination. Use cardinality and constraints to size and validate the list. |
resource | A resource picker or nested resource fields | Depends on location in the requirements response | For intake blocks, send a resource object. For participant resource fields, update the referenced Commenda OS resource. |
blocks[].fields, field keys become top-level keys in the intake requirements object. For nested object and collection fields, preserve the nested shape under the parent key.
Use each field’s key to build request payloads. commendaOs.field is an absolute Commenda OS mapping path, not the nested JSON key for the current renderer position.
For participantRequirements[].resourceFieldsByParticipantType, field keys describe data that must exist on the registered participant’s resource. Do not send those values to the intake endpoint. Update the referenced person or business entity through the Commenda OS Partner API.
The intake endpoint rejects unknown keys with 400 Bad Request. Sending participant-shaped values such as participants, directors, top-level residentialAddress, or a nested resource object under requirements fails validation before any state is stored. See Update incorporation intake for the full list of routing rules.
input.type is the UI hint for scalar fields.
input.type | Suggested control | Submit value |
|---|
text, textarea, email, phone, date, country | Text-like input, date picker, or country picker | String |
select | Select, radio group, or segmented control | The selected option value |
number, percent | Numeric input | Number |
select, render from input.options. Treat option value as the exact API value and option name/description as display copy. The API validates option values as sent; do not normalize, uppercase, or otherwise change casing.
Use input.placeholder and input.examples as hints only. They are not defaults.
Required and applicable fields
required and appliesWhen are separate concepts.
| Property | Meaning | Renderer behavior | Validation behavior |
|---|
required: true | The field is always required when applicable. | Mark required. | Missing value blocks submit. |
required: false | The field is optional. | Mark optional. | Missing value does not block submit. |
required.when | The field is conditionally required. | Recompute required state when the controlling field changes. | Missing value blocks submit only when the condition matches. |
appliesWhen | The field only applies for a selected condition. | Hide or disable the field when the condition does not match. | Non-applicable fields are ignored by validation. |
currentState is the merged history of accepted intake patches. It can contain values that are stale or no longer applicable after later choices. Treat incorporationValidation as the source of truth for readiness, not the presence of keys in currentState.
Cardinality and constraints
Collections and participant requirements can define cardinality.
| Property | Meaning | Example renderer behavior |
|---|
cardinality.exact | The list must contain exactly this many items. | Render a fixed number of rows. |
cardinality.min | The list must contain at least this many items. | Render one row and allow adding more. |
cardinality.max | The list must contain at most this many items. | Disable add after the maximum. |
constraints.
| Constraint | Meaning | Example renderer behavior |
|---|
uniqueItems | Items must be unique by the listed fields. | Warn before submit when two rows share the same field values. |
sumEquals | Numeric values across all items must total a specific number. | Show a running total and block submit when the total is off. |
validation, such as minLength, maxLength, min, max, or pattern. Use these to provide inline validation, but still handle server-side invalidRequirements.
Resource fields
Resource fields have different submission shapes depending on where they appear.
Intake resource fields
When a resource field appears under blocks[].fields, submit a resource object through the intake endpoint.
| Resource object field | Required | Description |
|---|
mode | Yes | Must be existingResource or inlineData. |
resourceId | When mode is existingResource | ID of an accessible Commenda OS resource of the type named by commendaOsResource.entity. |
data | When mode is inlineData; optional for existingResource | Field values for this resource requirement. |
fields array, those child fields describe the keys accepted under data. For existingResource, data supplements the saved resource values for incorporation validation. For inlineData, data is the full submitted resource value.
Use child field key values as the data keys. Child commendaOs.field values, when present, are absolute paths from the Commenda OS resource root.
Use existingResource when the customer already has a Commenda OS resource:
{
"requirements": {
"registeredOfficeAddressSource": "partnerProvidedLocation",
"registeredOfficeAddressLocation": {
"mode": "existingResource",
"resourceId": "location_001"
}
}
}
data when the existing resource is missing supplemental fields required for this incorporation:
{
"requirements": {
"registeredOfficeAddressSource": "partnerProvidedLocation",
"registeredOfficeAddressLocation": {
"mode": "existingResource",
"resourceId": "location_001",
"data": {
"addressLine1": "1 Raffles Place",
"postalCode": "048616",
"country": "SG"
}
}
}
}
inlineData when the incorporation should store the resource data only for this intake value:
{
"requirements": {
"registeredOfficeAddressSource": "partnerProvidedLocation",
"registeredOfficeAddressLocation": {
"mode": "inlineData",
"data": {
"addressLine1": "1 Raffles Place",
"postalCode": "048616",
"country": "SG"
}
}
}
}
commendaOs.field tells you where a field maps on a Commenda OS resource. commendaOsResource.entity tells you what kind of Commenda OS resource an existingResource value should reference. It does not create the resource automatically.
Participant resource fields
When a resource field appears under participantRequirements[].resourceFieldsByParticipantType, it describes data that must exist on the registered participant’s Commenda OS resource.
Do not render the intake resource object controls (mode and resourceId) for participant resource fields. Render the nested fields and submit them to the referenced person or business entity endpoint.
For Singapore individual directors and shareholders, residentialAddress is a required resource field on the KEY_PERSON resource. Satisfy it by updating the referenced person:
{
"residentialAddress": {
"addressLine1": "1 Raffles Place",
"city": "Singapore",
"postalCode": "048616",
"country": "SG"
}
}
POST /partner/commenda-os/customers/{customerId}/persons or PATCH /partner/commenda-os/customers/{customerId}/persons/{personId}.
The Partner API person endpoints accept residentialAddress directly. They do not accept a person locations array.
If a child field under residentialAddress has key: "addressLine1" and commendaOs.field: "residentialAddress.addressLine1", submit it once under the parent object: { "residentialAddress": { "addressLine1": "1 Raffles Place" } }. Do not submit { "residentialAddress": { "residentialAddress": { "addressLine1": "1 Raffles Place" } } }.
Worked example: Singapore Pte. Ltd.
This requirements snippet says to collect exactly three unique company names:
{
"key": "companyNames",
"fields": [
{
"kind": "collection",
"key": "companyNameOptions",
"name": "Company name options",
"cardinality": { "exact": 3 },
"constraints": [{ "kind": "uniqueItems", "fields": ["name"] }],
"item": {
"kind": "object",
"fields": [
{
"kind": "scalar",
"key": "name",
"name": "Proposed company name",
"input": { "type": "text" },
"validation": { "minLength": 1, "maxLength": 120 }
}
]
}
}
]
}
name, and prevent duplicate names before submit.
Submit the values through intake:
{
"requirements": {
"companyNameOptions": [
{ "name": "Acme SG Pte Ltd" },
{ "name": "Acme Asia Pte Ltd" },
{ "name": "Acme Global Pte Ltd" }
]
}
}
partnerProvidedLocation:
{
"key": "registeredOfficeAddress",
"fields": [
{
"kind": "scalar",
"key": "registeredOfficeAddressSource",
"name": "Registered office address source",
"required": true,
"input": {
"type": "select",
"options": [
{ "value": "commendaService", "name": "Use Commenda service" },
{ "value": "partnerProvidedLocation", "name": "Use partner-provided location" }
]
}
},
{
"kind": "resource",
"key": "registeredOfficeAddressLocation",
"required": {
"when": {
"fieldKey": "registeredOfficeAddressSource",
"equals": "partnerProvidedLocation"
}
},
"appliesWhen": {
"fieldKey": "registeredOfficeAddressSource",
"equals": "partnerProvidedLocation"
},
"commendaOsResource": { "entity": "location" },
"fields": [
{ "kind": "scalar", "key": "addressLine1", "input": { "type": "text" } },
{ "kind": "scalar", "key": "city", "input": { "type": "text" } },
{ "kind": "scalar", "key": "postalCode", "input": { "type": "text" } },
{ "kind": "scalar", "key": "country", "input": { "type": "country" } }
]
}
]
}
{
"requirements": {
"registeredOfficeAddressSource": "commendaService"
}
}
{
"requirements": {
"registeredOfficeAddressSource": "partnerProvidedLocation",
"registeredOfficeAddressLocation": {
"mode": "existingResource",
"resourceId": "location_001"
}
}
}
inlineData for that location field, use the same child fields keys under data:
{
"requirements": {
"registeredOfficeAddressSource": "partnerProvidedLocation",
"registeredOfficeAddressLocation": {
"mode": "inlineData",
"data": {
"addressLine1": "1 Raffles Place",
"city": "Singapore",
"postalCode": "048616",
"country": "SG"
}
}
}
}
{
"participantType": "INDIVIDUAL",
"resource": {
"resourceType": "KEY_PERSON",
"resourceId": 12
},
"roles": [{ "role": "DIRECTOR" }]
}
{
"path": "participants.participant_123.resource.residentialAddress",
"message": "Residential address is required"
}
participant_123 in the incorporation response, read participant.resource.resourceId, then update that person:
{
"residentialAddress": {
"addressLine1": "1 Raffles Place",
"city": "Singapore",
"postalCode": "048616",
"country": "SG"
}
}
Validation paths
Validation paths in missingRequirements and invalidRequirements point to the missing or invalid item:
| Example path | Meaning | Fix |
|---|
companyNames.companyNameOptions | Company name options are missing or invalid | Submit valid names through the intake endpoint as requirements.companyNameOptions. |
registeredOfficeAddress.registeredOfficeAddressLocation | A partner-provided registered office address location is required | Submit requirements.registeredOfficeAddressLocation or choose commendaService. |
participants.directors | A required director participant is missing | Register a person or business entity as a director. |
participants.participant_123.resource.residentialAddress | A registered participant’s referenced person is missing a residential address | Update that Commenda OS person with residentialAddress. |
participants.participant_123.documents.PASSPORT_SCAN | A participant is missing a passport scan | Upload a customer file, then upsert it as PASSPORT_SCAN for that participant. |
incorporationValidation; the incorporation is ready to submit when incorporationValidation.isComplete is true.
Renderer helpers
Most renderers need only a small set of pure helpers:
| Helper | Purpose |
|---|
evalAppliesWhen(rule, values) | Returns whether a field applies for the current sibling values. |
evalRequired(required, values) | Handles boolean required and required.when. |
padToCardinality(items, cardinality) | Initializes fixed or minimum collection rows. |
findUniqueItemsViolation(items, constraint) | Checks uniqueItems constraints before submit. |
incorporationValidation remains the final contract for submit readiness.
