> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m3ter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started with API Calls
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:
* [Setting Up for Service User API Calls](/guides/m3ter-apis/getting-started-with-api-calls#setting-up-for-service-user-api-calls)
* [Example 1: Submit Measurements](/guides/m3ter-apis/getting-started-with-api-calls#example-1-submit-measurements)
* [Example 2: Get Organization Config](/guides/m3ter-apis/getting-started-with-api-calls#example-2-get-organization-config)
* [Example 3: Create Meter](/guides/m3ter-apis/getting-started-with-api-calls#example-3-create-meter)
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:
* [Importing m3ter Collections into your Postman Workspace](/guides/m3ter-apis/getting-started-with-api-calls#importing-m3ter-collections-into-your-postman-workspace)
**Tip: Example Code Snippets.** The API call examples include code snippets that you can copy to your clipboard in **JSON**, **cURL**, or **Python Requests** versions.
## Setting Up for Service User API Calls
Follow these steps to get set up as a Service User able to make API calls to m3ter:
#### Step 1: Create a Service User and add Permissions
* 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](/guides/organization-and-access-management/managing-users#adding-permissions-to-service-users).
**More Details?** For details of how to complete this step, see [Creating and Configuring Service Users](/guides/organization-and-access-management/managing-users#creating-and-configuring-service-users).
#### Step 2: Generate Access Keys for the Service User.
* 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](/guides/authenticating-with-the-platform/service-authentication#generating-an-api-key-and-secret-for-a-service-user).
#### Step 3: Use Basic Authentication to obtain a Bearer Token.
* 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](/guides/authenticating-with-the-platform/service-authentication#obtaining-a-bearer-token-using-basic-auth) and see the [Auth section](/api/auth/get-token) of our API Reference Docs.
#### Step 4: Copy your Organization Id.
* When you've obtained your Service User Bearer Token at Step 3, you'll 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](/guides/organization-and-access-management/viewing-and-editing-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 portion of the URL after `/org/` is the Organization Id.
## Example 1: Submit Measurements
In this example, we submit Meter measurements for an Account to the Ingest API. In addition to the JSON shown for the example request made through Postman, code versions using other common languages are given and can be copied directly to your clipboard:
* [cURL Version](/guides/m3ter-apis/getting-started-with-api-calls#curl-version)
* [JavaScript Version](/guides/m3ter-apis/getting-started-with-api-calls#javascript-version)
* [Python Requests Version](/guides/m3ter-apis/getting-started-with-api-calls#python-requests-version)
* [Java Version](/guides/m3ter-apis/getting-started-with-api-calls#java-version)
**API Reference Docs:** see [Submit measurements](/api/measurements/introduction)
**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](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 **Settings>Organization details** page or from the URL in your browser after logging into the m3ter Console - see [Step 4](/guides/m3ter-apis/getting-started-with-api-calls#step-4-copy-your-organization-id) 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:
```json theme={null}
{
"measurements": [
{
"uid": "258c80a3-0744-4318-866a-681a7b232378",
"meter": "test_meter1",
"account": "doetech_premium",
"ts": "2022-05-11T12:14:41.836Z",
"measure": {
"gb_stored": 34000
}
}
]
}
```
4. Click **Send**. You will see that your submitted Meter measurement has been accepted in the **Response** panel:
### cURL Version
If you are working in the cmd line, here's the **cURL** version for this example **Submit Measurements** call:
```bash theme={null}
curl --location --request POST 'https://ingest.m3ter.com/organizations/{orgid}/measurements' \
--header 'Authorization: Bearer {bearerToken}} ' \
--header 'Content-Type: application/json' \
--data-raw '{
"measurements": [
{
"uid": "258c80a3-0744-4318-866a-681a7b232378",
"meter": "test_meter1",
"account": "doetech_premium",
"ts": "2022-05-11T12:14:41.836Z",
"measure": {
"gb_stored": 34000
}
}
]
}'
```
### JavaScript Version
Here's the **JavaScript** version of the **Submit Measurements** call:
```javascript theme={null}
const data = {
measurements: [
{
uid: '258c80a3-0744-4318-866a-681a7b232378',
meter: 'test_meter1',
account: 'doetech_premium',
ts: '2022-05-11T12:14:41.836Z',
measure: {
gb_stored: 34000
}
}
]
};
fetch('https://ingest.m3ter.com/organizations/{orgid}/measurements', {
method: 'POST',
headers: {
'Authorization': 'Bearer {bearer token}',
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
}).then((response) => {
console.log(response.json());
});
```
### Python Requests Version
Here's the **Python Requests** version of the **Submit Measurements** call:
```python theme={null}
import requests
import json
url = "https://ingest.m3ter.com/organizations/{orgid}/measurements"
payload = json.dumps({
"measurements": [
{
"uid": "258c80a3-0744-4318-866a-681a7b232378",
"meter": "test_meter1",
"account": "doetech_premium",
"ts": "2022-05-11T12:14:41.836Z",
"measure": {
"gb_stored": 34000
}
}
]
})
headers = {
'Authorization': 'Bearer {bearerToken}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
### Java Version
Here's the **Java** version of the **Submit Measurements** call:
```java theme={null}
package org.example;
import org.apache.http.HttpResponse;
import org.apache.http.HttpStatus;
import org.apache.http.client.fluent.Request;
import org.apache.http.entity.ContentType;
import org.apache.http.util.EntityUtils;
import java.io.IOException;
public class Main {
public static void main(String[] args) throws Exception {
new Main().start();
}
private void start() throws Exception {
System.out.println("Making POST request");
String response = post("https://ingest.m3ter.com/organizations/{orgid}/measurements", "{
\"measurements\": [
{
\"uid\": \"258c80a3-0744-4318-866a-681a7b232378\",
\"meter\": \"test_meter1\",
\"account\": \"doetech_premium\",
\"ts\": \"2022-05-11T12:14:41.836Z\",
\"measure\": {
\"gb_stored\": 34000
}
}
]
}");
System.out.println("Response = " + response);
}
private String post(String endpoint,
String body) throws IOException {
Request request = Request.Post(endpoint)
.bodyString(body, ContentType.APPLICATION_JSON)
.addHeader("Authorization", "Bearer {bearer token}");
HttpResponse response = request.execute().returnResponse();
int httpCode = response.getStatusLine().getStatusCode();
if (httpCode != HttpStatus.SC_OK) {
// Implement error handling here
return null;
}
return EntityUtils.toString(response.getEntity());
}
}
```
## Example 2: Get Organization Config
In this example, we retrieve the Organization config.
**API Reference Docs:** see [Retrieve OrganizationConfig](/api/organizationconfig/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](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:
## Example 3: Create Meter
In this example, we create a Meter.
**API Reference:** see [Create Meter](/api/meter/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](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:
```json theme={null}
{
"name": "Test Meter 2",
"code": "test_meter2",
"dataFields": [
{
"category": "MEASURE",
"code": "gbs_stored",
"name": "GBStorage",
"unit": "GiBy"
}
],
"derivedFields": [ ]
}
```
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:
### cURL Version
If you are working in the cmd line, here's the **cURL** version for this example **Create Meter** call:
```bash theme={null}
curl --location --request POST 'https://api.m3ter.com/organizations/{orgid}/meters' \
--header 'Authorization: Bearer {bearerToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Test Meter 2",
"code": "test_meter2",
"dataFields": [
{
"category": "MEASURE",
"code": "gbs_stored",
"name": "GBStorage",
"unit": "GiBy"
}
],
"derivedFields": [ ]
}'
```
### Python Requests Version
Here's the **Python Requests** version for this example **Create Meter** call:
```python theme={null}
import requests
import json
url = "https://api.m3ter.com/organizations/{orgid}/meters"
payload = json.dumps({
"name": "Test Meter 2",
"code": "test_meter2",
"dataFields": [
{
"category": "MEASURE",
"code": "gbs_stored",
"name": "GBStorage",
"unit": "GiBy"
}
],
"derivedFields": []
})
headers = {
'Authorization': 'Bearer {bearerToken}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
## Importing m3ter Collections into your Postman Workspace
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:
* [Importing the m3ter Open API](/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-open-api)
* **m3ter Open API**. The entire set of available API calls for the m3ter platform.
* [Importing the m3ter-Template API Collection](/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-template-api-collection)
* **m3ter-Template Collection**. A set of templated calls arranged by key functional area and covering calls for common operations in these areas.
### Importing the m3ter Open API
**To import the m3ter Open API as a Collection into your Postman Workspace:**
1. Go to the m3ter [API Reference documentation](/api).
2. In the **Getting Started** section, select **Postman**.
3. On the **Postman** page, select the **m3ter Open API spec JSON file** link:
* A `spec.json` file opens in a separate browser tab.
4. **Save** the file locally.
5. In your Postman Workspace, select **Import**:
* An **Import** dialog appears:
6. Select to import **files**. A **File Upload** window appears.
7. Navigate to where you've saved the `spec.json` file locally and select **Open**:
* The **Import** dialog adjusts to show progress for the import process.
* When the import process has completed, you can select how you want to complete the import:
* In this example, we've selected to import the file as a **Postman Collection**.
8. Select **Import**.
* The m3ter API is loaded into the **Collections** panel in your Postman Workspace:
### Importing the m3ter-Template API Collection
**To import the m3ter-Template Collection into your Postman Workspace:**
1. Go to the m3ter [API Reference documentation](/api).
2. In the **Getting Started** section, select **Postman**.
3. On the **Postman** page, copy the link provided for the **m3ter-Template API Collection**:
4. In your Postman Workspace, select **Collections**.
5. Select **Import**:
* An **Import** dialog appears.
6. Paste the URL link into the import target field on the dialog.
* The **m3ter-Template API Collection** is imported into your Workspace:
