# API integration

The Efento Cloud API enables you to securely retrieve measurement data from sensors connected to your Organization. Using the API, you can pull data from all sensors or only selected devices, depending on your needs. **Before accessing any data, you must** [**generate an API token**](/efento-cloud/advanced/editor/api-tokens.md)**, which authorizes your requests and ensures secure communication with the platform.**

In this chapter, you will find step-by-step examples showing how to use the API to:

* retrieve the most recent measurements from all sensors within a chosen location, and
* download historical measurement data for a specific time period.

These examples will help you quickly integrate Efento Cloud data with your own applications, dashboards, or analytical tools.

{% stepper %}
{% step %}

## Get lists of organisations

Check the IDs of the organisations, to which you have access, by sending the following request to Efento API:

**Method**: GET

**Endpoint**: <https://cloud.efento.io/api/v2/organizations>

**Headers**: Authorization: <mark style="color:red;">API token</mark> (e.g. “adsFcdc34rf…”)

In the response from Efento API, you will receive JSON that contains the list of all the organisations to which you have access along with their IDs and names:

```json
{
   "totalCount": 1,
   "organizations": [
       {
           "id": 2881,
           "name": "Organisation 1",
           "createdAt": "2022-05-25 11:09:27",
           "updatedAt": "2022-05-25 11:09:27",
           "token": "hf04gb0e-bsd3-440c-9fb9-ad0daad420e0",
           "smsSent": 0,
           "smsLeft": 0,
           "licensesLeft": 0,
           "measurementPointsCount": 1
       },
       ]
}
```

**You will need the ID of the organisation in the next request ("id": 2881).**

{% endstep %}

{% step %}

## Get list of all locations in your organisation

Sensors in organisations are grouped by locations. To receive the list of all locations in your organisation use the following request:

**Method**: GET

**Endpoint**: <https://cloud.efento.io/api/v2/locations?organization-id=><mark style="color:red;">ID-OF-YOUR-ORGANISATION</mark> (*e.g.  <https://cloud.efento.io/api/v2/locations?organization-id=2881>*)

**Headers**: Authorization: <mark style="color:red;">API token</mark> (e.g. “adsFcdc34rf…”)

In the response from Efento API, you will receive JSON that contains the list of all the locations to which you have access along with their IDs and names:

```json
{
   "locations": [
       {
           "id": 5655,
           "name": "TOP",
           "organizationId": 2881,
           "createdAt": "2022-05-25 11:09:27",
           "parentId": 0
       }
   ],
   "totalCount": 1
}
```

**You will need the ID of the location in the next request ("id": 5655).**

{% endstep %}

{% step %}

## Get list of the measurement points with their most recent measurements

To receive the list of all measurement points in the selected location use the following request:

**Method**: GET

**Endpoint**: <https://cloud.efento.io/api/v2/measurement-points?location-ids=><mark style="color:red;">ID-OF-THE-LOCATION</mark> (*e.g.  <https://cloud.efento.io/api/v2/measurement-points?location-ids=5655>* )

**Headers**: Authorization: <mark style="color:red;">API token</mark> (e.g. “adsFcdc34rf…”)

{% hint style="info" %}
By default, the API returns the first 20 measurement points assigned to the organisation. If your organisation contains more than 20 measurement points, you need to use pagination to retrieve the information about all the devices.
{% endhint %}

To retrieve more measurement points use th following request: <https://cloud.efento.io/api/v2/measurement-points?location-ids=><mark style="color:red;">ID-OF-THE-LOCATION</mark>&<mark style="color:red;">limit=20</mark>&<mark style="color:red;">offset=0</mark> (*e.g. <https://cloud.efento.io/api/v2/measurement-points?location-ids=5655\\&limit=20\\&offset=0>*)

**limit** - number of the measurement points you want to retrieve (min. 20, max.100)

**offset**  - offset used to shift the measurement points retrieved by the request (e.g. to retrieve first 100 measurement points use “...\&limit=100\&offset=0”, to retrieve second 100 measurement points use “...\&limit=100\&offset=100”, to retrieve third 100 measurement points, use “...\&limit=100\&offset=200”, etc.)

In the response from Efento API, you will receive JSON that contains the list of all the measurement points assigned to the selected location along with their IDs and names and the value of the most recent measurement:

```json
{
   "measurementPoints": [
       {
           "id": 989330,
           "locationId": 5655,
           "createdAt": "2022-05-25 12:17:22",
           "name": "40EBEC",
           "unconfirmedAlertsCount": 358,
           "activeAlertsCount": 0,
           "status": "OPERATIONAL",
           "measurements": {
               "measuredAt": "2022-06-15 12:15:00",
               "period": 5,
               "channels": [
                   {
                       "number": 1,
                       "name": "40EBEC",
                       "type": "ALARM",
                       "value": 0,
                       "status": "OK"
                   }
               ]
           },
           "device": {
               "id": 1128025,
               "serialNumber": "282C0240EBEC",
               "powerStatus": "BATTERY_OK",
               "signal": 37,
               "nextCommunicationAt": "2022-06-15 13:21:03"
           }
       }
   ],
   "totalCount": 1
}
```

**You will need the ID of the measurement point for the next request ("id": 989330)**

{% endstep %}

{% step %}

## Get measurements from the selected time period

To receive the the measurement from the selected time period use the following request:

**Method**: GET

**Endpoint**: <https://cloud.efento.io/api/v2/measurement-points/><mark style="color:red;">ID-OF-THE-MEASUREMENT-POINT</mark>/measurements?from=<mark style="color:red;">DATE-OF-THE-FIRST-MEASUREMENT-IN-UTC</mark>\&to=<mark style="color:red;">DATE-OF-THE-LAST-MEASUREMENT-IN-UTC</mark> *(e.g. <https://cloud.efento.io/api/v2/measurement-points/989330/measurements?from=2022-06-14> 22:00:00\&to=2022-06-15 21:59:59)*

**Headers**: Authorization: <mark style="color:red;">API token</mark> (e.g. “adsFcdc34rf…”)

In the response from Efento API, you will receive JSON that contains the list of all the measurements taken in the selected time period
{% endstep %}
{% endstepper %}

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.efento.io/efento-cloud/integrations/api-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.