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

# List and Sync Records

> Page through customers, beneficiaries, and payments to keep local state in sync

Use list endpoints to read partner-owned records after creating or updating them. The customer, beneficiary, and payment list endpoints use cursor pagination.

Required permissions depend on the resource:

| Resource    | Permission           |
| ----------- | -------------------- |
| Customer    | `CUSTOMERS_READ`     |
| Beneficiary | `BENEFICIARIES_READ` |
| Payment     | `PAYMENTS_READ`      |

## Pagination pattern

Send `limit` on the first request. If the response includes `hasMore: true`, send the returned `nextCursor` as `cursor` on the next request.

```bash theme={null}
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/customers?limit=20" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN"
```

```bash theme={null}
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/customers?limit=20&cursor=<next-cursor>" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN"
```

List responses include `items`, `nextCursor`, and `hasMore`.

## List customers

Use `GET /api/v1/customers` to list customers in your partner organization.

```bash theme={null}
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/customers?limit=20&status=APPROVED" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN"
```

Optional filters:

| Filter   | Required? | Notes                                                                                          |
| -------- | --------- | ---------------------------------------------------------------------------------------------- |
| `status` | Optional  | One of `DRAFT`, `PENDING_REVIEW`, `CORRECTION_REQUESTED`, `APPROVED`, `REJECTED`, `SUSPENDED`. |
| `limit`  | Optional  | Page size from 1 to 100. Defaults to 20.                                                       |
| `cursor` | Optional  | Cursor returned by the previous page.                                                          |

## List beneficiaries for a customer

Use `GET /api/v1/customers/{customerId}/beneficiaries` to list beneficiaries under one customer.

```bash theme={null}
CUSTOMER_ID="<customer-id>"
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/customers/$CUSTOMER_ID/beneficiaries?limit=20&status=APPROVED" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN"
```

Optional filters:

| Filter   | Required? | Notes                                                                                 |
| -------- | --------- | ------------------------------------------------------------------------------------- |
| `status` | Optional  | One of `PENDING_REVIEW`, `CORRECTION_REQUESTED`, `APPROVED`, `REJECTED`, `SUSPENDED`. |
| `limit`  | Optional  | Page size from 1 to 100. Defaults to 20.                                              |
| `cursor` | Optional  | Cursor returned by the previous page.                                                 |

## List payments

Use `GET /api/v1/payment` to list payments across your partner organization. You can filter by status, customer, beneficiary, or created date range.

```bash theme={null}
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/payment?limit=20&status=COMPLETED&dateFrom=2026-07-01T00:00:00Z&dateTo=2026-07-31T23:59:59Z" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN"
```

Optional filters:

| Filter          | Required? | Notes                                                                                                         |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `status`        | Optional  | One of `PENDING_REVIEW`, `CORRECTION_NEEDED`, `APPROVED`, `PROCESSING`, `COMPLETED`, `REJECTED`, `CANCELLED`. |
| `customerId`    | Optional  | Limit results to one customer.                                                                                |
| `beneficiaryId` | Optional  | Limit results to one beneficiary.                                                                             |
| `dateFrom`      | Optional  | ISO date-time lower bound, for example `2026-07-01T00:00:00Z`.                                                |
| `dateTo`        | Optional  | ISO date-time upper bound, for example `2026-07-31T23:59:59Z`.                                                |
| `limit`         | Optional  | Page size from 1 to 100. Defaults to 20.                                                                      |
| `cursor`        | Optional  | Cursor returned by the previous page.                                                                         |

For complete list output schemas, open the [API Reference](/api-reference/introduction).