FAQ

Why does my request return all objects even though I added a filter?

📘

Invalid filter syntax is ignored

If a query parameter's syntax is invalid, Surfact ignores it rather than erroring — which can return every object. Double-check the __ separator and attribute name. See Field Filters.

How do I discover an endpoint's fields?

📘

Use an OPTIONS request

You can send an OPTIONS request to any endpoint to get a detailed JSON description of its attributes — including which are required and which are read_only.

curl -X OPTIONS 'https://api.surfact.com/api/v2.0/devices/' \
  -H 'X-Auth-Token: your_token_here'

{
  "name": "Device List",
  "actions": {
    "POST": {
      "label":       { "type": "string", "required": false, "read_only": false, "label": "Label" },
      "name":        { "type": "string", "required": false, "read_only": false, "label": "Name", "max_length": 200 },
      "description": { "type": "string", "required": false, "read_only": false, "label": "Description" }
    }
  }
}

read_only: true on a field means the API accepts it in a write without complaint and then ignores it, so OPTIONS is the fastest way to find out whether a field you are sending will actually take effect.

My timestamps look wrong — what format does Surfact use?

📘

Two formats — check which field you are reading

Data-point and activity timestamps are POSIX time in milliseconds: timestamp and created_at inside a value, lastActivity on devices and variables, and lastTriggered on events — for example 1788442281742.

Resource metadata timestamps are ISO-8601 strings: createdAt on devices, variables, organizations, events and event logs — for example 2026-08-12T13:39:08.353792Z.

A single response can contain both: a reefer's device object carries an ISO-8601 createdAt right next to a millisecond lastActivity. See Data Structure Overview.

How long is my token valid?

📘

Six hours

Tokens expire after 6 hours — generate a fresh one as needed. See Authentication.

How do I show a device on a map?

📘

Read lat and lng from the position variable

Surfact reads lat and lng from a dot's context, so a single dot is enough to plot the position. On an Emma tracker those coordinates arrive on the position variable, whose value is the accuracy of the fix in metres. See Device Position.

I'm still not getting a 200 OK

Drop us a line at [email protected] and we'll help you out.