Skip to the content

DoRoutes API · version 1

Trackers

POST/v1/trackers/positions

A tracker sends its points

For maker clouds and LoRaWAN network servers. The tracker's token as the bearer; no tenant key. 1 to 500 points. Points less accurate than 100 m are dropped, and a point already received at that time is ignored. A vehicle tracker's points are kept for its van inside the firm's tracker_window (shift, working_hours or always) or while the van's theft watch is on. kept is how many were new.

Request body · object

  • pointsarray of TrackerPoint, required
    • recorded_atstring, required
    • latitudenumber, required
    • longitudenumber, required
    • accuracy_mnumber, required
    • speed_mpsnumber or null
    • headingnumber or null
    • battery_percentinteger or null
Example request
{
  "points": [
    {
      "recorded_at": "string",
      "latitude": 0,
      "longitude": 0,
      "accuracy_m": 0,
      "speed_mps": 0,
      "heading": 0,
      "battery_percent": 0
    }
  ]
}

Response 200 · Kept

Taken in.

  • keptinteger, required

    How many points were new and kept.

Example response 200
{
  "kept": 0
}

Response 400 · Error

The request is not valid.

  • errorobject, required
    • codestring, required

      A short machine-readable name, such as not_found.

    • messagestring, required

      What went wrong, for people.

  • request_idstring, required

    Matches the X-Request-ID response header.

Example response 400
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "request_id": "string"
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

POST/v1/trackers/traccar

The platform's Traccar forwards a position

The platform secret as the bearer; no tenant key. One Traccar position (speed in knots), found by device.uniqueId among active trackers of every firm. An unknown device keeps nothing.

Request body · object

  • deviceobject, required
    • uniqueIdstring, required
  • positionobject, required
    • fixTimestring, required
    • latitudenumber, required
    • longitudenumber, required
    • accuracynumber
    • speednumber or null
    • coursenumber or null
    • attributesobject
Example request
{
  "device": {
    "uniqueId": "string"
  },
  "position": {
    "fixTime": "string",
    "latitude": 0,
    "longitude": 0,
    "accuracy": 0,
    "speed": 0,
    "course": 0,
    "attributes": {}
  }
}

Response 200 · Kept

Taken in.

Fields as in A tracker sends its points

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

GET/v1/admin/trackers

The firm's trackers

Needs the vehicles.manage permission. Active first, by label.

Response 200 · object

The trackers.

  • trackersarray of Tracker, required
    • idinteger (int64), required
    • kindstring, required

      One of: vehicle cargo

    • labelstring, required
    • identifierstring, required
    • vehicle_idinteger (int64) or null, required
    • statusstring, required

      One of: active retired

    • last_seen_atstring

      When it last reported, UTC as YYYY-MM-DD HH:MM:SS.

    • battery_percentinteger or null, required
    • created_atstring, required
