Purpose of this article
This article outlines the requirements both your organization and your third-party data provider must meet to successfully integrate an API with Scaler. Use this as a reference during planning to ensure all stakeholders are prepared before implementation begins. Share this article — or the linked requirements document — with your provider's API or technical team before onboarding starts.
Integration process overview
Setting up an API integration involves four key phases:
- Preparation — Confirm API readiness and align on technical requirements (3–4 weeks)
- Development — Build and test the API connection in a staging environment (approximately 2 weeks from project start)
- Mapping — Align fields between the external platform and Scaler (1–4 weeks)
- Synchronization — Validate data flow between systems (under 1 day)
Timelines depend on provider responsiveness, documentation quality, number of fields, and client input speed.
How the integration works
Scaler connects to provider APIs on a scheduled basis (typically daily, weekly, or monthly) to collect two categories of information:
- Entities — Buildings and utility meters, the physical assets for which data is collected.
- Usage — Meter readings or consumption figures, the actual energy, water, or waste data over time.
All data is fetched, transformed to Scaler's standard format, validated, and stored. Stale or removed records are automatically deactivated on each sync.
Authentication
Scaler supports the following authentication mechanisms. Your provider must confirm which method their API uses and supply the necessary credentials.
Method | Description | What Scaler needs |
API Key | A static token sent in a request header or query parameter. | Header name and key value |
HTTP Basic Auth | Username and password encoded in the Authorization header. | Username and password |
OAuth 2.0 | Token obtained via Client Credentials or Password Grant flow. Scaler handles token refresh automatically. | Token endpoint URL, client ID, client secret (and username/password if Password Grant) |
Bearer Token | A static or long-lived bearer token. | Token value and the expected Authorization header format |
All credentials are stored as encrypted environment variables on Scaler's side and are never committed to source code or configuration files.
API requirements
Protocol and format
Scaler's preferred integration format is:
- REST
- JSON response bodies (XML is supported but requires additional processing)
- Standard HTTP status codes (200, 201, 204, 400, 401, 403, 404, 429, 5xx)
If the provider API uses a different protocol (GraphQL, SOAP, CSV export, etc.), discuss with the Scaler team during onboarding.
Pagination
If endpoints return large data sets, pagination should be supported. Scaler can work with common pagination styles:
- Offset/limit pagination (e.g.
?offset=0&limit=100)
- Cursor/token-based pagination (e.g.
nextPage,nextTokenfields)
- Link header pagination (RFC 5988)
The provider should document how pagination is indicated in responses (e.g. a nextPage field, a total count, or a Link header).
Date range filtering
Usage endpoints must support filtering by date range so that Scaler can request only the period it needs. Typical query parameters are:
from/toorstart_date/end_date(YYYY-MM-DD format preferred)
- Scaler may split large ranges into smaller chunks if the API has a per-request limit.
The provider should document any restrictions on the maximum date range per request.
Rate limits
The provider should document any rate limits imposed by their API, including:
- Maximum requests per minute / hour / day
- Per-endpoint limits if they differ from global limits
- The HTTP status code returned when a rate limit is hit (ideally 429 with a Retry-After header)
Scaler implements automatic retry with exponential backoff when it receives a 429 response.
Environments
The provider should confirm whether they offer separate base URLs for testing/staging and production environments. Scaler will test against a non-production environment before going live.
Required data
Scaler organizes imported data into three entity types: Assets (buildings), Meters (measurement points), and Usage records (readings or consumption). The sections below define the fields Scaler needs for each type.
Assets (buildings / properties)
An asset represents a physical location — typically a building, site, or property. Each asset must have a stable, unique identifier within the provider's system.
Field | Required / Optional | Notes |
Unique identifier (external_id) | Required | A stable, provider-assigned ID. Used to match and deduplicate records across syncs. |
Name / Description | Required | A human-readable label for the asset. |
Address | Optional | Physical address of the building. Helps with manual mapping. |
Additional metadata | Optional | Any extra attributes the system exposes (e.g. portfolio name, region). Stored as-is. |
If the provider API does not have a discrete assets endpoint and meters carry location information, Scaler can derive assets from meter data. The provider should describe the data model so the Scaler team can design the appropriate transformation.
Meters (measurement points)
A meter represents a single measurement point attached to an asset. Each meter must be linkable to an asset via a shared identifier.
Field | Required / Optional | Notes |
Unique identifier (external_id) | Required | A stable, provider-assigned ID for the meter. |
Asset identifier | Required | The identifier of the asset this meter belongs to. |
Meter type | Required | The commodity being measured. See supported meter types below. |
Meter subtype | Optional | Further classification (e.g. Potable for water, or Natural gas for energy). |
Unit of measurement | Required | The unit in which readings are reported (e.g. kWh, m³, litres). |
Description | Optional | A label or name for the meter. |
Additional metadata | Optional | Any extra attributes (e.g. MPAN, serial number). Stored as-is. |
Supported meter types
Scaler maintains a fixed set of meter types. The provider should map their meter classification to one of the categories below. If the provider uses a different classification, the Scaler team will agree on a mapping during onboarding.
Top-level category | Sub-categories (examples) |
Energy | Coal, Coke, Diesel, District Chilled Water, District Heating and Cooling, District Hot Water, District Steam, EV Charging, Fuel Oil, Natural Gas, Off-site Electricity, On-site Renewable Electricity, Propane, Wood |
Water | Potable, Reclaimed, Grey |
Waste | Hazardous, Non-hazardous |
If the provider API does not supply a meter type, the provider should describe how the commodity can be inferred from available fields (e.g. unit symbol, endpoint path).
Units of measurement
Each meter must have an associated unit. The unit must be a standard measurement abbreviation such as kWh, MWh, GJ, m³, litres, therms, or similar. Scaler will register any unit that is not already in its database on first sync.
Usage and consumption data
Usage records represent the actual readings or consumption figures for a meter over a period. Scaler supports two formats:
- Consumption format — Consumption over a period: a value covering a start date and an end date (e.g. monthly total kWh).
- Reading format — Point-in-time meter reading: a single value at a specific date or timestamp (e.g. meter stand reading).
At least one format must be supported. Both formats may be provided simultaneously.
Usage record fields
Field | Required / Optional | Notes |
Meter identifier | Required | Links the reading to a meter. Must match the meter's external_id. |
Start date | Required (consumption) | Inclusive start of the period. Format: YYYY-MM-DD. |
End date | Required (consumption) | Exclusive end of the period. Must be after start date. Format: YYYY-MM-DD. |
Consumption value | Required (consumption) | Numeric. The total consumption for the period, in the meter's unit. |
Reading date | Required (reading) | The date or timestamp of the meter reading. Format: YYYY-MM-DD or ISO 8601. |
Reading value | Required (reading) | Numeric. The meter stand value at the reading date. |
Redelivery to grid | Optional | Energy exported or returned to the grid (e.g. solar surplus). Numeric, same unit as consumption. |
Production | Optional | On-site energy production (e.g. solar generation). Numeric. |
Cost | Optional | The cost for the period. Numeric. |
Currency | Optional | ISO 4217 currency code (e.g. EUR, GBP, USD). Required if cost is provided. |
Estimation flag | Optional | Boolean. True if the value is estimated rather than measured. |
Additional metadata | Optional | Any supplementary fields the system exposes. |
Date and time format
Scaler requires all dates and timestamps to conform to the following:
- Date-only values: YYYY-MM-DD (ISO 8601 date format)
- Datetime values: ISO 8601 with timezone offset (e.g.
2024-03-15T08:00:00+00:00or2024-03-15T08:00:00Z)
- If the provider API returns timestamps without timezone information, the provider must document the assumed timezone.
End dates must be strictly after start dates. Records where end date precedes start date will be rejected.
Granularity
The provider should specify the granularity of usage data available from their API:
- Daily, monthly, or other intervals for consumption data
- Frequency of point-in-time readings (e.g. every 30 minutes for half-hourly data)
If sub-daily data is available but monthly aggregates are not, Scaler can aggregate to the required granularity on its side. The provider should document what aggregation the API already applies, if any.
End-to-end data flow
To complete a working integration, the following relationships must be navigable via the provider API:
- Each meter can be linked to an asset (directly or by derivation).
- Each usage record references a meter.
- Each meter has a unit of measurement.
The provider should supply an overview of their API's data model and the endpoints that expose each entity type. An entity-relationship diagram or an annotated Postman collection / Swagger specification is ideal.
What Scaler provides
Item | Detail |
Credential storage | API keys, tokens, and passwords are stored as encrypted environment variables — never in code or configuration files. |
Sync schedule | Scaler runs integration jobs on a configurable schedule (typically daily, weekly, or monthly). The schedule is agreed during onboarding. |
Incremental sync support | Where the provider API supports it, Scaler requests only data that has changed or been added since the last sync, to minimise load. |
Automatic retry | Scaler retries failed requests automatically on rate-limit (HTTP 429) and server-error (HTTP 5xx) responses, with exponential backoff. |
Error reporting | Scaler logs all errors and can notify the client team when a sync fails. Invalid records are quarantined rather than silently dropped. |
Testing environment | Scaler can test against a non-production environment before activating the live sync. |
Client requirements
Client preparation checklist
Cost and agreement
Integration ownership
Access and permissions
Data scope and parameters
Mapping work
Pre-onboarding checklist for providers
To begin integration scoping, the third-party provider should supply the following:
- API base URL(s) — staging and production
- Authentication method and credentials for a test account
- API reference documentation or OpenAPI/Swagger specification
- Postman collection or equivalent if available
- Description of any rate limits or access restrictions
- Confirmation of available data types (assets, meters, units, usage) and their granularity
- Description of how meters relate to assets within the data model
- List of supported date range parameters and any per-request date range limits
- Known edge cases — meter resets, estimated readings, solar/redelivery fields, etc.
If any of the above are not applicable or not yet available, the provider should let the Scaler team know during the initial call so we can plan accordingly.
Troubleshooting and common mistakes
- Missing provider documentation → Contact the provider early to confirm API documentation exists and is accessible
- Unclear data flow → Request a diagram or written description of how data moves from assets to meters to consumption records
- Rate limits not disclosed → Ask the provider explicitly about API call limits to avoid integration delays
- Mismatched meter IDs → Always fetch the latest data from Scaler before uploading mapping files to ensure IDs are current and valid
- Date format inconsistencies → Confirm the provider uses YYYY-MM-DD or ISO 8601 timestamps. Non-standard formats will cause rejected records.
- Missing timezone information → If the provider API returns timestamps without timezone data, confirm the assumed timezone before development begins.
Additional resources
- Setting up your API Integration — Step-by-step guide to configuring your API connection in Scaler
- Switching third-party API providers — How to transition between data providers
- ENERGY STAR Portfolio Manager integration — Specific setup guide for ENERGY STAR connections