Skip to main content
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

OperationFlat sectionArray section
ReadReturns a JSON objectReturns a JSON array; each element includes a refId (UUID)
SavePUT with a JSON objectPUT with a JSON array; include refId for existing entities, omit for new ones
DeleteNot applicableDELETE /sections/{sectionName}/{refId} removes a single entity
DocumentsLink with datumName onlyLink with datumName and the entity’s refId

​
Reading array data

Retrieve array section data with 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
    }
  ]
}

​
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.

​
Removing entities

Remove a single entity from an array section with 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'
Omitting refId when the document belongs to an array section entity causes the upload to fail with a 400 error.