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 with your provider's API or technical team before onboarding starts.
This article covers integrations where Scaler connects to your provider's API and collects the data on a schedule (pull). If your provider wants to send data to Scaler instead, they use the Scaler Push API, documented at docs.scalerglobal.com/push-api. If your provider can only export files, see SFTP file delivery requirements.
Integration process overview
Setting up an API integration involves four key phases:
- Preparation: confirm API readiness and align on technical requirements (3 to 4 weeks)
- Development: build and test the API connection in a staging environment (about 2 weeks)
- Mapping: align fields between the external platform and Scaler (1 to 4 weeks)
- Synchronization: validate data flow between systems (under 1 day)
End to end, expect 6 to 10 weeks. Timelines depend on provider responsiveness, documentation quality, number of fields, and how quickly inputs are provided.
How the integration works
Scaler connects to your provider's API on a schedule 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.
Scaler mirrors what the provider's API returns. If a meter stops appearing in the API response, Scaler deactivates it. If a reading stops appearing for a period Scaler fetches again, Scaler removes it. The provider's API should therefore only leave out records that were deleted at the source.
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 |
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), discuss with the Scaler team during onboarding. For file exports, see Sending files to Scaler over SFTP.
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
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)
The provider should document any limit on the date range per request; Scaler splits larger ranges into chunks.
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.
IP allowlisting
If the provider restricts API access by IP address, allowlist the staging address and the production address for your Scaler region, and issue a separate API key for each environment.
Environment | Source IP address |
Staging | 54.72.1.69 |
Production, Europe | 52.212.20.98 |
Production, Australia | 54.252.84.149 |
Required data
Scaler organizes imported data into assets (buildings), meters (measurement points) and usage records (readings or consumption). The sections below define the fields Scaler needs for each.
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³, liters). |
Description | Optional | A label or name for the meter. |
Additional metadata | Optional | Any extra attributes (e.g. MPAN, serial number). Stored as-is. |
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 |
Energy | Coal, Coke, Diesel, District Chilled Water, District Heating and Cooling, District Hot Water, District Steam, EV Charging, Fuel Oil, Heat Cold Storage, Kerosene, LPG (Propane), Natural Gas, Off-site Electricity, On-site Electricity (Non-renewable), On-site Renewable Electricity, Wood |
Water | Potable, Reclaimed |
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).
Each meter must have an associated unit. The unit must be a standard measurement abbreviation such as kWh, MWh, GJ, m³, liters, therms, or similar.
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: a point-in-time meter reading, a single value at a specific date or timestamp (e.g. a cumulative register reading).
At least one format must be supported. Both formats may be provided simultaneously.
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, or ISO 8601 datetime for sub-daily data. |
End date | Required (consumption) | End of the period, exclusive: the first day after the period (2026-01-01 to 2026-02-01 for January). If the provider uses an inclusive end date, they must state it. Format: YYYY-MM-DD, or ISO 8601 datetime for sub-daily data. |
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 cumulative register 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, same unit as consumption. |
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. |
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.
The end date must be after the start date. A daily record runs from one day to the next (2026-01-01 to 2026-01-02).
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 | Scaler stores credentials encrypted, per connection. |
Sync schedule | Scaler runs integration jobs on a configurable schedule (typically daily, weekly, or monthly). The schedule is agreed during onboarding. |
Sync window | Where the provider API supports it, Scaler limits each sync to recent periods to reduce load. Readings for periods Scaler no longer fetches stay as they are. |
Automatic retry | Scaler retries failed requests automatically on rate-limit (HTTP 429) and server-error (HTTP 5xx) responses, with exponential backoff. |
Troubleshooting | Mapping status shows on the API Mapping tab of the Automations page. For missing or unexpected data, see Troubleshooting missing or unexpected data from an API integration. |
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) for 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 flag this to the Scaler team during the initial call.
Common pitfalls
- 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
- Mapping assets and meters on the Automations page: connecting your provider's sites and meters to Scaler once the integration is live
- Switching third-party API providers: how to transition between data providers
- ENERGY STAR Portfolio Manager integration: setup guide for ENERGY STAR connections
