Skip to content

Upload payload & ingest endpoint

Once sync is on, Beekon POSTs batches of stored history to your url. This page describes the format your server receives and how to build the endpoint that accepts it.

On this topic: Turn on sync · Upload payload & ingest endpoint (this page) · Auth & token refresh

Each upload is one JSON object at schema_version: 1. New fields arrive only as additions, so your endpoint must ignore fields it doesn’t know. Locations travel in identity segments: each segment carries the user_id that was set when its rows were recorded, so an account switch while offline never attributes one user’s locations to another.

{
"schema_version": 1,
"batch_id": "0190d4e2-7b1a-7c3e-9f10-2a4b6c8d0e1f",
"session_id": "0190d4e0-1234-7000-8000-aabbccddeeff",
"sent_at": "2026-06-15T12:34:56.789Z",
"device": {
"install_id": "0190c1a4-aaaa-7bbb-8ccc-ddddeeeeffff",
"platform": "ios",
"sdk_version": "0.6.0",
"model": "iPhone15,3"
},
"extras": {"trip": "morning-commute"},
"segments": [
{
"user_id": "app-user-123",
"locations": [
{
"id": "0190d4e2-7b1a-7c3e-9f10-2a4b6c8d0e20",
"timestamp": "2026-06-15T12:34:10.000Z",
"trigger": "interval",
"motion": "moving",
"is_mock": false,
"latitude": 37.7749,
"longitude": -122.4194,
"accuracy": 5.2,
"speed": 2.5,
"bearing": 180,
"altitude": 14.3,
"activity": "walking",
"battery_percent": 87,
"is_charging": false,
"power_save_mode": false
}
],
"geofence_events": [
{
"id": "0190d4e2-7b1a-7c3e-9f10-2a4b6c8d0e21",
"type": "exit",
"geofence_id": "home",
"timestamp": "2026-06-15T12:34:05.000Z"
}
]
}
]
}
FieldTypeAlways presentMeaning
schema_versionintegeryes1 for this format. Branch on it.
batch_idstring (UUIDv7)yesNew for each POST attempt. For tracing only: never dedupe on it. A retried batch may be rebuilt with a new batch_id. Dedupe on each location’s and event’s id.
session_idstringyesOne tracking run, from start() to stop(), stable across a relaunch. Group a trip’s locations by it.
sent_atstringyesWhen the device built the batch (new for each attempt).
deviceobjectyesConstant per install.
extrasobjectnoYour opaque string → string map from setExtras(...). Omitted when empty. Never carries identity.
reported_stateobjectnoCloud-mode device health and config report. A custom backend can ignore it.
segmentsarrayyesIdentity segments in time order. Each is {user_id?, locations[], geofence_events[]}. A segment without user_id is anonymous: attribute it to device.install_id. Consecutive segments never share an identity.

device carries install_id (UUIDv7, stable per app install), platform ("android" / "ios"), sdk_version, and model (omitted when blank).

The SDK mints batch_id, install_id and each location id as UUIDv7. Treat them as opaque strings: Beekon’s own API accepts any text as an install_id and any UUID version as a location id.

FieldTypeAlwaysMeaning
idstring (UUIDv7)yesLocation id. The dedup key.
timestampstringyesWhen the location was recorded.
triggerstringyesinterval · motion · check_in · geofence · manual
motionstringyesmoving · stationary · unknown
is_mockbooleanyesOS flagged the location as mock.
latitude, longitudenumberyesDegrees.
accuracynumbernoHorizontal accuracy, metres. Omitted when absent.
speednumbernoMetres/second. Omitted when absent.
bearingnumbernoCourse, degrees. Omitted when absent.
altitudenumbernoMetres. Omitted when absent.
activitystringnostationary · walking · running · cycling · automotive · unknown. Omitted when activity detection is off.
qualitystringnolow_accuracy · implausible_speed. Omitted when the location has no quality flag.
battery_percentintegernoBattery level when the location was recorded. Omitted when unknown.
is_chargingbooleannoCharging at record time. Omitted when unknown.
power_save_modebooleannoOS power saver active at record time. Omitted when unknown.
FieldTypeMeaning
idstring (UUIDv7)Event id. Dedupe on it.
geofence_idstringThe geofence that fired (your id).
typestringenter or exit.
timestampstringWhen the crossing occurred, on the device clock.

