Array sections

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:

{
  "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 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'

Omitting refId when the document belongs to an array section entity causes the upload to fail with a 400 error.

Fiat payouts

Managed Payments

Stablecoin payments

How array sections differ from flat sections

Reading array data

Saving array data

Removing entities

Document association

​How array sections differ from flat sections

​Reading array data

​Saving array data

​Removing entities

​Document association

How array sections differ from flat sections

Reading array data

Saving array data

Removing entities

Document association