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 TEK Seal",
    "type": "TEK-Seal-asset-type",
    "tags": []
  },
  "device": {
    "eui": "A6B6C5D5E3F3A9B9",
    "name": "Test TEK Seal",
    "type": "TEK_SEAL"
  },
  "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 TEK Seal",
      "type": "TEK_SEAL"
    },
    "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": "AGGREGATED_LOCATION"
  },

Outdoor data:

  "outdoorLocation": {
    "timestamp": 1760020355000,
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "Test TEK Seal",
      "type": "TEK_SEAL"
    },
    "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 TEK Seal",
      "type": "TEK_SEAL"
    },
    "coordinates": {
      "lat": 50.45005,
      "lon": 30.52345
    },
    "altitude": 175.0
  },

Device payload data:

  "deviceData": {
    "timestamp": 1760017705000,
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "Test TEK Seal",
      "type": "TEK_SEAL"
    },
    "deviceData": {
      "temperature": 21.8,
      "humidity": 46
    }
  },

Battery data:

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

Motion State data:

  "motionState": {
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "Test TEK Seal",
      "type": "TEK_SEAL"
    },
    "timestamp": 1760017705000,
    "stateStart": 1760017600000,
    "isMoving": true
  },

Emergency State data:

  "emergencyState": {
    "device": {
      "eui": "A6B6C5D5E3F3A9B9",
      "name": "Test TEK Seal",
      "type": "TEK_SEAL"
    },
    "timestamp": 1760017705000,
    "sosButtonAlarm": false,
    "safetyHookAlarm": false,
    "fallDetectionAlarm": false,
    "pressureAlarm": false,
    "earActive": false
  }
}

Retry Policy

When Locus attempts to deliver a message (for example, a device payload/location data/etc) to an external HTTP endpoint, it expects to receive a successful response (HTTP 2xx).
If the target system does not respond successfully (e.g., due to timeout, connection error, or non-2xx HTTP response), Locus automatically retries the delivery according to a predefined retry policy.

Retry Logic

If the initial message delivery fails, the system performs up to three retry attempts with the following delays:

Attempt	Delay before retry	Description
1st retry	2 minutes	The first retry occurs 2 minutes after the initial failed attempt.
2nd retry	4 minutes	If the first retry also fails, another attempt is made after 4 minutes.
3rd retry	8 minutes	If the second retry fails, the system performs a final retry after 8 minutes.

After all retry attempts are exhausted, the message is considered undelivered.
No further retries are performed.

Example Scenario

If a message fails to be delivered at 10:00, retries will occur as follows:

10:02 — 1st retry
10:06 — 2nd retry
10:14 — 3rd retry

If all three attempts fail, the message is not retried again.

Important Notes

Retry intervals are fixed and cannot be configured by the user.
Each retry includes the same payload as the original attempt.
Once a message is successfully delivered (HTTP 2xx), no further retries occur.
If the external endpoint consistently fails, newer messages are still processed independently — the retry mechanism applies per message.