Field app API

The field app API is what a technician's phone talks to: the tech's day, moving a job from "on the way" to "done", turn-by-turn directions to the next stop, check-ins, location, photos, parts, notes, calling the customer, and linking a personal calendar. Use it to build your own field app or to connect a device you already use.

Everything here lives under /v1/tech/, plus the directions endpoints under /v1/field/ and one OAuth callback that Google and Microsoft call, not you.

• Base URL: https://go.crewlink.ai (api.crewlink.ai is not set up yet). For testing, ask CrewLink for an API key for a test company.
• Examples use $CREWLINK for the base URL and $KEY for a tech token.
• An interactive reference for every endpoint is served at GET /docs.

#Endpoint index

#Who can call these

Every /v1/tech/ and /v1/field/ endpoint needs a tech token:

Authorization: Bearer <id>.<secret>

A tech token is one of:

• A tech user token. An owner creates a user with role: "tech" linked to a person on the schedule (POST /v1/office/users with personId, see office.md). The token is shown once.
• A tech sign-in session. The tech signs in with their email and a one-time code (see sign-in.md). Sessions last 30 days.

The token acts as the person on the schedule it is linked to. Every call is about that person: their day, their jobs, their truck, their calendar.

Office tokens (owner, dispatcher) and company API keys get 403 forbidden here, and a tech token gets 403 on office and CrewConnect endpoints. One person, one token: if two people share a phone, give each their own sign-in.

#A tech only sees their own schedule

A job is visible to a tech only while it is booked and the tech is on it (they have a visit on that job). Every job endpoint answers 404 not_found with the message "That job isn't on your schedule." for anything else: another tech's job, a cancelled job, another company's job. Jobs sent to the company through CrewConnect appear like any other job once they are on the tech's schedule.

What a tech sees about the customer is deliberately small: the first name, the address and the job notes. The customer's phone number is never returned; use the masked call instead. Teammates on the same job appear by first name.

#Times in this API

Most times here are company wall-clock time, written YYYY-MM-DDTHH:mm with no offset (for example 2026-10-12T12:00 means noon in the company's time zone). The company's IANA time zone is in GET /v1/tech/me. Fields that are instants (at in job history) are ISO 8601 in UTC.

#Offline taps and retries

A phone loses signal in basements and crawl spaces. The CrewLink app queues taps while offline and sends them when it reconnects, sometimes more than once. Two things make that safe on every POST below that changes something (stage, check-in, location, notes, parts):

at in the body: when it really happened. An ISO 8601 time with an offset, e.g. "2026-10-12T15:18:00Z". CrewLink uses it instead of the time the request arrived: for arrived and done (so time on site, and what CrewLink learns from it, is right), for the job history, for the parts log and for the position's time. It may be up to 24 hours in the past. A time a few minutes ahead of the server counts as now (phone clocks drift); anything further ahead, or older than 24 hours, is 422 invalid_at. Leave it out for a tap sent live. What the tap changes on the schedule (a check-in's extension, texts) still happens now.

Idempotency-Key header: act once. Any unique string per tap (a UUID is fine), up to 200 characters of letters, digits, _, -, . and :. The first request with a key runs and CrewLink keeps its response for 24 hours. Sending the same key again, with the same method, path and body, returns that stored response (with the header Idempotent-Replayed: true) instead of acting twice: one note, one set of parts off the truck, one stage change. Keys are per user.

A response of 500 or more isn't kept, so retrying the same key runs the request again.

curl -s -X POST $CREWLINK/v1/tech/jobs/1042/stage \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{"stage":"on_site","at":"2026-10-12T15:18:00Z"}'

#Errors

Errors always look like this:

{ "error": "not_found", "message": "That job isn't on your schedule." }

#The tech's day

#GET /v1/tech/me

