This topic helps you get started making API calls as a Service User to the m3ter platform. It explains how to quickly get set up to make API calls and provides example calls to help you reach a point where you can begin to submit usage data measurements as a Service User:
If you are using Postman, you can import some sample m3ter collections into your Workspace. If you have downloaded the m3ter Open API spec, you can also import this as a collection into your Workspace in Postman:
Tip: Example Code Snippets. The API call examples include code snippets that you can copy to your clipboard in JSON, cURL, and Python Requests versions.
Follow these steps to get set up as a Service User able to make API calls to m3ter:
Log in to the m3ter Console and under Settings>Users, create a Service User.
Add required Permissions to the new Service User. You must assign Administrator Permissions to a Service User to allow that user to make API calls. See Adding Permissions to Service Users.
More Details? For details of how to complete this step, see Creating and Configuring Service Users.
In the Console, open the Overview page for a Service User and generate an Access Key id and Api Secret.
Make sure you make a copy of the Api Secret.
More Details? For details on how to complete this step, see Generating an API Key and Secret for a Service User.
We maintain an OAuth 2.0 Client Credentials grant type authentication flow for Service User Authentication.
From your preferred OAuth 2.0 client, submit a request to the m3ter OAuth Client Credentials authentication flow using the Access Key id and Api Secret to obtain a Bearer Token for your Service User.
You will need the Bearer Token to make any subsequent API calls.
More Details? For more details on how to complete this step, see Obtaining a Bearer Token Using Basic Auth and see the Auth section of our API Reference Docs.
When you have obtained your Service User Bearer Token at Step 3, you will also need a copy of your Organization Id to make any subsequent API calls.
You can copy this directly to your clipboard from the Settings>Organization Details page in the Console - see Managing your Organization.
You can obtain your Organization Id from the URL in your browser after logging in to the m3ter Console:
https://console.m3ter.com/org/
396d788d-XXXX-4e8b-YYYY-a41f46ZZZZZ3
/settings/users
In this example, the highlighted portion of the URL after /org/
is the Organization Id.
In this example, we submit Meter measurements for an Account to the Ingest API.
API Reference Docs: see Submit measurements
To Submit measurement using Postman:
1. In your Postman Workspace, select to make a POST call and enter this URL as the endpoint:
https://ingest.m3ter.com/organizations/396d788d-XXXX-4e8b-XXXX-aYYYYY3/measurements
Where the portion of the URL endpoint after /organizations/
is your Organization id and which you can copy from the URL in your browser after logging into the m3ter Console - see Step 4 in the previous section.
2. On the Authorization tab, for Type select Bearer Token and copy and paste it into the Token field:
3. Select the Body tab and enter JSON for the request:
In this example:
We're submitting a single measurement for a measure type Data Field on a Meter.
The "uid"
provided for the measurement must be a unique and immutable string.
For the "meter"
parameter, enter the Meter's code
string.
For the "account"
parameter, enter the Account's code
string.
Important! If you submit another measurement using the same "uid"
but with a different "measure"
quantity, an "accepted"
response will be returned but the system interprets this as the same data and ignores the new measure.
Here is the JSON for the Submit measurements request example:
1{2"measurements": [3{4"uid": "258c80a3-0744-4318-866a-681a7b232378",5"meter": "test_meter1",6"account": "doetech_premium",7"ts": "2022-05-11T12:14:41.836Z",8"measure": {9"gb_stored": 3400010}11}12]13}
4. Click Send. You will see that your submitted Meter measurement has been accepted in the Response panel:
If you are working in the cmd line, here's the cURL version for this example Submit Measurements call:
1curl --location --request POST 'https://ingest.m3ter.com/organizations/{orgid}/measurements' \2--header 'Authorization: Bearer {bearerToken}} ' \3--header 'Content-Type: application/json' \4--data-raw '{5"measurements": [6{7"uid": "258c80a3-0744-4318-866a-681a7b232378",8"meter": "test_meter1",9"account": "doetech_premium",10"ts": "2022-05-11T12:14:41.836Z",11"measure": {12"gb_stored": 3400013}14}15]16}'
Here's the Python Requests version of the Submit Measurements call:
1import requests2import json34url = "https://ingest.m3ter.com/organizations/{orgid}/measurements"56payload = json.dumps({7"measurements": [8{9"uid": "258c80a3-0744-4318-866a-681a7b232378",10"meter": "test_meter1",11"account": "doetech_premium",12"ts": "2022-05-11T12:14:41.836Z",13"measure": {14"gb_stored": 3400015}16}17]18})19headers = {20'Authorization': 'Bearer {bearerToken}',21'Content-Type': 'application/json'22}2324response = requests.request("POST", url, headers=headers, data=payload)2526print(response.text)
In this example, we retrieve the Organization config.
API Reference Docs: see Retrieve OrganizationConfig.
To obtain your Organization Config using Postman:
1. In your Postman Workspace, select to make a GET call and enter this URL as the endpoint:
https://api.m3ter.com/organizations/396d788d-XXXX-4e8b-XXXX-a41fZZZZZ3/organizationconfig
2. On the Authorization tab, for Type select Bearer Token and copy and paste it into the Token field:
4. Click Send. Your Organization Config is returned into the Response panel:
In this example, we create a Meter.
API Reference: see Create Meter
To Create a Meter using Postman:
1. In your Postman Workspace, select to make a POST call and enter this URL as the endpoint:
https://api.m3ter.com/organizations/396d788d-XXXX-4e8b-XXXX-a41fZZZZZ3/meters
2. On the Authorization tab, for Type select Bearer Token and copy and paste it into the Token field.
3. Select the Body tab and enter JSON for the request:
Here is the JSON for the Create Meter request example:
1{2"name": "Test Meter 2",3"code": "test_meter2",4"dataFields": [5{6"category": "MEASURE",7"code": "gbs_stored",8"name": "GBStorage",9"unit": "GiBy"10}11],12"derivedFields": [ ]1314}
In this example, we create a Meter with a single Data Field of type Measure, and which has no Derived Fields defined.
Tip: Global or Product Meter? In this example, we have omitted a "product"
parameter from the request body, which means this request will create a Global Meter. If you want to create a Meter belonging exclusively to a specific Product, you must provide the Product id in your request.
4. Click Send. You'll see the newly created Meter details returned in the Response panel:
If you are working in the cmd line, here's the cURL version for this example Create Meter call:
1curl --location --request POST 'https://api.m3ter.com/organizations/{orgid}/meters' \2--header 'Authorization: Bearer {bearerToken}' \3--header 'Content-Type: application/json' \4--data-raw '{5"name": "Test Meter 2",6"code": "test_meter2",7"dataFields": [8{9"category": "MEASURE",10"code": "gbs_stored",11"name": "GBStorage",12"unit": "GiBy"13}14],15"derivedFields": [ ]1617}'
Here's the Python Requests version for this example Create Meter call:
1import requests2import json34url = "https://api.m3ter.com/organizations/{orgid}/meters"56payload = json.dumps({7"name": "Test Meter 2",8"code": "test_meter2",9"dataFields": [10{11"category": "MEASURE",12"code": "gbs_stored",13"name": "GBStorage",14"unit": "GiBy"15}16],17"derivedFields": []18})19headers = {20'Authorization': 'Bearer {bearerToken}',21'Content-Type': 'application/json'22}2324response = requests.request("POST", url, headers=headers, data=payload)2526print(response.text)
If you are working in Postman for making API calls to m3ter, some m3ter Collections are available for you to import into your Postman Workspace. These Collections provide examples of calls you'll typically need to make to the m3ter APIs:
m3ter Sample Auth Collection. Calls required for Authorization, including Get Bearer Token and Create Service User. Import URL is: https://www.getpostman.com/collections/36033de1ccecd9cf90f2
m3ter Open API. The entire set of available API calls for the m3ter platform.
To import an m3ter Collection into your Postman Workspace:
1. In your Postman Workspace, select Collections.
2. Select Import. An Import popup appears.
3. Select the Link tab and enter the URL for the m3ter Collections you want to import:
4. Select Continue. The popup adjusts to show details of the Collection that will be imported:
5. Select to confirm the Import. The Collection is loaded into the Collections panel in your Postman Workspace:
In this example, we've imported the m3ter Sample Auth Collection into our Postman Workspace.
To import the m3ter Open API into your Postman Workspace:
1. Go to the m3ter API Reference documentation.
2. Select to Download the m3ter Open API spec. A swagger.json
file is downloaded into your Downloads folder.
3. In your Postman Workspace, select Collections.
4. Select Import. An Import popup appears.
5. On the File tab, select OpenAPI. A File Upload window appears.
6. Navigate to where you've saved the Open API spec swagger.json
file from the download and select Open. The Import popup adjusts to show the details of the selected file and the Generate collection from imported APIs option is selected by default:
7. Select Import. A message appears confirming the import was successful. Click Close. The m3ter API is loaded into the Collections panel in your Postman Workspace:
Next: HTTP Error Codes
Login to the Support portal for additional help and to send questions to our Support team.