Data integration with external system

How to setup client endpoint to LOCUS

1. To create an Integration with third-party application send POST request to /api/http-notification-config

Request example:

curl -X POST \
  'https://{host}/api/http-notification-config' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "{url}",
    "httpHeaders": {
      "additionalProp1": "string1",
      "additionalProp2": "string2",
      "additionalProp3": "string3"
    }
  }'

{token} - Requires a valid Bearer token with administrative or configuration management rights.
{host} - Locus host
{url} - URL with protocol part without port
Possible values:
String
Example:
"https://test.free.beeceptor.com"

Response Body example:

{
  "id": "45677e30-7494-4867-9c33-6886105bc434",
  "url": "https://test.com",
  "httpHeaders": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

2. To edit an existing Integration with third-party application send PUT request to /api/http-notification-config:

Request example:

curl -X PUT \
  'https://{host}/api/http-notification-config' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "45677e30-7494-4867-9c33-6886105bc434",
    "url": "https://test1.com",
    "httpHeaders": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }'

{token} - Requires a valid Bearer token with administrative or configuration management rights.
{host} - Locus host
{url} - URL with protocol part without port
Possible values:
String
Example:
"https://test.free.beeceptor.com"

Response Body example:

{
  "id": "45677e30-7494-4867-9c33-6886105bc434",
  "url": "https://test1.com",
  "httpHeaders": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

3. To view all existing Integrations with third-party application send GET request to /api/http-notification-config:

Request example:

curl -X GET \
  'https://{host}/api/http-notification-config' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}'

{token} - Requires a valid Bearer token with administrative or configuration management rights.
{host} - Locus host
{url} - URL with protocol part without port
Possible values:
String
Example:
"https://test.free.beeceptor.com"

Response Body example:

[
  {
    "id": "45677e30-7494-4867-9c33-6886105bc434",
    "url": "https://test1.com",
    "httpHeaders": {
      "additionalProp1": "string1",
      "additionalProp2": "string2",
      "additionalProp3": "string3"
    }
  },

4. To view an existing Integration with third-party application by ID send GET request to /api/http-notification-config/id/{id}:

Request example:

curl -X 'GET' \
  'https://{url}/api/http-notification-config/id/{id}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}

Response Body example:

{
  "id": "45677e30-7494-4867-9c33-6886105bc434",
  "url": "https://test1.com",
  "httpHeaders": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

5. To delete an existing Integration with third-party application send DELETE request to /api/http-notification-config/id/{id}:

Request example:

curl -X 'DELETE' \
  'https://{url}/api/http-notification-config/id/{id}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer <token>'

{token} - Requires a valid Bearer token with administrative or configuration management rights.
{host} - Locus host
{url} - URL with protocol part without port
Possible values:
String
Example:
"https://test.free.beeceptor.com"

Response Body:

Status: 204 No Content The configuration was successfully deleted.

Received payload example:

The following payload is received from the device.
All fields shown as null will always be present in the payload,
but only one of them will contain data at a time —
depending on the type of event or information sent by the device.

Example of the default (base) payload:

{
  "timestamp": 1760020355000,
  "asset": {
    "id": "ab33be01-a114-49d3-f5432-92933a52bfb6",
    "name": "test",
    "type": "test-asset-type",
    "tags": []
  },
  "device": {
    "eui": "A6B6C5D5E3F3A9B9",
    "name": "test-device",
    "type": "tracker"
  },
  "indoorLocation": null,
  "outdoorLocation": null,
  "wifiLocation": null,
  "deviceData": null
  "batteryData": null,
  "motionState": null,
  "emergencyState": null
}

PLEASE NOTE: Each of the null fields can contain data depending on the device event type. For example, when location data is received — only indoorLocation, outdoorLocation, or wifiLocation will be populated, while all other fields will remain null.

Field-specific payload examples

Indoor data:

  "indoorLocation": {
    "timestamp": 1760017705000,
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "test-device",
      "type": "tracker"
    },
    "indoorLocation": {
      "site": {
        "id": "site-1",
        "name": "Test Site"
      },
      "building": {
        "id": "building-1",
        "name": "North Tower"
      },
      "floor": {
        "id": "floor-1",
        "name": "Level 1",
        "level": "1"
      },
      "coordinates": {
        "x": 42.75,
        "y": 18.20
      }
    },
    "status": "CONFIRMED"
  },

Outdoor data:

  "outdoorLocation": {
    "timestamp": 1760020355000,
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "test-device",
      "type": "tracker"
    },
    "coordinates": {
      "lat": 53.04582079999999,
      "lon": -111.786454975
    },
    "altitude": -520.35,
    "source": "gnss",
    "aggregationStatus": "AGGREGATED_LOCATION"
  },

Outdoor WiFi data:

  "wifiLocation": {
    "timestamp": 1760017705000,
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "test-device",
      "type": "tracker"
    },
    "coordinates": {
      "lat": 50.45005,
      "lon": 30.52345
    },
    "altitude": 175.0
  },

Device payload data:

  "deviceData": {
    "timestamp": 1760017705000,
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "test-device",
      "type": "tracker"
    },
    "deviceData": {
      "temperature": 21.8,
      "humidity": 46
    }
  },

Battery data:

  "batteryData": {
    "timestamp": 1760017705000,
    "remainingBatteryPercentage": 84,
    "remainingBatteryDays": 120
  },

Motion State data:

  "motionState": {
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "test-device",
      "type": "tracker"
    },
    "timestamp": 1760017705000,
    "stateStart": 1760017600000,
    "isMoving": true
  },

Emergency State data:

  "emergencyState": {
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "test-device",
      "type": "tracker"
    },
    "timestamp": 1760017705000,
    "sosButtonAlarm": false,
    "safetyHookAlarm": false,
    "fallDetectionAlarm": false,
    "pressureAlarm": false,
    "earActive": false
  }
}

Retry policy description ( 3 times, exponential)