Location Service API Endpoints

The production API base URL is https://api.tradesmentechnologies.com/.

Base Path

/prod/location

Endpoints

How tracking starts and stops: A technician's mobile app should poll Get Tracking Session (below). When it reports an active session, the app streams GPS via Update Location; when it reports no active session, the app stops. A session is created when an "on my way" text is sent naming the technician (see the notifications API) and ends when an "arrived"/"completed" text is sent for that job or after a 4-hour safety-net TTL. This lets a dispatcher — not just the technician themselves — trigger tracking, because the named technician's own device reacts to the session rather than to who pressed send.

Update Location

Store the calling employee's last-known GPS coordinates. Called by the employee's mobile app. The companyId and employeeId are derived from the auth token, so an employee can only ever write their own location. Each call overwrites the previous one (only the most recent fix is kept).

• Method: POST
• Path: /location
• Authentication: Required — Authorization: Bearer <token>
• Request Body:

  {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "accuracy": 8.5
  }
  

  • latitude (required): number between -90 and 90.
  • longitude (required): number between -180 and 180.
  • accuracy (optional): non-negative number, in meters, if the device reports it. Omit the field when unknown — an explicit null is rejected with 400.
• Success Response: 200 OK

  { "message": "Location updated" }
  

• Error Responses:
  • 400 Bad Request — missing body, missing/non-numeric latitude/longitude, out-of-range coordinates, or negative accuracy.
  • 401 Unauthorized — missing or invalid token.
  • 500 Internal Server Error

Get Location

Retrieve a technician's last-known location for a specific job. Public (no authentication) — intended for the customer-facing technician web page, which polls it every 30 seconds. The location is only returned while there is an active tracking session for the requested job and the company's showEmployeePageInOmw feature flag is on. Because the link sent in an on-my-way text carries that job's ID, once the job ends (its tracking session is deleted) the link can no longer reveal the technician's whereabouts — even if the technician is now sharing location for a different job.

• Method: GET
• Path: /location
• Authentication: None
• Query Parameters:
  • company (required): the company ID.
  • employee (required): the employee ID.
  • job (required): the job ID the customer was notified about. Location is only returned while this job is being actively tracked.
• Success Response: 200 OK

  {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "accuracy": 8.5,
    "updatedAt": "2026-05-23T16:37:48.809Z",
    "destination": {
      "latitude": 37.8044,
      "longitude": -122.2712,
      "formattedAddress": "123 Main St, Oakland, CA 94607"
    }
  }
  

  • accuracy is null when the device did not report it.
  • destination is the geocoded location of the job the technician is heading to, so the page can show a second pin (with the address in a popup) alongside the technician. It is null when the job has no address or the address could not be geocoded.
• Error Responses:
  • 400 Bad Request — missing company, employee, or job query parameter.
  • 403 Forbidden — the company does not have location sharing (showEmployeePageInOmw) enabled.
  • 404 Not Found — comes in two flavors, distinguished by an available field in the body so the page can choose between "waiting" and "not available":
    • { "message": "No active tracking for this job", "available": false } — the requested job is not being tracked (the link is for a finished or expired job). This is terminal; the page should stop polling and show that live location isn't available.
    • { "message": "No recent location available" } (no available field) — the job is being tracked but no location has been reported yet, or the last fix is stale (older than 5 minutes, intentionally withheld so customers never see a misleading old position). This is transient; the page should keep polling.
  • 500 Internal Server Error

Get Tracking Session

Tell the calling employee's mobile app whether it should currently be streaming GPS. The app polls this endpoint; when active is true it should push location via Update Location, and when false it should stop. The companyId and employeeId are derived from the auth token, so an employee can only ever read their own session.

A session is created by an "on my way" text (when the company's showEmployeePageInOmw feature flag is on) and removed by an "arrived"/"completed" text for the same job, or automatically after a 4-hour TTL backstop.

• Method: GET
• Path: /location/session
• Authentication: Required — Authorization: Bearer <token>
• Query Parameters: None
• Success Response: 200 OK
  • When a session is active:

    {
      "active": true,
      "jobId": "job-123",
      "startedAt": "2026-05-25T16:37:48.809Z",
      "expiresAt": 1748191068
    }
    

    • expiresAt is the session's TTL expiry, in epoch seconds.
  • When no session is active:

    { "active": false }
    

• Error Responses:
  • 401 Unauthorized — missing or invalid token.
  • 500 Internal Server Error