Integration Basics
❓ When do monthly fetches run for integrations?
Answer
Monthly integrations fetch and sync data on the 1st of each month, typically between 02:00–06:00 UTC.
Some integrations (like ENERGY STAR Portfolio Manager – ESPM) run daily instead of monthly.
Exact timing can vary depending on integration type and provider configuration.
❓ Are Scaler’s APIs exposed via an API gateway?
Answer
Scaler uses a central application layer as the primary entry point for API traffic. This layer:
- routes incoming requests to the correct backend services
- centralizes authentication
- supports microservice-based architecture
- allows for performance optimizations
From a client perspective, you interact with a single, consistent API layer, even though multiple services operate behind it.
❓ Where can I find Scaler’s API documentation?
❓ Can other organisations push data into Scaler via API?
Answer
Currently, no. Scaler does not allow external systems to push data into the platform via a general-purpose inbound API.
Today, Scaler focuses on:
- securely fetching ESG and utility data from external providers
- exposing Scaler data via an API for clients who want to pull data from Scaler
Supporting push-based write APIs would require:
- expanded security and authentication infrastructure
- extensive validation and data quality mechanisms
- higher and clearer client demand
For these reasons, inbound push APIs are not supported at this time.
Meters, Versions & Mapping
❓ Do syncs automatically use the latest meter version?
Answer
Yes. Scaler syncs per meter, not per meter version.
- Integrations fetch consumption data for a meter as a whole
- Meter versions in Scaler are important for calculations, but not for the integration logic
- The integration uses whichever version is currently mapped to the external meter
❓ Can I select a specific meter version for syncing?
Answer
No.
The meter mapping determines which version is used. Once a meter is mapped to an external meter, the sync will use the appropriate version automatically. No manual version selection is needed (or possible) in the integration.
❓ Does Scaler only support 1:1 mapping between external and Scaler meters?
Answer
Yes – from the perspective of how data is written into Scaler:
- One external meter is mapped to one Scaler meter to avoid duplicate consumption records.
- Mapping multiple external meters to a single Scaler meter would create duplicate or overlapping data, since no aggregation happens at this step.
It is possible to reuse one external meter’s data across more than one Scaler meter (for example, by configuring additional logic or duplication), but this is a special case and not a standard aggregation/disaggregation feature of mappings.
ESPM Setup & Backups
❓ How do we set up a new client to sync their ESPM data, or add assets to an existing ESPM integration?
Answer
To set up ESPM syncing for a client, Scaler needs:
- the full list of the client’s ESPM Property IDs that should be connected
ESPM properties can be:
- owned directly in the client’s ESPM account, or
- shared by consultants or third parties
Confirming the property IDs ensures we fetch the correct assets and meters.
❓ What happens if a client provides ESPM credentials but has not mapped all their meters yet? Does backup still run?
Answer
Yes. Once ESPM is configured and the backup job is enabled:
- Scaler can fetch and back up all ESPM asset and meter information, even if not all meters are mapped yet.
- Mapping is required for syncing consumption data into Scaler meters, but the ESPM backup can still run in parallel and store a full copy of the metadata.
The backup job is separate from the mapping and syncing steps.
❓ What are the steps to set up the ESPM full backup?
Answer
When ESPM is enabled for a client, three recurring jobs are configured:
- Fetch assets and meters (entities)
- Fetch consumptions and readings (usage)
- Fetch and store a full backup of all assets and meters to cloud storage (S3)
This setup ensures both operational syncing and long-term backup of ESPM data.
Fetches & Syncs
❓ When do fetches and syncs happen?
Answer
ESPM:
- Fetches and syncs daily, typically between 02:00–06:00 UTC
- Average performance: about 20 minutes per 1,000 meters
- Example: a portfolio with 2,700 meters would complete around 06:50 UTC
All other incoming integrations:
- Fetch and sync monthly once live in production
- Schedule: 1st of each month, typically 02:00–06:00 UTC
❓ How does the fetch process work?
Answer
For each client and integration, Scaler runs a separate “fetch job” that usually follows these steps:
- Fetch data from the provider
- Process the raw data into Scaler’s internal structure
- Validate it against business rules and data quality constraints
- Store it in Scaler
Jobs are queued and processed one at a time per worker. This prevents conflicts, ensures stable orchestration, and avoids dropped or partially handled jobs.
❓ How does the sync process work, technically?
Answer
In Scaler integrations, a usage represents a consumption record (consumption, redelivery, or meter reading).
For each usage:
- On creation, it receives
created_atandupdated_attimestamps
- When a provider updates that usage, only
updated_atchanges
Syncs use updated_at as the sync date:
- The first sync imports all available usages
- Subsequent syncs (Sync N+1) send the last
sync_date
- The integration then fetches only usages with
updated_atnewer than that date
- If nothing has changed, no records are updated
This approach improves efficiency by avoiding full re-checks of all historical records.
Performance guideline: approximately 100 meters per 5 minutes of sync time.
❓ What do “active” and “inactive” mean for meters and usages?
Answer
Usages (consumption records):
- When a usage is first fetched, it is marked active
- If it disappears in a later fetch (deleted, disabled, or removed upstream), it is marked inactive
- Inactive usages are hidden in the consumptions UI but remain stored for history and potential restoration
Meters:
- When a meter is set to inactive, it still appears in the UI
- Scaler simply stops updating it with new data
Integration Roadmap & Prioritization
❓ When will a specific integration request be ready?
Answer
Integration timelines are prioritized based on:
- ARR impact (annual recurring revenue affected)
- Number of clients who will use the integration
- Strategic and operational urgency
In rare cases, business-critical situations may be prioritized ahead of the roadmap.
If you have a specific integration in mind, your Scaler contact can share whether it is:
- already on the roadmap
- under evaluation
- or requires additional scoping and demand validation.
Meter Data Types
❓ What is the “Data type” field in meter details and how is it used?
Answer
The Data type field describes how consumption data is structured and/or delivered.
Available options:
- Consumption recording
- Meter reading
- API connection
Consumption recording
- Represents usage over a time period
- Has a start date, end date, and the consumption value
- Example:
- Jan 31 reading: 12,350 kWh
- Feb 28 reading: 13,600 kWh
- Consumption in February: 1,250 kWh
Meter reading
- A point-in-time cumulative measurement (like a car’s odometer)
- Uses a single date for when the reading was taken
API connection
- Indicates that data is managed via an API
- Scaler Spreadsheet uploads will not overwrite data for meters marked as “API connection”
- Note: currently, the “Meter reading” data type must be selected to support meter-reading-style records, which can in some rare cases still allow spreadsheet overwrites. This is a known limitation that Scaler is addressing.
API Mapping
❓ What is the purpose of API Mapping?
Answer
API Mapping links internal Scaler assets and meters to the corresponding assets and meters in third-party systems.
Benefits:
- Automated collection of consumption data
- Reduced manual data entry
- More accurate and up-to-date reporting
❓ Who can use the API Mapping feature and where is it located?
Answer
- Available to Scaler internal teams (such as Account Operations) in production
- Available to clients behind a feature flag, and will be released more broadly with Bulk Meter Mapping
Location in the Scaler app:
Collection → Asset → API mappings
❓ How do I map internal assets to third-party assets?
Answer
- Go to the API Asset Mappings page
- Select the asset you want to map
- Choose the corresponding third-party asset from the list
- Confirm the mapping
One internal asset can be mapped to multiple external assets, which supports scenarios like:
- separate providers for energy, water, and waste for the same physical asset
❓ Can I map a single internal asset to multiple third-party assets?
Answer
Yes. One internal asset can be mapped to multiple external assets.
This is useful if different providers manage different resource types (e.g. one for electricity, another for water) for the same building.
❓ How do I map internal meters to third-party meters?
Answer
- From the API Asset Mappings page, select the asset whose meters you want to map
- Select the internal meter
- Choose the corresponding third-party meter
- Confirm the mapping
- One internal meter can be mapped to multiple external meters if needed
- This supports cases where data is sourced from multiple providers for the same logical meter
❓ Can I map a single external meter to multiple internal meters?
Answer
No.
The system does not support mapping multiple internal meters to a single external meter.
- No disaggregation (one external → many internal)
- No aggregation (many external → one internal) at the meter level
However, multiple external assets can be mapped to a single internal asset, when that better reflects how the real-world site is modeled.
❓ How can I map multiple assets and meters at once (Bulk Meter Mapping)?
Answer
Bulk meter mapping lets you create many asset and meter mappings via a CSV template.
Steps:
- Download the meter mapping template from the API Mapping area
- Fill in required fields such as:
scaler_asset_idscaler_meter_id
- Upload the template for the correct portfolio
Notes:
- Mappings can be created via bulk upload but not deleted via this method
- A file containing mappings across multiple portfolios must be uploaded once per portfolio
❓ What errors might I see during bulk uploads, and what do they mean?
Answer
Examples of possible errors:
- File cannot be parsed
- File format incorrect or template modified in an unsupported way
- Asset was not found in Scaler: {scaler_asset_id}
- Asset doesn’t exist in the selected portfolio
- Asset was not found in Integration: {external_asset_id}
- External asset ID is invalid or has been changed
- The external asset is already mapped to a different Scaler ID
- Asset mapping error: asset already mapped or not found in the integration
- Meter was not found in Integration: {external_meter_id}
- Scaler Meter with given ID was not found
- Scaler Meter history record not found
- Error processing mappings (general error – contact support)
These errors appear in dedicated error columns in the template, highlighting the rows that need correction.
❓ What if I cannot find the third-party meter or asset I want to map?
Answer
Possible reasons:
- The asset/meter has not been fetched yet from the third-party API
- The asset is already mapped (so its meters may not appear as expected)
- The integration configuration is incomplete
Steps to take:
- Check if the asset or meter is already mapped
- Confirm that the relevant data has been fetched from the provider
- If it still doesn’t appear, contact Scaler support for further investigation
❓ How do I unmap an existing asset or meter?
Answer
- Go to the API Mapping page
- Find the asset or meter you want to unmap
- Use the unmap (trash/delete) action
- Confirm the unmapping
⚠️ Important: If you unmap an asset or meter that already has synced consumption data, that data will no longer be connected to the integration.
❓ Can I review data after it has been mapped and synced?
Answer
Yes.
- On the Asset Mappings page, you can see how many meters are mapped out of the total for each asset
- On the Meter Mapping page, you can see:
- how many consumptions were synced
- how many failed
- detailed validation messages for partial or failed syncs
You can inspect individual consumption records, including errors that prevented some records from syncing.
Bill Scraping
❓ How does Bill Scraping work with Scaler?
Answer
Scaler integrates with Nectar to automatically process utility bills.
Duplicate prevention:
- Scaler creates a hash of each uploaded file and checks if an identical file already exists
- If a duplicate is found, that file is not uploaded or sent to Nectar
- Other non-duplicate files in the same batch are still processed
Nectar also runs its own duplicate checks. Files detected as duplicates are marked accordingly and cannot be mapped or synced.
❓ What do the different statuses in the Bill Upload Log mean?
Answer
Possible statuses (rough order of user flow):
- 🔵 Pending – The bill has been uploaded and received by Nectar
- 🔴 Failed – The bill could not be processed (invalid PDF, not a bill, or another error)
- 🔴 Duplicate – A duplicate bill was detected (by Scaler or Nectar)
- 🟡 Missing asset mapping – The asset must be mapped before the bill can be synced
- 🟡 Missing meter mapping – The meter must be mapped before syncing can complete
- 🔵 Syncing – Data is being fetched and processed from Nectar
- 🟢 Synced – The bill was successfully processed and consumptions have been created
In some cases, assets and meters may already be known from previous bills, but new consumption records still require an additional fetch step for usage data after bill scraping.
Bill Scraping Setup
❓ What are the steps to set up bill scraping for a new client using Nectar?
Answer
A typical setup flow is:
- Create or configure a test account (or relevant environment) in Scaler for the client
- Create the corresponding account in Nectar
- Upload sample or initial bills to Nectar
- Create meters in Scaler based on the identifiers from the scraped bills
- Map Scaler meters to the scraped meter identifiers once processing is complete
- Trigger a sync so that consumption data flows into Scaler
- Verify that the consumptions have been created correctly in Scaler