Who this token belongs to, their company, their time zone (their branch's: a Denver tech of a Chicago company works on Denver time) and the current time in it. Call it once at app start.

curl -s $CREWLINK/v1/tech/me -H "Authorization: Bearer $KEY"

{
  "name": "Maria Gomez",
  "personId": 12,
  "timezone": "America/Chicago",
  "company": { "name": "Northline Heating & Air", "timezone": "America/Chicago", "slug": "northline" },
  "now": "2026-10-12T10:30"
}

company.slug is for address search (GET /v1/public/geocode?slug=&q=), e.g. when the tech enters a new home address.

Errors: 401, 403.

#GET /v1/tech/day

The tech's stops for one day, in start order. Only booked jobs are listed; a job stays on the list after it is done (with stage: "done").

curl -s "$CREWLINK/v1/tech/day?date=2026-10-12" -H "Authorization: Bearer $KEY"

{
  "date": "2026-10-12",
  "timezone": "America/Chicago",
  "stops": [
    {
      "jobId": 1042,
      "start": "2026-10-12T12:00",
      "end": "2026-10-12T13:15",
      "stage": "scheduled",
      "service": "Seasonal tune-up",
      "customer": "Jamie",
      "address": "2150 W Roscoe St, Chicago, IL",
      "lat": 41.955,
      "lng": -87.675,
      "notes": "Side gate code 4411",
      "crew": ["Maria"],
      "textsCustomer": true
    }
  ]
}

Errors: 401, 403, 422 (bad date).

#GET /v1/tech/jobs/{id}

One job on the tech's schedule, with its history (stage changes, check-ins and notes, oldest first).

{
  "jobId": 1042,
  "stage": "on_site",
  "service": "Seasonal tune-up",
  "address": "2150 W Roscoe St, Chicago, IL",
  "notes": "Side gate code 4411",
  "events": [
    { "kind": "en_route", "at": "2026-10-12T16:40:00.000Z", "text": null },
    { "kind": "arrived", "at": "2026-10-12T17:00:00.000Z", "text": null },
    { "kind": "checkin", "at": "2026-10-12T17:35:00.000Z", "text": "on_track" },
    { "kind": "note", "at": "2026-10-12T17:41:00.000Z", "text": "Filter was 2 sizes too small; replaced." }
  ]
}

Event kind is one of en_route, arrived, done, checkin (with the answer in text), note, attention or attention_cleared (the office flagged the job, reason in text). Events from every crew member on the job are included, and notes the office added (no tech on them).

Errors: 401, 403, 404.

#GET /v1/tech/jobs/{id}/attachments

Files on a job on the tech's schedule: the proposal, photos and documents the office or an integration added. Booked jobs only.

{
  "attachments": [
    { "id": "c0f7a1d2-5b3e-4f6a-8c9d-0e1f2a3b4c5d", "jobId": 1042, "kind": "proposal", "name": "Proposal - Quinn.pdf", "contentType": "application/pdf", "bytes": 482113, "status": "uploaded", "uploadedBy": { "kind": "platform", "id": "6d0c1f9a-3b2e-4c55-8f71-0a9b8c7d6e5f" }, "createdAt": "2026-11-02T18:05:00.000Z", "uploadedAt": "2026-11-02T18:05:00.000Z", "url": "https://..." }
  ]
}

url is a signed download link good for 15 minutes; ask again for a fresh one. Errors: 401, 403, 404 (not a booked job on your schedule).

#Job stages

A booked job moves through four stages. A tech moves it forward only; skipping ahead is allowed (for example straight from scheduled to on_site), going back or repeating a stage is not.

stateDiagram-v2
  direction LR
  scheduled --> en_route: on the way
  en_route --> on_site: arrived
  on_site --> done: done
  scheduled --> on_site
  scheduled --> done
  en_route --> done

Every tap also goes into the office's Plan vs actual: on the way, arrived and done are compared with the day's plan (the drive, the arrival against the planned start, the time on site), and a check-in records whether the job ran long. Nothing changes for the tech, and a tap never waits for it.

The customer text is sent only when the job has a customer with a US or Canadian mobile number, and only while homeowner messages are on for the job (notify), the company (homeownerMessaging) and the platform that booked it. The stop's textsCustomer says which, and the stage tap answers texted, so the app never tells the tech a text went out when it didn't. For a job that came in through CrewConnect, texts carry the brand chosen on that connection (see crewconnect.md).

What the customer receives:

Webhooks go to the company doing the job (the company the tech works for). Payloads are described in webhooks.md; the data for all three stage events is:

{ "jobId": 1042, "personId": 12, "at": "2026-10-12T18:12:00.000Z", "etaMinutes": 12, "minutesOnSite": null }

at is when the tech tapped (for a tap queued offline, when it happened). etaMinutes is set only on job.en_route with a position; minutesOnSite only on job.completed when the job was marked on_site first.

#POST /v1/tech/jobs/{id}/stage

Move a job to its next stage.

Send an Idempotency-Key header so a retried tap moves the job once (a repeat returns the first answer instead of 409 already).

curl -s -X POST $CREWLINK/v1/tech/jobs/1042/stage \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"stage":"en_route","lat":41.9,"lng":-87.65}'

