The platform provides two versions of its OData API. OData v2 supports read-only access and is the primary interface for reporting tools such as Excel and Power BI. OData v4 is a newer API that supports both read and write operations and is intended for system-to-system integrations.
Both versions require objects to be published through a Resource before they can be accessed. See Configuring OData Resources.
OData v2
OData v2 is a read-only interface. It returns data from published objects using URL-based queries and is well suited to connecting reporting tools or building automated data exports.
URL Structure
An OData v2 query URL has two components: the instance identifier, and the object system name. The object name is appended to the base endpoint:
https://api.energysys.com/v2/{instance_id}/OBJECT_NAME
Contact support if you are unsure of your instance identifier.
Endpoints
Two endpoint formats are available, depending on the authentication method used.
OAuth 2.0 authentication:
https://api.{domain}/v2/{instance-id}
Mutual TLS (mTLS) authentication (Prod):
https://api.{region}.energysys.com/odata-cert/resource.svc/{instance_guid}
Mutual TLS (mTLS) authentication (Test):
https://api.test.{region}.energysys.com/odata-cert/resource.svc/{instance_guid}
Contact support for the correct domain and region values for your instance.
OData v4
OData v4 supports GET, POST, PUT, and DELETE operations. It is designed for automated system integrations where external systems need to read and write records directly.
Endpoints
Two endpoint formats are available, depending on the authentication method used.
OAuth 2.0 authentication:
https://api.{domain}/v4/{instance-id}
Mutual TLS (mTLS) authentication:
https://{region}.api.{domain}/v4/{instance-id}
Contact support for the correct domain and region values for your instance.
Discovery Endpoints
Two endpoints help external tools understand the available data structure.
The service document lists available entity sets:
/v4/{instance-id}
The metadata document provides the full schema:
/v4/{instance-id}/$metadata
Supported Operations
GET retrieves records. Requests can return a collection or a single record.
POST creates a new record. The request body must include all required properties. The GUID and id fields are generated automatically and must not be included. An audit comment is required.
PUT updates an existing record. The request body must include the complete record definition and the GUID or unique identifier of the record being updated. An audit comment is required.
DELETE removes a record. The request must identify the record and include an audit comment.
Validation
All write operations are validated before being applied. Validation checks include permissions, required fields, referenced record existence, data validation rules, and data security rules. Requests that fail validation return an error response.
Error Responses
Failed requests return an HTTP status code and a structured error message. Common responses include 404 (record not found) and 409 (conflict when attempting to create a record that already exists).
Common to Both Versions
Authentication
OAuth 2.0 uses a JSON Web Token (JWT) included in the HTTP request as a Bearer token. The token is generated through an application registration in your organisation's Entra ID tenant. This method is commonly used when connecting tools such as Excel, Power BI, or other Microsoft applications.
Mutual TLS (mTLS) uses X.509 client certificates to authenticate the calling system. Each client must present a valid certificate issued by an approved Certificate Authority. This method is recommended for automated system-to-system integrations.
Authorisation
Access is controlled by permission sets configured in the platform. An object must be added to a Resource and included in a permission set before it can be queried. Users or service accounts must have the appropriate roles to perform read, create, update, or delete operations.
Data Formats
The API returns JSON or XML depending on the Accept header in the request. JSON is preferred, as it produces smaller payloads and faster response times.
Filtering Records
Use $filter to restrict results. The following operators are supported: eq (equals), ge (greater than or equal), le (less than or equal), and and (combine conditions).
Filter by a date attribute:
/CONTRACT?$filter=PRODUCTION_DATE eq datetime'2024-01-01T00:00:00'
Filter by modification date, useful for incremental extracts:
/CONTRACT?$filter=EU_MODIFIED_AT ge datetime'2024-01-01T00:00:00'
Combine conditions:
/CONTRACT?$filter=STATUS eq 'Active' and PRODUCTION_DATE eq datetime'2024-01-01T00:00:00'
Selecting Attributes
By default, all attributes are returned. Use $select to limit the response to specific fields and reduce payload size:
/CONTRACT?$select=NAME,PRODUCTION_DATE,VALUE
Limiting Results
Use $top to cap the number of records returned. This is useful when testing queries:
/CONTRACT?$top=10&$filter=STATUS eq 'Active'
URL Encoding
When constructing queries manually, encode special characters: %20 for a space, %27 for a single quote.