Example response 200
{
  "trackers": [
    {
      "id": 0,
      "kind": "vehicle",
      "label": "string",
      "identifier": "string",
      "vehicle_id": 0,
      "status": "active",
      "last_seen_at": "string",
      "battery_percent": 0,
      "created_at": "string"
    }
  ]
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

POST/v1/admin/trackers

Register a tracker

Needs the vehicles.manage permission. A vehicle tracker may name its van, which has one active tracker at most; a cargo tag names none. The identifier (the device's IMEI or maker's ID) is unique among active trackers of every firm (409). The token is shown only here; the tracker sends it to POST /v1/trackers/positions.

Request body · object

  • kindstring, required

    One of: vehicle cargo

  • labelstring, required
  • identifierstring, required
  • vehicle_idinteger (int64) or null
Example request
{
  "kind": "vehicle",
  "label": "string",
  "identifier": "string",
  "vehicle_id": 0
}

Response 200 · object

Registered.

  • trackerTracker, required
    • idinteger (int64), required
    • kindstring, required

      One of: vehicle cargo

    • labelstring, required
    • identifierstring, required
    • vehicle_idinteger (int64) or null, required
    • statusstring, required

      One of: active retired

    • last_seen_atstring

      When it last reported, UTC as YYYY-MM-DD HH:MM:SS.

    • battery_percentinteger or null, required
    • created_atstring, required
  • tokenstring, required

    The tracker's token for HTTPS push, shown only now.

Example response 200
{
  "tracker": {
    "id": 0,
    "kind": "vehicle",
    "label": "string",
    "identifier": "string",
    "vehicle_id": 0,
    "status": "active",
    "last_seen_at": "string",
    "battery_percent": 0,
    "created_at": "string"
  },
  "token": "string"
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 409 · Error

It clashes with what is stored.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

POST/v1/admin/trackers/{id}/retire

Retire a tracker

Needs the vehicles.manage permission. Its token stops working and its identifier can be registered again. Retiring a retired tracker changes nothing.

Parameters

  • idstring, in the path, required

Response 200 · object

Retired.

  • trackerTracker, required
    • idinteger (int64), required
    • kindstring, required

      One of: vehicle cargo

    • labelstring, required
    • identifierstring, required
    • vehicle_idinteger (int64) or null, required
    • statusstring, required

      One of: active retired

    • last_seen_atstring

      When it last reported, UTC as YYYY-MM-DD HH:MM:SS.

    • battery_percentinteger or null, required
    • created_atstring, required
Example response 200
{
  "tracker": {
    "id": 0,
    "kind": "vehicle",
    "label": "string",
    "identifier": "string",
    "vehicle_id": 0,
    "status": "active",
    "last_seen_at": "string",
    "battery_percent": 0,
    "created_at": "string"
  }
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

GET/v1/admin/job/{id}/tags

A job's cargo tags

Needs the jobs.read permission. Released ones included, oldest first.

Parameters

  • idstring, in the path, required

Response 200 · object

The tags.

  • tagsarray of JobTag, required
    • idinteger (int64), required
    • job_idinteger (int64), required
    • tracker_idinteger (int64), required
    • labelstring, required
    • identifierstring, required
    • itemstring, required
    • attached_atstring, required
    • loaded_atstring

      When the job's Loaded step happened; the tag is watched from then. Absent before.

    • released_atstring

      When it was delivered or moved to another job.

    • last_seen_atstring

      When it last reported while watched.

Example response 200
{
  "tags": [
    {
      "id": 0,
      "job_id": 0,
      "tracker_id": 0,
      "label": "string",
      "identifier": "string",
      "item": "string",
      "attached_at": "string",
      "loaded_at": "string",
      "released_at": "string",
      "last_seen_at": "string"
    }
  ]
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

POST/v1/admin/job/{id}/tags

Put a cargo tag on a job

Needs the jobs.write permission. The tag is watched from the job's Loaded step, now or when it is recorded, until Delivered. A vehicle's tracker (400), a job whose load goes to disposal stops (400) and a tag already on a job not delivered (409) are refused; move a tag with PUT /v1/admin/job-tags/{id}.

Parameters

  • idstring, in the path, required

Request body · object

  • identifierstring, required
  • itemstring

    What the tag is on.

Example request
{
  "identifier": "string",
  "item": "string"
}

Response 200 · object

Attached.

  • tagJobTag, required
    • idinteger (int64), required
    • job_idinteger (int64), required
    • tracker_idinteger (int64), required
    • labelstring, required
    • identifierstring, required
    • itemstring, required
    • attached_atstring, required
    • loaded_atstring

      When the job's Loaded step happened; the tag is watched from then. Absent before.

    • released_atstring

      When it was delivered or moved to another job.

    • last_seen_atstring

      When it last reported while watched.

Example response 200
{
  "tag": {
    "id": 0,
    "job_id": 0,
    "tracker_id": 0,
    "label": "string",
    "identifier": "string",
    "item": "string",
    "attached_at": "string",
    "loaded_at": "string",
    "released_at": "string",
    "last_seen_at": "string"
  }
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 409 · Error

It clashes with what is stored.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

PUT/v1/admin/job-tags/{id}

Move a cargo tag to another job

Needs the jobs.write permission. The tag is released from its job and watched by the other from that job's Loaded step. A released tag can't move (409).

Parameters

  • idstring, in the path, required

Request body · object

  • job_idinteger (int64), required
Example request
{
  "job_id": 0
}

Response 200 · object

Moved; the tag on its new job.

  • tagJobTag, required
    • idinteger (int64), required
    • job_idinteger (int64), required
    • tracker_idinteger (int64), required
    • labelstring, required
    • identifierstring, required
    • itemstring, required
    • attached_atstring, required
    • loaded_atstring

      When the job's Loaded step happened; the tag is watched from then. Absent before.

    • released_atstring

      When it was delivered or moved to another job.

    • last_seen_atstring

      When it last reported while watched.

Example response 200
{
  "tag": {
    "id": 0,
    "job_id": 0,
    "tracker_id": 0,
    "label": "string",
    "identifier": "string",
    "item": "string",
    "attached_at": "string",
    "loaded_at": "string",
    "released_at": "string",
    "last_seen_at": "string"
  }
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 409 · Error

It clashes with what is stored.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

GET/v1/admin/job-tags/live

Cargo tags in transit

Needs the tracking.read permission. Each tag loaded and not yet delivered that has reported since, at its latest point, with its job's vehicle, by tag.

Response 200 · object

The tags.

  • tagsarray of TagInTransit, required
    • idinteger (int64), required
    • job_idinteger (int64), required
    • labelstring, required
    • itemstring, required
    • vehicle_idinteger (int64) or null, required

      The job's vehicle; null when it has none.

    • positionVehiclePosition, required

      A point a phone or a vehicle tracker recorded. recorded_at is RFC 3339 when a phone sends it, and UTC as YYYY-MM-DD HH:MM:SS when the API gives it. A vehicle's tracker points come first; its phone's fill the tracker's gaps of more than 2 minutes.

      • sourcestring

        One of: phone tracker

      • recorded_atstring, required
      • latitudenumber, required
      • longitudenumber, required
      • accuracy_mnumber, required

        The phone's estimate of the error, in metres.

      • speed_mpsnumber or null
      • headingnumber or null

        Degrees from north, 0 to under 360.

Example response 200
{
  "tags": [
    {
      "id": 0,
      "job_id": 0,
      "label": "string",
      "item": "string",
      "vehicle_id": 0,
      "position": {
        "source": "phone",
        "recorded_at": "string",
        "latitude": 0,
        "longitude": 0,
        "accuracy_m": 0,
        "speed_mps": 0,
        "heading": 0
      }
    }
  ]
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

GET/v1/admin/job-tags/{id}/trail

A cargo tag's points while watched

Needs the tracking.read permission. Oldest first; kept as long as the business keeps proof.

Parameters

  • idstring, in the path, required

Response 200 · object

The points.

  • positionsarray of VehiclePosition, required
    • sourcestring

      One of: phone tracker

    • recorded_atstring, required
    • latitudenumber, required
    • longitudenumber, required
    • accuracy_mnumber, required

      The phone's estimate of the error, in metres.

    • speed_mpsnumber or null
    • headingnumber or null

      Degrees from north, 0 to under 360.

Example response 200
{
  "positions": [
    {
      "source": "phone",
      "recorded_at": "string",
      "latitude": 0,
      "longitude": 0,
      "accuracy_m": 0,
      "speed_mps": 0,
      "heading": 0
    }
  ]
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

GET/v1/admin/tag-alerts

The open cargo tag alerts

Needs the tracking.alerts permission. Newest first. Alerts are raised every minute; each is published as tag.alert and emailed to staff with tracking.alerts.

Response 200 · object

The alerts.

  • alertsarray of TagAlert, required
    • idinteger (int64), required
    • tag_idinteger (int64), required
    • job_idinteger (int64), required
    • kindstring, required

      away_from_van, further than tag_away_metres from its van for tag_away_minutes; wrong_stop, left at another of its van's drops that day; silent, no point for tag_silent_minutes; delivered_away, last seen further than tag_dropoff_metres from its drop when delivered.

      One of: away_from_van wrong_stop silent delivered_away

    • labelstring, required
    • itemstring, required
    • raised_atstring, required
    • handled_atstring
Example response 200
{
  "alerts": [
    {
      "id": 0,
      "tag_id": 0,
      "job_id": 0,
      "kind": "away_from_van",
      "label": "string",
      "item": "string",
      "raised_at": "string",
      "handled_at": "string"
    }
  ]
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points

POST/v1/admin/tag-alerts/{id}/handled

Mark a tag alert handled

Needs the tracking.alerts permission. Marking a handled alert again changes nothing.

Parameters

  • idstring, in the path, required

Response 200 · object

Handled.

  • handledboolean, required
Example response 200
{
  "handled": true
}

Response 400 · Error

The request is not valid.

Fields as in A tracker sends its points

Response 401 · Error

No tenant key, or no valid session.

Fields as in A tracker sends its points

Response 403 · Error

The session may not do this.

Fields as in A tracker sends its points

Response 404 · Error

Not found, or not yours.

Fields as in A tracker sends its points

Response 500 · Error

Something failed on our side.

Fields as in A tracker sends its points