{ "jobId": 1042, "stage": "en_route", "etaMinutes": 9, "minutesOnSite": null, "texted": true }

Marking it done:

{ "jobId": 1042, "stage": "done", "etaMinutes": null, "minutesOnSite": 52, "texted": true }

Errors:

#POST /v1/tech/jobs/{id}/checkin

The mid-job check-in. The CrewLink app asks it about halfway through each job: is the tech on track, or how much longer will they need? Only for a job the tech is on site at.

• on_track just records the answer.
• office_review asks the office to look at the job, with an optional note (the gate is locked, the customer wants a quote first). Nothing on the schedule changes; the job shows as needs attention on the office's lists until they clear it. newEnd is null and changes is [].
• plus15, plus30 or plus60 extend the tech's visit now, while there's still time to fix the rest of the day. Every later job on the tech's day that no longer fits is handled right away: handed to a teammate who can make the same time, otherwise moved to the nearest open time within the next week. Jobs that still fit are left alone. Customers whose job changes are texted. The response lists what happened to each later job.

curl -s -X POST $CREWLINK/v1/tech/jobs/1042/checkin \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"plus30"}'

{
  "jobId": 1042,
  "newEnd": "2026-10-12T10:45",
  "changes": [
    { "jobId": 1043, "action": "handed_off", "local": "2026-10-12T10:30", "techs": ["Luis"], "customerTexted": true }
  ]
}

With on_track, newEnd is null and changes is [].

newEnd and local are company wall-clock times; techs are the first names of the people now on that job. customerTexted says whether that job's customer is texted about the change: false for kept and for needs_call with a time, and whenever homeowner messages are off for that job. Any extension also sends the job.running_late webhook to the company (see webhooks.md).

Errors:

#POST /v1/tech/location

Report where the tech is. The CrewLink app sends this about once a minute while the tech is on the clock, per the company's GPS policy. The latest position is kept as the live position (deleted after 30 days). A fix taken on the clock (30 minutes either side of the day's working hours and visits) is also added to the tech's location trail, thinned to one per 25 m or 60 s, which the company keeps for locationRetentionDays (default 90) for mileage and pay disputes (platforms.md); off the clock nothing goes into the trail. The On the way / Arrived / Done taps' lat/lng count as fixes too. It drives the office's live board (who will be late for their next start) and the fleet map (see office.md).

curl -s -X POST $CREWLINK/v1/tech/location \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"lat":41.951,"lng":-87.66}'

Returns 204 No Content. Errors: 401, 403, 422 (invalid_request, invalid_at).

#Notes, photos and parts

#POST /v1/tech/jobs/{id}/notes

Add a note to a job. Notes appear in the job's history (GET /v1/tech/jobs/{id}) for everyone on the job, and in the job's message thread as a note from the tech, where the office reads it (Messaging).

