Docs
Docs

Home

Introduction
OmniConnect Flow
Integration Steps
Troubleshooting
Docs
GETTING STARTED
  • Home
  • Introduction
    OmniConnect Flow
    Integration Steps
    Troubleshooting
  • Introduction
    Authentication
    Utility Data
    Service Account Details
    Historical Data
    Interval Data
    Errors
© 2021 Omnimetic
Get Started
API Reference
Comprehensive reference for integrating with Omniconnect API
Introduction
Omnimetic APIs are organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Currently our Omnimetic APIs works with production mode only but soon we will be offering sandbox where you can test our APIs without affecting your live data. The API key you use to authenticate the request help us to determine API call source and provide better support.
BASE URL
https://app.omnimetic.com/api
* By default, the Omnimetic API Docs demonstrate using curl to interact with the API over HTTP.
Authentication
Omnimetic uses access token generated against API Keys to authenticate requests. You can view and manage your API keys in the Omnimetic Console.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Omnimetic token has a one-hour active life, and will need to be replaced after one hour of inactivity. Please note that both client id and secret key need to be provided to indicate you want to authenticate.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
ACCESS TOKEN REQUEST
$ curl 'https://app.omnimetic.com/api/access-token' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"clientId": "e4de5af2-37ab-45a9-88fd-8949b045bf92",
"name": "Omnimetic",
"secret": "e4de5af2-37ab-45a9-88fd-8949b045bf92"
}'
RESPONSE EXAMPLE
{
"id": "61717f9aa817d400165cc85a"
"token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50S
WQiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJp
YXQiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46
vxtmf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
}
Utility Data
Clients can download utility data for any connected utility service account using - /accounts/:accountId/utility-service-accounts/:utilityServiceAccountId/download-data
accountId & bearer token can be obtained from authentication API to make API request successfully.
utilityServiceAccountId - Recieved during successful account connection through OmniConnect SDK.
UTILITY DATA REQUEST
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/'\
'download-data' \
-o output.xlsx \
-X GET \
-H "Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
RESPONSE EXAMPLE
./output.xlsx
Request for fetching service account details
Clients can get utility service account info using - /accounts/:accountId/utility-service-accounts/:utilityServiceAccountId/info
SERVICE ACCOUNT DETAILS REQUEST
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/info' \
-X GET \
-H "Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
RESPONSE EXAMPLE
{
"id": "64d4a4ba8061ed001f6159cf",
"externalServiceAccountId": "64d4a4ba8061ed001f6159ce",
"address": {
"street": "jaipur", "city": "jaipur", "state": "RJ", "postalCode": "201203"
},
"linkedDate": "2023-08-10T08:50:02.621Z",
"legalNames": ["John"],
}
Request for fetching historical data
Clients can get historical data info using - /accounts/:accountId/utility-service-accounts/:utilityServiceAccountId/historical-data
HISTORICAL DATA REQUEST
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/'\
'historical-data?year=YYYY' \
-L -X GET \
-H "Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
RESPONSE EXAMPLE
[
{
"id": "650e54bebe364f001939392b",
"utilityUserAccount": {
"_id": "6500260c0fcc610013b84928"
},
"serviceAccount": {
"_id": "6500260c0fcc610013b84929"
},
"utilityCompany": {
"_id": "64a4167b4945ba8fb83f2b33"
},
"month": "August",
"offPeakUsageInWatts": 0,
"onPeakUsageInWatts": 0,
"year": 2023,
"amountInCents": 1128,
"energyConsumptionInWatts": 677270.4,
},
]
Request for fetching interval data
Clients can get interval data info using - /accounts/:accountId/utility-service-accounts/:utilityServiceAccountId/interval-data
INTERVAL DATA REQUEST
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/'\
'interval-data?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD' \
-L -X GET \
-H "Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
RESPONSE EXAMPLE
[
{
"id": "65237aedd518190012ef765c",
"utilityUserAccount": {
"_id": "6500260c0fcc610013b84928"
},
"serviceAccount": {
"_id": "6500260c0fcc610013b84929"
},
"utilityCompany": {
"_id": "64a4167b4945ba8fb83f2b33"
},
"date": "2023-10-07T23:00:00.000Z",
"hour": "23:00",
"onPeakUsage": 0,
"offPeakUsage": 4.72,
"totalUsage": 1,
},
]
Errors
Omnimetic uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Omnimetic's servers.
HTTP STATUS CODE SUMMARY
200 - OK Everything worked as expected.
400 - Bad request Unacceptable request, often due to missing a required parameter.
401 - Unauthorized Unauthorized access or invalid token
404 - Not Found The requested resource doesn't exist.
500 - Server Error Something went wrong on Omnimetic's end.