Skip to main content

Quick start

This takes about five minutes with curl. Each step uses the response from the one before.

1. Create an API key​

In the admin, open Settings → API keys, name the key after the system that will use it, and choose Create key. Copy the key (it starts rtf_); it's only shown once.

export TRACKER=https://<your Tracker host>/api
export TRACKER_KEY=rtf_...

2. Create a visit​

curl -s "$TRACKER/v1/journeys" \
  -H "Authorization: Bearer $TRACKER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "JOB-1001",
    "customer": { "name": "Sam Tenant", "email": "sam@example.com" },
    "destination": { "lat": 53.8110, "lng": -1.5530, "label": "14 Woodhouse Lane, Leeds" },
    "operative": { "displayName": "Alex" },
    "appointment": { "start": "2026-11-02T09:00:00Z", "end": "2026-11-02T12:00:00Z" }
  }'

The response has the visit and its live state:

{
  "journey": {
    "id": "jrn_…",
    "status": "scheduled",
    "trackingUrl": "https://<your Tracker host>/t/…",
    "fieldUrl": "https://<your Tracker host>/t/share/…",
    "...": "…"
  },
  "live": { "status": "scheduled", "appointment": { "start": "…", "end": "…" }, "...": "…" }
}

Open trackingUrl in a browser: that's the customer's page. Sam also got the booked email with that link. To stop that while testing, send "notify": false.

Destinations

Instead of coordinates, send "destination": { "uprn": "10023456789" }. Tracker looks the UPRN up in OS Open UPRN, which is the most reliable way to land on the right building.

3. Set off​

curl -s "$TRACKER/v1/journeys/jrn_…/start" \
  -H "Authorization: Bearer $TRACKER_KEY" -H "Content-Type: application/json" \
  -d '{ "position": { "lat": 53.7958, "lng": -1.5476, "accuracyM": 8 } }'

The response is the customer's view, now en_route, with a route and an eta. The tracking page shows the map straight away.

4. Send positions​

curl -s "$TRACKER/v1/journeys/jrn_…/positions" \
  -H "Authorization: Bearer $TRACKER_KEY" -H "Content-Type: application/json" \
  -d '{ "positions": [
        { "lat": 53.8001, "lng": -1.5489, "recordedAt": "2026-11-02T09:41:05Z" },
        { "lat": 53.8030, "lng": -1.5502, "recordedAt": "2026-11-02T09:41:15Z" } ] }'

Watch the dot move on the tracking page. Send a position at the destination, or call /arrive, to finish:

curl -s -X POST "$TRACKER/v1/journeys/jrn_…/arrive" -H "Authorization: Bearer $TRACKER_KEY"

Next​

  • Visits: bulk creation, filtering, cancelling.
  • Sending positions: batching, timing and the live feed.
  • Webhooks: send customer messages through your own SMS or email provider.