curl -s -X POST $CREWLINK/v1/tech/jobs/1042/notes \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Filter was 2 sizes too small; replaced."}'

{ "id": 5531 }

Returns 201. Errors: 401, 403, 404, 422. Send an Idempotency-Key so a retried note is added once.

#Photos

Photo bytes never pass through the CrewLink API. A photo is added in three steps:

sequenceDiagram
  participant App as Field app
  participant API as CrewLink API
  participant S as Photo storage
  App->>API: POST /v1/tech/jobs/{id}/photos {contentType, caption}
  API-->>App: 201 {photoId, uploadUrl}
  App->>S: PUT uploadUrl (image bytes, same Content-Type)
  S-->>App: 200
  App->>API: POST /v1/tech/jobs/{id}/photos/{photoId}/uploaded
  API-->>App: 200 {photoId, status: "uploaded"}

1. Ask for an upload URL.

   bashCopy

   curl -s -X POST $CREWLINK/v1/tech/jobs/1042/photos \
     -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"contentType":"image/jpeg","caption":"Filter before"}'

   jsonCopy

   {
     "photoId": "6f1c2b8e-4d3a-4c1e-9a77-2f0d6b5e9c11",
     "uploadUrl": "https://<storage-host>/<path>.jpg?<signature parameters>"
   }

   Treat uploadUrl as opaque: don't change or re-encode it.

2. Upload the bytes with an HTTP PUT straight to uploadUrl, within 15 minutes, with the same Content-Type you declared. Use the URL exactly as given and add no Authorization header.

   bashCopy

   curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @filter-before.jpg

   Storage answers 200 on success. If the URL has expired, start again at step 1.

3. Confirm the upload.

   bashCopy

   curl -s -X POST $CREWLINK/v1/tech/jobs/1042/photos/6f1c2b8e-4d3a-4c1e-9a77-2f0d6b5e9c11/uploaded \
     -H "Authorization: Bearer $KEY"

   jsonCopy

   { "photoId": "6f1c2b8e-4d3a-4c1e-9a77-2f0d6b5e9c11", "status": "uploaded" }

Only confirmed photos are shown to the office (GET /v1/office/jobs/{id}/photos, see office.md). When you confirm, CrewLink checks storage: nothing there yet is 409 not_uploaded (finish the PUT, then confirm again), and a photo over 25 MB or of another type than the contentType you declared is 422 upload_mismatch (the file and the photo are removed; start again). Confirm after storage returned a 2xx. A photo that is never confirmed is never shown. Photos are visible only to the company doing the job: a company that sent the job through CrewConnect does not see them.

#POST /v1/tech/jobs/{id}/photos

Returns 201 {photoId, uploadUrl}. The URL is valid for 15 minutes and only takes the Content-Type you declared (storage refuses another). Photos are up to 25 MB. Errors: 401, 403, 404 (job not on your schedule), 422.

#POST /v1/tech/jobs/{id}/photos/{photoId}/uploaded

No body. Returns 200 {photoId, status: "uploaded"}. Confirming twice is harmless. Errors: 401, 403, 404 (job not on your schedule, or no such photo on that job), 409 not_uploaded (nothing in storage yet), 422 upload_mismatch (over 25 MB or another type; the photo is removed), 422 (photoId isn't a UUID), 502 storage_unavailable (storage didn't answer; retry).

#GET /v1/tech/stock

The parts on the tech's truck, as the office last counted or moved them.

{ "stock": [ { "partId": 31, "sku": "FLT-1620", "name": "16x20 filter", "qty": 4 } ] }

Errors: 401, 403.

#POST /v1/tech/jobs/{id}/parts

Log parts used on a job. They come off the tech's truck count and are added to the job's invoice and profit-and-loss (see office.md).

Send an Idempotency-Key header so a retry takes the parts off the truck once.

curl -s -X POST $CREWLINK/v1/tech/jobs/1042/parts \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"partId":31,"qty":2}'

{ "id": 877, "leftOnTruck": 2 }