A geofence event carries no position. When the device records a location at the crossing, that location travels separately in locations[] with trigger: geofence. Don’t reject a batch because of an event’s type or geofence_id: store or skip an event you don’t recognise and still return 2xx. A 400 would make the device delete the whole batch, its locations included.

  • Transport: POST, Content-Type: application/json, Content-Encoding: gzip. The body is always gzipped.
  • Timestamps: ISO-8601 UTC with exactly three fractional digits and a literal Z: YYYY-MM-DDTHH:MM:SS.mmmZ.
  • Enums: always lowercase snake_case (check_in, low_accuracy).
  • Numbers: a whole number has no decimal point (180, not 180.0).
  • Optional fields are omitted, never null. A missing accuracy, speed, bearing or altitude means the OS didn’t report it. Treat it as unknown, never as 0.
  • Bad locations are removed on the device. A location with a non-finite latitude or longitude is dropped before sending; the rest of the batch still arrives.

Your endpoint receives the upload at the exact url in SyncConfig (Beekon follows no redirect), over HTTPS for any non-loopback URL, and answers with a status code that tells the SDK what to do with the batch. Every Beekon backend does four things:

  1. Gunzip and parse the body (Content-Encoding: gzip, JSON inside).
  2. Dedupe on each location’s and event’s id (INSERT … ON CONFLICT DO NOTHING) so retries do no harm. Never dedupe on batch_id: it is for tracing and may change on a retry.
  3. Store each segment’s locations and geofence events with its user_id.
  4. Answer with the right status code. 2xx means the data is durably stored and the device can delete its copy. An empty 2xx body is a complete answer. Return 400 or 422 only for a payload that will never be accepted, and 5xx to ask for a retry.
import express from 'express';
import zlib from 'node:zlib';
const app = express();
// Beekon sends gzipped JSON. Take the raw bytes; don't let a JSON body-parser
// touch them.
app.use('/ingest', express.raw({ type: '*/*', limit: '12mb' }));
// Stand-in for your database. In production use a table with a UNIQUE index
// on each location id, and INSERT ... ON CONFLICT DO NOTHING. The location id
// is the dedup key (batch_id is for tracing and may change on a retry).
const received = new Map(); // id -> row
app.post('/ingest', (req, res) => {
// 1. Gunzip + parse.
let envelope;
try {
const raw = req.headers['content-encoding'] === 'gzip'
? zlib.gunzipSync(req.body)
: req.body;
envelope = JSON.parse(raw.toString('utf8'));
} catch {
// unparseable: the SDK deletes the batch and doesn't retry
return res.sendStatus(400);
}
// 2. (Optional) authenticate. Return 401 to make the SDK refresh its token
// and retry.
// if (!authorized(req)) return res.sendStatus(401);
// 3. Idempotent ingest: dedupe on each row's id, so a replay changes nothing.
for (const segment of envelope.segments ?? []) {
for (const loc of segment.locations ?? []) {
if (received.has(loc.id)) continue;
received.set(loc.id, {
...loc,
sessionId: envelope.session_id,
installId: envelope.device.install_id,
userId: segment.user_id ?? null, // record-time identity
});
}
// ...store segment.geofence_events the same way (dedupe on their id too)...
}
// 4. Acknowledge, only after the data is durably written.
return res.sendStatus(200);
});
app.listen(8080, () => console.log('ingest listening on :8080'));

The SDK reads your HTTP status and acts on the batch. It deletes the batch from the device only on 2xx, or on 400 and 422, which say the payload will never be accepted:

You returnSDK treats it asWhat the SDK does
2xxacceptedDeletes the batch.
400, 422rejectedDeletes the batch and doesn’t retry. Use only for a payload that will never be accepted.
401, 403authKeeps the batch, refreshes the token (if configured), retries once.
408, 429transientKeeps the batch, backs off, retries. Retry-After is honoured on 429.
5xx, timeout, network errortransientKeeps the batch, retries with backoff. Retry-After is honoured on 503.
413too largeKeeps the batch, halves it and retries, down to a single location or event. One that still gets 413 is deleted so it can’t block the queue.
404, 3xx, any other 4xxpermanentKeeps the batch. Fix the endpoint.

A 2xx that never reaches the device (a dropped connection, or a timeout after you committed) looks like a failed upload to the SDK. It sends the same locations and events again, possibly regrouped under a new batch_id. Dedupe on each id and a replay, even of a partial write, is safe.

Your 2xx may carry a JSON body. Every field is optional and unknown fields are ignored. Beekon Cloud uses this body to send data back to the device (a config_revision signal, a geofence_halo slice, pending device commands). A custom backend can implement any of it, and most implement none: a bare 200 with no body is a complete answer. A malformed body never undoes the upload: the batch stays deleted on the device.

Next: protect the endpoint with a rotating token on Auth & token refresh, and check uploads end to end with syncStatus.