> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Array sections

> 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](/cpn/managed-payments/end-user-onboarding/concepts/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](/api-reference/end-user-onboarding/get-section) endpoint
(`GET /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}`).
The response is a JSON array where each element includes a `refId`:

```json theme={null}
{
  "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:

```shell theme={null}
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](/api-reference/end-user-onboarding/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](/cpn/managed-payments/end-user-onboarding/howtos/upload-documents)
for the full upload workflow.

```shell theme={null}
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'
```

<Warning>
  Omitting `refId` when the document belongs to an array section entity causes the
  upload to fail with a `400` error.
</Warning>