Returns 201. Errors:

#Calling the customer

#POST /v1/tech/jobs/{id}/call

Get a number to call or text this job's customer through. The customer sees a CrewLink number, not the tech's, and the tech never sees the customer's real number. The customer can call or text back through the same number for a day.

No body.

curl -s -X POST $CREWLINK/v1/tech/jobs/1042/call -H "Authorization: Bearer $KEY"

{ "dial": "+13125550147" }

Dial or text dial from the tech's own mobile (the one on file with the office): the call is connected only from that phone. Each call to this endpoint sets up a fresh connection, so ask for the number each time rather than storing it.

Errors:

#Linking a calendar

A tech can link their own Google or Outlook calendar so personal appointments never get booked over:

• Busy time comes in. Busy times in the linked calendar for the next 21 days block bookings for that tech, on the booking page, in the office and through CrewConnect.
• Jobs go out. Every CrewLink job on the tech's schedule for the next 21 days is written into the calendar, titled with the service and the customer's first name (for example Seasonal tune-up · Jamie), with the address and the job number. These entries are marked free, so they never count as busy time themselves. They follow moves and are removed when a job is cancelled.
• Sync runs every 5 minutes, and right after linking. The tech can also ask for a sync now.

The flow:

sequenceDiagram
  participant App as Field app
  participant API as CrewLink API
  participant P as Google / Microsoft
  App->>API: POST /v1/tech/calendar/connect {provider}
  API-->>App: {url}
  App->>P: open url in a browser; tech signs in and consents
  P->>API: GET /v1/calendar/callback/{provider}?code=...&state=...
  API-->>App: redirect to the CrewLink web app, ?calendar=connected or failed
  App->>API: GET /v1/tech/calendar (status)

#POST /v1/tech/calendar/connect

Start linking a calendar. Returns the provider's sign-in URL; open it in a browser on the tech's device. The URL works once and expires after 15 minutes.

curl -s -X POST $CREWLINK/v1/tech/calendar/connect \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"provider":"google"}'

{ "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=https%3A%2F%2Fgo.crewlink.ai%2Fv1%2Fcalendar%2Fcallback%2Fgoogle&...&state=..." }

After consent, the provider sends the browser back to CrewLink, which links the calendar, runs a first sync and then redirects to the CrewLink web app with ?calendar=connected (or ?calendar=failed if consent was refused, the link expired or was already used, or the provider rejected it). Linking the same provider again replaces the earlier link.

