Understand how to work with repeatable entity sections like beneficial owners and directors
Some sections represent repeatable entities such as beneficial_owners,
authorized_signers, or directors. These are array sections. The schema
defines them with type: array containing items that describe each entity.
Array sections differ from flat sections in how data is read, saved, and linked
to documents.Conditional logic
can activate or deactivate array sections based on the application’s
configuration.
How array sections differ from flat sections
Operation
Flat section
Array section
Read
Returns a JSON object
Returns a JSON array; each element includes a refId (UUID)
Save
PUT with a JSON object
PUT with a JSON array; include refId for existing entities, omit for new ones
Delete
Not applicable
DELETE /sections/{sectionName}/{refId} removes a single entity
Documents
Link with datumName only
Link with datumName and the entity’s refId
Reading array data
Retrieve array section data with the
Get section endpoint
(GET /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}).
The response is a JSON array where each element includes a refId:
In this example, the first entity is updated (existing refId) and the second
is created (no refId). Existing entities not included in the array are
preserved, not deleted.
Removing entities
Remove a single entity from an array section with the
Remove entity endpoint
(DELETE /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}/{refId}).
The response includes the updated section list with recalculated statuses.
Document association
When uploading a document for a field in an array entity, include the entity’s
refId so the document is associated with the correct person or organization.
See
Upload documents
for the full upload workflow.