Getting Started

The EnergyCAP REST API lets you programmatically access and manage your organization’s energy data. You can retrieve meters, bills, accounts, cost centers, and more — or push data in from external systems.

The API is language-agnostic: any HTTP client works. All requests and responses use JSON.

Quick Start

Here’s everything you need to make your first API call:

1. Get your API key

API keys are created in EnergyCAP under API Keys and Webhooks by a user with Application Settings: Manage permission. See Authentication for details.

2. Identify your environment

Your base URL depends on where your organization is hosted. Common environments include:

Environment Base URL
US East (Production) https://app.energycap.com
US West https://wce.energycap.com
EU https://app-eu.energycap.com

See Environments for the full list, including implementation and alias URLs.

3. Make a request

curl -X GET "https://app.energycap.com/api/v3/meter" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

A successful response returns a JSON array of meter objects with a 200 OK status.

Base URL Structure

All requests follow this pattern:

https://{environment}/api/{version}/{resource}
Component Description
{environment} Your organization’s host (see Environments)
{version} API version, e.g. v3 or v202407
{resource} The endpoint, e.g. meter, bill, account

HTTP Methods

GET Retrieve a resource or list of resources

POST Create a new resource

PUT Replace an existing resource (all fields required in the body)

DELETE Remove a resource

Required Headers

Every request must include these headers:

Header Value Description
ECI-ApiKey Your API key Authenticates the request
Content-Type application/json Required for all requests. Some file-upload endpoints use application/octet-stream instead

Response Format

Successful responses

Responses return JSON. Single-resource endpoints return an object. List endpoints return an array and support paging.

Nested objects

The API includes commonly needed related data directly in responses to reduce round trips. For example, a meter response includes its related account, commodity, and primary use inline rather than requiring separate requests:

{
  "meterId": 1234,
  "meterCode": "METER1234",
  "meterInfo": "Meter 1234",
  "commodity": {
    "commodityId": 1,
    "commodityCode": "ELECTRIC",
    "commodityInfo": "Electric"
  },
  "accounts": [
    {
      "accountId": 1234,
      "accountCode": "ACCT1234",
      "accountInfo": "Account 1234"
    }
  ],
  "primaryUse": {
    "primaryUseId": 1,
    "primaryUseCode": "METERUSE1",
    "primaryUseInfo": "Meter Use 1"
  }
}

Use field reduction to limit which fields are returned if you don’t need everything.

Status Codes

Code Meaning What to do
200 OK Request succeeded
201 Created Resource was created successfully
204 No Content Request succeeded, no body returned (common for DELETE)
400 Bad Request Check your request body and parameters for errors
401 Unauthorized Your API key is missing, invalid, or the user lacks permission
403 Forbidden The server understood the request but refuses to authorize it
404 Not Found The resource doesn’t exist — verify the ID or path
405 Method Not Allowed This HTTP method isn’t supported on the endpoint
406 Not Acceptable The request’s Accept header is incompatible with the response
429 Too Many Requests You’ve hit the rate limit — back off and retry
500 Internal Server Error Something went wrong on our end — contact support if it persists

Rate Limiting

Rate limits are enforced on a growing number of endpoints to ensure availability for all users. If you exceed the limit, the API returns 429 Too Many Requests.

How to handle it:

  • Implement a retry strategy with a delay of 5–10 seconds after receiving a 429
  • Do not retry immediately — this keeps the rate limit active
  • For bulk operations, batch your requests and add a short delay between calls

API Versioning

The API version in the URL (e.g. v3, v202407) is independent of the EnergyCAP application version. A version only changes when there are breaking changes to the request or response format. See API Versioning for details on our versioning policy.

Next Steps