Errors: 401, 403, 422, 503 not_configured (that provider isn't available on this deployment).

#GET /v1/tech/calendar

The tech's linked calendars.

{
  "calendars": [
    { "provider": "google", "account": "maria@example.com", "status": "ok", "lastSyncAt": "2026-10-12T15:35:00.000Z", "lastError": null }
  ]
}

Errors: 401, 403.

#POST /v1/tech/calendar/sync

Sync every linked calendar for this tech now, then return the same body as GET /v1/tech/calendar. Useful right after the tech adds an appointment. No body. Errors: 401, 403.

#DELETE /v1/tech/calendar/{provider}

Unlink a calendar. Syncing stops.

{ "removed": true }

removed is false if nothing was linked. Busy times brought in from that calendar stop blocking bookings right away (past ones stay on the record). Job entries already written into the calendar are not deleted from it.

Errors: 401, 403, 422.

#GET /v1/calendar/callback/{provider}

The OAuth redirect target. Google or Microsoft sends the tech's browser here after consent; you never call it yourself. It takes code, state and optionally error as query parameters and always answers 302 Found, redirecting to the CrewLink web app: /tech?calendar=connected, or /tech?calendar=failed for a bad or reused state, a provider error or refused consent. No token is needed: the one-time state from POST /v1/tech/calendar/connect identifies the tech.

The office can see who has linked a calendar and whether it is syncing with GET /v1/office/calendars (office.md).

#Wins

A tech's own wins, all from their own taps and reviews (how each number is worked out: office.md, Wins). Jobs worked by a crew count for everyone on it. Nothing here shows another tech's numbers except the leaderboard's top 3, by first name and last initial, when the company has turned the leaderboard on.

#GET /v1/tech/me/wins

curl -s $CREWLINK/v1/tech/me/wins -H "Authorization: Bearer $KEY"

{
  "rookie": null,
  "streak": { "current": 12, "best": 25, "startedOn": "2026-10-06", "atRisk": true, "paused": false },
  "streaks": [
    { "type": "on_time", "name": "On-time arrivals", "unit": "arrivals", "description": "…", "current": 12, "best": 25, "startedOn": "2026-10-06", "atRisk": true, "paused": false, "nextMilestone": 25 },
    { "type": "on_the_way", "name": "On-the-way taps", "unit": "days", "description": "…", "current": 4, "best": 9, "startedOn": "2026-10-09", "atRisk": false, "paused": false, "nextMilestone": 5 },
    { "type": "five_star", "name": "Five-star reviews", "unit": "reviews", "description": "…", "current": 3, "best": 11, "startedOn": "2026-10-01", "atRisk": false, "paused": false, "nextMilestone": 5 },
    { "type": "no_checkin", "name": "Inside the planned time", "unit": "jobs", "description": "…", "current": 18, "best": 40, "startedOn": "2026-10-02", "atRisk": false, "paused": false, "nextMilestone": 25 }
  ],
  "week": { "from": "2026-10-12", "to": "2026-10-18", "arrivals": 6, "onTime": 6, "onTimeRate": 100, "done": 6, "fiveStar": 1, "drivesMeasured": 5, "driveMinutesSaved": 7.5, "bestDayJobs": 4 },
  "personalBest": { "jobs": 6, "date": "2026-09-30" },
  "totals": { "arrivals": 310, "onTimeRate": 94.2, "early": 120, "done": 305, "fiveStar": 41, "reviews": 48, "firstTimeFixRate": 96.1, "ranLong": 22, "headsUp": 17, "checkinHonestyRate": 77.3 },
  "badges": [
    { "key": "clockwork", "name": "Clockwork", "description": "On-time arrivals in a row …", "tier": "silver", "value": 25, "next": { "tier": "gold", "threshold": 50 }, "earnedAt": "2026-10-02T15:12:00.000Z" },
    { "key": "closer", "name": "Closer", "description": "Jobs finished", "tier": "silver", "value": 305, "next": { "tier": "gold", "threshold": 500 }, "earnedAt": "2026-08-14T21:40:00.000Z" }
  ],
  "celebrations": [
    { "id": 77, "kind": "badge", "title": "You hit a 25-visit on-time streak", "badge": { "key": "clockwork", "name": "Clockwork", "tier": "gold" }, "streak": null, "at": "2026-10-02T15:12:00.000Z" }
  ],
  "leaderboard": { "enabled": true, "hidden": false, "boards": [
    { "key": "on_time", "name": "On-time arrivals", "unit": "pct", "top": [{ "rank": 1, "personId": 12, "name": "Maria G.", "value": 100, "detail": "6 of 6 arrivals", "rookie": false }], "you": { "rank": 1, "personId": 12, "name": "Maria G.", "value": 100, "detail": "6 of 6 arrivals", "rookie": false, "qualified": true, "hidden": false } }
  ] }
}

Errors: 401, 403.

#PATCH /v1/tech/me/wins/settings

curl -s -X PATCH $CREWLINK/v1/tech/me/wins/settings -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{ "hideFromLeaderboard": true }'

Response 200: { "hideFromLeaderboard": true }. Hidden, the tech isn't ranked or shown to anyone else; they still see their own row. Errors: 401, 403, 422.

#POST /v1/tech/me/wins/celebrated

Mark celebrations as shown so they aren't returned again. Body: { "ids": [77] } (1 to 50 ids from celebrations). Ids that aren't this tech's are ignored. Response 204. Errors: 401, 403, 422.

#Messages

Techs message the office and their job's crew with the Messaging API, using the same tech token:

• The office line (GET /v1/messaging/office-line, POST /v1/messaging/office-line/messages): one conversation between the tech and everyone in the office.
• Job threads (GET /v1/messaging/jobs/{jobId}, POST /v1/messaging/jobs/{jobId}/messages): one per job, with the office and everyone on the job. On the way, arrived, done, check-ins and notes show in it as they happen.
• Everyone, the company channel, which techs read (and post in, if the owner allows it), and direct messages with the office (with other techs only if the owner allows it).

The two POSTs above take the job id or nothing, not a conversation id, so a message written offline can wait in the same queue as the taps: give it an Idempotency-Key when it's written and resend it unchanged (Offline taps and retries). Unread counts for a badge: GET /v1/messaging/unread.

#My pay

#GET /v1/tech/pay

What the tech has earned this pay week so far (technician pay): jobs completed and their pay, the miles driven over each day's route and the mileage pay, bonuses and deductions, and the total; what closed weeks still owe them; and their last payment. Pay accrues when they tap done.

{
  "visible": true,
  "pay": {
    "period": { "start": "2026-10-12", "end": "2026-10-18", "status": "open" },
    "jobs": 6, "jobPayCents": 54000, "distance": 141.2, "unit": "mi", "mileageCents": 3530, "adjustmentsCents": 0, "totalCents": 57530, "currency": "USD",
    "owedCents": 0,
    "lastPaid": { "periodStart": "2026-10-05", "totalCents": 81200, "paidAt": "2026-10-13T16:00:00.000Z" }
  }
}

{ "visible": false, "pay": null } when the owner doesn't show pay in the app (techsSeePay). Errors: 401, 403.

#My hours and home

A tech can change their own working hours (several windows a day) and home address, when the owner allows it (techsEditHours, on by default). A change takes effect tomorrow in the company's time zone, so today's jobs stay as booked; the office sees it waiting on the team.

#GET /v1/tech/profile

{
  "name": "Maria Gomez",
  "designation": "w2",
  "verified": true,
  "home": { "lat": 41.93, "lng": -87.7 },
  "address": { "line1": "2150 W Roscoe St", "city": "Chicago", "region": "IL", "postalCode": "60618" },
  "availability": [[[480, 720], [780, 1020]], [[480, 1020]], [[480, 1020]], [[480, 1020]], [[480, 1020]], [], []],
  "pendingChange": null,
  "canEdit": true,
  "managedBy": null,
  "managedByName": null
}

availability: Monday first, each day's windows as [start, end] minutes after midnight; [] off. pendingChange: { from, availability, address } when a change is waiting. canEdit is false when the owner doesn't let techs change these, or when an integration owns them: then managedBy is its slug and managedByName its name (e.g. "Acme"), and the app says "Your hours, time off and home are managed in Acme. Change them there." instead of the edit button.

#PATCH /v1/tech/profile

Body: availability (seven lists of windows, at most 6 a day, not overlapping) and/or address with homeLat and homeLng (pick it from address search). Sending again before tomorrow replaces the waiting change.

Response 200: the profile, with pendingChange.from = tomorrow. Errors: 403 not_allowed (the owner manages hours in the office), 409 managed_by_integration (an integration owns your hours and home: managedBy, managedByName; office.md), 422 invalid_request (overlapping windows, an address without its position, or nothing sent).

#Directions

In-app turn-by-turn navigation: the next stop, and a driving route to it. A typical flow when the tech taps On my way:

1. POST /v1/tech/jobs/{id}/stage with en_route (texts the customer, as always).
2. GET /v1/field/jobs/{id}/route?from=<lat>,<lng> with the phone's position, and show the steps.
3. Watch the position. A step is done when the phone is within about 30 m of its maneuver (or past it along the line). More than about 60 m off the line for 10 seconds: ask for the route again from where the phone is. Within about 75 m of to: offer Arrived, which is POST /v1/tech/jobs/{id}/stage with on_site.

Nothing about the route is stored, and from is not saved as a location report (send those to POST /v1/tech/location).

#GET /v1/field/next-stop

The tech's next stop today: the first stop in plan order that isn't done (one they're on the way to, or on site at, counts). Use it for an "On my way to my next stop" button.

curl -s $CREWLINK/v1/field/next-stop -H "Authorization: Bearer $KEY"

{ "jobId": 1042 }

jobId is null when nothing is left today. Errors: 401, 403.

#GET /v1/field/jobs/{id}/route

A driving route from from to the job, with turn-by-turn steps.

curl -s "$CREWLINK/v1/field/jobs/1042/route?from=41.8902,-87.6511" -H "Authorization: Bearer $KEY"

{
  "jobId": 1042,
  "to": { "lat": 41.955, "lng": -87.675, "address": "2501 N Lincoln Ave, Chicago" },
  "from": { "lat": 41.8902, "lng": -87.6511 },
  "provider": "mapbox",
  "distanceMeters": 8123,
  "durationSeconds": 1260,
  "eta": "2026-10-12T15:51:00.000Z",
  "arriveBy": "2026-10-12T17:00:00.000Z",
  "geometry": { "type": "LineString", "coordinates": [[-87.6511, 41.8902], [-87.6511, 41.9], [-87.675, 41.955]] },
  "steps": [
    { "instruction": "Drive north on N Halsted St.", "name": "N Halsted St", "distanceMeters": 1100, "durationSeconds": 120,
      "maneuver": { "type": "depart", "modifier": null, "location": [-87.6511, 41.8902], "bearingAfter": 0 },
      "voice": "Drive north on North Halsted Street, then turn left." },
    { "instruction": "Turn left onto W Fullerton Ave.", "name": "W Fullerton Ave", "distanceMeters": 800, "durationSeconds": 100,
      "maneuver": { "type": "turn", "modifier": "left", "location": [-87.6511, 41.9], "bearingAfter": 270 },
      "voice": "Turn left onto West Fullerton Avenue.",
      "lanes": [
        { "indications": ["left"], "valid": true, "active": true, "validIndication": "left" },
        { "indications": ["straight"], "valid": false, "active": false },
        { "indications": ["right"], "valid": false, "active": false }
      ] },
    { "instruction": "You have arrived.", "name": "N Lincoln Ave", "distanceMeters": 0, "durationSeconds": 0,
      "maneuver": { "type": "arrive", "modifier": null, "location": [-87.675, 41.955], "bearingAfter": 0 },
      "voice": null }
  ],
  "maxspeed": [{ "speed": 30, "unit": "mph" }, null],
  "mapStyle": {
    "url": "https://api.mapbox.com/styles/v1/mapbox/navigation-day-v1",
    "token": "pk.<mapbox token>",
    "style": "crewlink-nav",
    "version": 1,
    "themes": ["light", "blue", "dark"]
  }
}

Routes are kept for a few minutes: asking again from about the same place gives the same answer.

Errors:

#The first-run tour

The tech app shows a short intro the first time a tech signs in, and the web tech view a guided tour. Where they are in it is kept per person with GET /v1/me/tour and PATCH /v1/me/tour (any role, the caller's own state only), so it shows once and resumes on another device. The app uses the tour id tech-app; the web tech view uses tech. Request and response: office.md.

curl -X PATCH $CREWLINK/v1/me/tour -H "authorization: Bearer $TECH_TOKEN" \
  -H 'content-type: application/json' -d '{"tour": "tech-app", "status": "completed"}'

#Related

• messaging.md: the office line, job threads, the company channel and who can message whom.
• office.md: creating tech users, the live board, job photos, parts and stock, linked calendars.
• webhooks.md: job.en_route, job.arrived, job.completed and job.running_late payloads, and how to verify signatures.
• crewconnect.md: jobs that come in from other companies.
• sign-in.md: email sign-in for techs.