Skip to main content
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.
QuestionWhere to lookWhat your integration should do
What incorporation-level fields do I ask for?blocks[].fieldsRender these fields and submit values through PATCH /partner/incorporation/{incorporationId}/intake under requirements.
Who must be attached to the incorporation?participantRequirementsCreate or reuse Commenda OS people/business entities, then register them as participants.
What data must exist on a participant’s person or business entity?resourceFieldsByParticipantTypeRender 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?documentRequirementsUpload a customer file, then upsert it into the participant’s required document slot.
Why is validation still incomplete?missingRequirements and invalidRequirementsFollow each validation path back to the field, participant, resource field, or document slot that needs attention.

​
Renderer model

Build your renderer around each field’s kind.
kindRender asValue shapeSubmit through
scalarOne input control using input.typePrimitive string, number, or booleanParent destination. For blocks[].fields, send under requirements.{key}.
objectA nested group of fieldsObject keyed by child field keysParent destination. Object fields can appear anywhere a field is accepted; the current Singapore requirements use them as collection items.
collectionRepeating itemsArray of item objects or resource objectsParent destination. Use cardinality and constraints to size and validate the list.
resourceA resource picker or nested resource fieldsDepends on location in the requirements responseFor intake blocks, send a resource object. For participant resource fields, update the referenced Commenda OS resource.
For 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. 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.

​
Scalar input types

input.type is the UI hint for scalar fields.
input.typeSuggested controlSubmit value
text, textarea, email, phone, date, countryText-like input, date picker, or country pickerString
selectSelect, radio group, or segmented controlThe selected option value
number, percentNumeric inputNumber
For 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.
PropertyMeaningRenderer behaviorValidation behavior
required: trueThe field is always required when applicable.Mark required.Missing value blocks submit.
required: falseThe field is optional.Mark optional.Missing value does not block submit.
required.whenThe field is conditionally required.Recompute required state when the controlling field changes.Missing value blocks submit only when the condition matches.
appliesWhenThe 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.
Because intake updates are merge-based, 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.
PropertyMeaningExample renderer behavior
cardinality.exactThe list must contain exactly this many items.Render a fixed number of rows.
cardinality.minThe list must contain at least this many items.Render one row and allow adding more.
cardinality.maxThe list must contain at most this many items.Disable add after the maximum.
Collections can also define constraints.
ConstraintMeaningExample renderer behavior
uniqueItemsItems must be unique by the listed fields.Warn before submit when two rows share the same field values.
sumEqualsNumeric values across all items must total a specific number.Show a running total and block submit when the total is off.
Scalar fields can define 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 fieldRequiredDescription
modeYesMust be existingResource or inlineData.
resourceIdWhen mode is existingResourceID of an accessible Commenda OS resource of the type named by commendaOsResource.entity.
dataWhen mode is inlineData; optional for existingResourceField values for this resource requirement.
When a resource field includes a 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 existingResource when the customer already has a Commenda OS resource: 
{
  "requirements": {
    "registeredOfficeAddressSource": "partnerProvidedLocation",
    "registeredOfficeAddressLocation": {
      "mode": "existingResource",
      "resourceId": "location_001"
    }
  }
}
You can include 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"
      }
    }
  }
}
Use 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"
      }
    }
  }
}
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. 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"
  }
}
This is not an intake value and it is not the registered office address location. Submit it through 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.

​
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 }
          }
        ]
      }
    }
  ]
}
A renderer should show three text inputs, validate each 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" }
    ]
  }
}
This requirements snippet says to render a select for registered office address source. The location field is only visible and required when the user chooses 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" } }
      ]
    }
  ]
}
If the user chooses Commenda’s registered office service, submit only the selected option: 
{
  "requirements": {
    "registeredOfficeAddressSource": "commendaService"
  }
}
If the user chooses a partner-provided location, submit the selected source plus the resource object: 
{
  "requirements": {
    "registeredOfficeAddressSource": "partnerProvidedLocation",
    "registeredOfficeAddressLocation": {
      "mode": "existingResource",
      "resourceId": "location_001"
    }
  }
}
If the user chooses 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"
      }
    }
  }
}
Participant requirements are rendered separately from intake fields. For an individual director, create or update a person, register that person as a participant, and attach required documents: 
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 12
  },
  "roles": [{ "role": "DIRECTOR" }]
}
If validation returns: 
{
  "path": "participants.participant_123.resource.residentialAddress",
  "message": "Residential address is required"
}
Find 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 pathMeaningFix
companyNames.companyNameOptionsCompany name options are missing or invalidSubmit valid names through the intake endpoint as requirements.companyNameOptions.
registeredOfficeAddress.registeredOfficeAddressLocationA partner-provided registered office address location is requiredSubmit requirements.registeredOfficeAddressLocation or choose commendaService.
participants.directorsA required director participant is missingRegister a person or business entity as a director.
participants.participant_123.resource.residentialAddressA registered participant’s referenced person is missing a residential addressUpdate that Commenda OS person with residentialAddress.
participants.participant_123.documents.PASSPORT_SCANA participant is missing a passport scanUpload a customer file, then upsert it as PASSPORT_SCAN for that participant.
Your renderer can prevent many invalid values before submit, but Commenda validation is authoritative. After every write, read incorporationValidation; the incorporation is ready to submit when incorporationValidation.isComplete is true.

​
Renderer helpers

Most renderers need only a small set of pure helpers:
HelperPurpose
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.
Keep client-side validation helpful but non-authoritative. The server may add or change requirements, and incorporationValidation remains the final contract for submit readiness.