# Bulk retrievals

Use this workflow to retrieve larger sets of core data from UtilityCloud.

Bulk retrievals are typically used when an external system needs to synchronize data, build an initial data copy, or periodically retrieve updated information from UtilityCloud.

## Endpoints

```http
GET /v1/cm/accounts?limit={limit}&page={page}
GET /v1/cm/accountingpoints?limit={limit}&page={page}
GET /v1/cm/contracts?limit={limit}&page={page}
GET /v1/cm/customers?limit={limit}&page={page}
GET /v1/pm/products
```

## When to use

Use this workflow when an external system needs to retrieve multiple resources from UtilityCloud.

Typical use cases include:

- initial data synchronization
- retrieving customers for a CRM or data warehouse
- retrieving accounts for invoice-related synchronization
- retrieving accounting points for operational or settlement-related use
- retrieving contracts and related customer, account, accounting point, and product information
- retrieving products available for contract or offer creation

## Request parameters

| Parameter | Description |
|---|---|
| `limit` | Maximum number of records to return in one page. |
| `page` | Page number to retrieve. |

## Example requests

Retrieve accounts:

```http
GET /v1/cm/accounts?limit=10&page=0
```

Retrieve accounting points:

```http
GET /v1/cm/accountingpoints?limit=10&page=0
```

Retrieve contracts:

```http
GET /v1/cm/contracts?limit=10&page=0
```

Retrieve customers:

```http
GET /v1/cm/customers?limit=10&page=0
```

Retrieve products:

```http
GET /v1/pm/products
```

## Response

The response structure depends on the endpoint.

Bulk retrieval endpoints typically return a collection of resources and, where supported, a count or paging-related information.

Example structure:

```json
{
  "count": 1,
  "customers": [
    {
      "Guid": "9c571be0-a689-4b83-9343-4043b5328836",
      "Identification": "31074355544",
      "GivenName": "Kari",
      "FamilyName": "Nordmann"
    }
  ]
}
```

## Resource types

| Endpoint | Resource |
|---|---|
| `GET /v1/cm/accounts` | Accounts |
| `GET /v1/cm/accountingpoints` | Accounting Points |
| `GET /v1/cm/contracts` | Contracts |
| `GET /v1/cm/customers` | Customers |
| `GET /v1/pm/products` | Products |

## Recommended approach

For an initial synchronization, retrieve the required resources page by page.

A common approach is to start with contracts, because Contract responses include or reference many of the related core objects.

Depending on the use case, retrieving contracts may provide access to related Customer, Account, Accounting Point, and Product data without requiring separate full retrievals for all resource types.

## Notes

Use `limit` and `page` to retrieve paged data where supported.

Start with `page=0` and continue requesting the next page until no more records are returned.

The amount of data returned by each endpoint depends on tenant configuration, available data, and endpoint behavior.

By looping through all contracts, you can retrieve most of the related objects at the same time.

For successful PM requests, `responseCode` is `0000000000`.

## Related endpoints

```http
GET /v1/cm/accounts?limit={limit}&page={page}
GET /v1/cm/accountingpoints?limit={limit}&page={page}
GET /v1/cm/contracts?limit={limit}&page={page}
GET /v1/cm/customers?limit={limit}&page={page}
GET /v1/pm/products
```