Array sections

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:

{
  "data": [
    {
      "refId": "550e8400-e29b-41d4-a716-446655440001",
      "firstName": "Jane",
      "lastName": "Doe",
      "ownershipPercentage": "51"
    },
    {
      "refId": "660e8400-e29b-41d4-a716-446655440002",
      "firstName": "John",
      "lastName": "Smith",
      "ownershipPercentage": "49"
    }
  ]
}

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:

curl --request PUT \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/sections/beneficial_owners \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "refId": "550e8400-e29b-41d4-a716-446655440001",
      "firstName": "Jane",
      "lastName": "Doe",
      "ownershipPercentage": 60
    },
    {
      "firstName": "Alex",
      "lastName": "Johnson",
      "ownershipPercentage": 40
    }
  ]'

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.

curl --request POST \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/documents \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'X-Idempotency-Key: ${IDEMPOTENCY_KEY}' \
  --form 'fileContent=@passport.pdf' \
  --form 'fileName=passport.pdf' \
  --form 'datumName=passport_document' \
  --form 'refId=550e8400-e29b-41d4-a716-446655440001' \
  --form 'issuedCountry=US'

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.