Understand how to work with repeatable entity sections like beneficial owners and directors
Some sections hold repeatable entities such as beneficial_owners,
authorized_signers, or directors. These are array sections. The schema
marks them as type: array with items for each entity. Array sections exist
because a business can have any number of these entities—two beneficial owners,
or five.Each entity gets its own refId so you can update it or attach documents to it
on its own. These sections use different read, save, and document rules than
flat ones.Conditional logic can turn
array sections on or off based on application settings.
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:
By default, values like ownershipPercentage return as strings. Add
?typedValues=true to
Get section,
List sections (with
includeData=true), or
Get all application data to
get native JSON types.
Saving array data
When saving, include refId for entities you want to update and omit it for new
entities:
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.
Always include the entity’s refId when you update it. Without refId, the API
adds a new entity instead. That can leave the section incomplete if the
duplicate is missing required documents. Delete it with
DELETE /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}/{refId}.
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.
Uploading a document for an array entity returns a documentId, but that alone
does not fill the entity’s document field. Save the array section again with the
documentId in the relevant field. Include the same refId so the API updates
the existing entity, not a new one.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.