Copy page

Common workflows

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

Code
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:

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

Retrieve accounting points:

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

Retrieve contracts:

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

Retrieve customers:

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

Retrieve products:

Code
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:

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

Code
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