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.
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.
$ 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"
}'
{"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.
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/'\
'download-data' \-o output.xlsx \-X GET \-H "Authorization: BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
./output.xlsxRequest for fetching service account details
Clients can get utility service account info using - /accounts/:accountId/utility-service-accounts/:utilityServiceAccountId/info
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/info' \-X GET \-H "Authorization: BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
{"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
$ curl 'https://app.omnimetic.com/api/accounts/:accountId/'\
'utility-service-accounts/:utilityServiceAccountId/'\
'historical-data?year=YYYY' \-L -X GET \-H "Authorization: BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
[{"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
$ 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: BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SW
QiOiI2MTcxN2Y5YWE4MTdkNDAwMTY1Y2M4NWEiLCJpYX
QiOjE2MzcxNjY5NjQsImV4cCI6MTYzNzI1MzM2NH0.B46vxt
mf-21bc_QL0W28Y_PKWm13VGLk6IS1wpfGtfs"
[{"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.
200 - OK Everything worked as expected.400 - Bad request Unacceptable request, often due to missing a required parameter.401 - Unauthorized Unauthorized access or invalid token404 - Not Found The requested resource doesn't exist.500 - Server Error Something went wrong on Omnimetic's end.