Office API

The office API is everything a company's back office does: the day board, the live board, the team, branches and services, time off, booking and moving jobs, same-day emergencies, users, roles, invitation links and tokens, client companies, out-of-area and client requests and trips, recurring work, inventory, job profit, the fleet, reports, KPIs and exports, billing and invoices, and webhook endpoints.

Each call is scoped to the company behind the token. You only ever see and change your own company's people, jobs and money.

Related pages:

• booking-page.md: the public booking page, the customer's manage link, out-of-area requests from customers, invoice and review links.
• field-app.md: what techs call from their phones (/v1/tech/...).
• crewconnect.md: sending work to partner companies and contractors (/v1/connect/...).
• messaging.md: messages between your people (/v1/messaging/...): the company channel, a thread per job, each tech's office line, direct messages, partner channels, and the owner's rules for who can message whom.
• webhooks.md: events, payloads, signatures and retries.
• sign-in.md: email sign-in for people (session tokens).

#Contents

• Before you start
  • Authentication and roles
  • Times, money and ids
  • Errors
  • Rate limits
• Endpoint index
• Schedule
• Live board
• Dispatch board
• Team
• Branches and services
• Time off and blocks
• Office jobs
• Jobs for integrations (list, detail, complete, notes, attention, catalog, open times, holds, files)
• Sites (one per property per client company, every visit ever made there)
• Intake and job search
• Emergencies
• Calendar view and calendar connections
• Credentials
• Users and tokens
• Roles and scopes
• Invitation links
• Client companies
  • Test clients and test people
• Out-of-area requests and trips
• Recurring work and memberships
• Inventory
• Job P&L
• Fleet
• Drive times (travel model)
• Reports and market data
• Where jobs stand and the heat map
• KPIs, exports and the weekly report
• Plan vs actual
• Technician pay
• Wins
• Billing, invoices, payouts and reviews
• Webhook endpoints
• Platforms
• Company, settings and the API key

#Before you start

Base URL: https://go.crewlink.ai (live today; api.crewlink.ai is not set up yet). For testing, ask CrewLink for an API key for a test company. The examples use $CREWLINK for the base URL and $KEY for a token:

export CREWLINK=https://go.crewlink.ai
export KEY='3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90.<secret>'
curl -s "$CREWLINK/v1/office/me" -H "Authorization: Bearer $KEY"

The API also serves an interactive reference at GET /docs, built from GET /v1/openapi.json.

#Authentication and roles

Send Authorization: Bearer <id>.<secret> on every call. These tokens work:

Every endpoint on this page accepts owner, field manager and dispatcher tokens (a field manager can do whatever a dispatcher can). A tech token gets 403 forbidden here (techs use field-app.md). Field managers and dispatchers whose scope is team or own see only their own requests and jobs, and get 403 scoped on the whole-company endpoints: see Roles and scopes. A few calls are owner only:

A missing, malformed, wrong or deactivated token gets 401 unauthorized. A deactivated user's sessions stop working too.

Idempotency-Key. Every write on this page (POST, PUT, PATCH, DELETE) takes an optional Idempotency-Key header: a retry with the same key and body within 24 hours gets the first answer back (Idempotent-Replayed: true) instead of acting twice; the same key with a different body is 422 idempotency_key_reused; while the first is still running, 409 in_progress. Keys are per user (or per company API key, or per platform and company). 5xx answers aren't kept.

#Times, money and ids

• Time zones per branch. The company has a default IANA zone, and each branch can have its own (a Denver branch of a Chicago company). A job's times are on the clock of its address (a branch whose area holds it gives its zone), and a person's hours and day on their own clock (their branch's; without a branch, their home's; or one set on them); responses that carry wall-clock times say which zone with timezone. A company in one zone sees no difference. See the person's time zone.
• Request times are ISO 8601 datetimes with an offset: 2026-11-16T16:00:00Z or 2026-11-16T10:00:00-06:00. Office bookings and moves also take local instead: the wall clock where the job is (2026-11-16T10:00), so you don't need to know the branch's zone. Dates are YYYY-MM-DD, read in the zone they're about (a tech's day in their branch's zone; a company report in the company's).
• Response times come in two forms. start (and eta, expiresAt, at, ...) is the real instant in UTC, e.g. 2026-11-16T16:00:00.000Z. local is the wall clock where the job is, YYYY-MM-DDTHH:mm, e.g. 2026-11-16T10:00, with its zone in timezone. A few board views (the schedule, trip stops) give only wall-clock times; each section says so.
• Distances are metric in the API (km, areaKm, perKmCents, costPerKmCents). Show them in the company's units (mi or km, from GET /v1/office/me).
• Minutes after midnight. Working hours and the on-call window are minutes after local midnight: 480 is 8:00, 1020 is 17:00, 1440 is the end of the day. Each day's hours are [start, end] with 0 <= start < end <= 1440 (anything else is 422).
• Money is an integer in minor units (...Cents: 12900 is $129.00) plus an ISO currency code where it can vary.
• Ids. Jobs, people, services, blocks, credentials, parts and invoices have integer ids. Users, webhook endpoints, recurrences, trips, vehicles and payouts have UUIDs. A booking id, a job id and an out-of-area request id are the same number for the same job.

#Errors

Every error has the same body:

{ "error": "slot_taken", "message": "No qualified tech can make that time." }

The per-endpoint lists below leave out 401, 403 and 429, which any call can return. The OpenAPI spec (/v1/openapi.json) lists them on every route, with 400, 404 (a platform key's company that hasn't granted it), 422 and 500 where they apply.

#Why a time can't be booked

When the office books, moves or accepts a job at a time that can't be booked, the 409 body says why in message (written for the person at the desk) and in reason (for your code), and personId names the tech it's about when it's about one:

{
  "error": "slot_taken",
  "message": "That time is held for same-day emergencies (on-call reserve, 12:00–5:00 PM). Pick another time or tech.",
  "reason": "on_call_reserve",
  "personId": 1
}

The first four are checked before the routing, so they're exact. Without picked techs, a reason is given only when it rules out everyone who could go (for example, everyone qualified is on call then). Out-of-area accepts answer cannot_reach instead of slot_taken when the tech can't get there in time; see accept.

#Rate limits

Each client IP can make up to 600 requests a minute across the API (a platform key: 1,200 a minute per key instead, wherever it calls from). Over the limit you get 429 rate_limited with a Retry-After header (seconds) and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Back off until Retry-After has passed.

#Endpoint index

O+D = owner, field manager and dispatcher (people with a team or own scope only where Roles and scopes says). O = owner only.

#Schedule

#GET /v1/office/schedule

Everyone's day: each active person's visits (booked jobs, plus booking-page holds in progress) and calendar blocks on that date. Times here are wall clock only (YYYY-MM-DDTHH:mm), since the board is drawn in local time. Each tech's day and times are on their branch's clock (timezone on each tech): with branches in two zones, date=2026-11-16 is the 16th in Chicago for the Chicago techs and the 16th in Denver for the Denver techs, so a Denver job at 23:00 is on the Denver tech's 16th even though it is already the 17th in Chicago.

Query:

curl -s "$CREWLINK/v1/office/schedule?date=2026-11-16" -H "Authorization: Bearer $KEY"

Response 200:

{
  "date": "2026-11-16",
  "techs": [
    {
      "id": 1,
      "name": "Maria Gomez",
      "timezone": "America/Chicago",
      "visits": [
        {
          "jobId": 1042,
          "start": "2026-11-16T10:00",
          "end": "2026-11-16T11:15",
          "status": "booked",
          "jobStatus": "scheduled",
          "overdue": false,
          "needsAttention": false,
          "attentionReason": null,
          "service": "Seasonal tune-up",
          "customer": "Pat Quinn",
          "address": "2210 W Addison St, Chicago",
          "sentBy": null,
          "client": { "id": "9b1e6f2a-4c3d-4e8f-a7b6-2d1c0e9f8a75", "name": "Globex Solar" },
          "filedBy": "Filed by Dana One · Globex Solar",
          "hidden": false,
          "state": "scheduled"
        }
      ],
      "blocks": [
        { "id": 17, "start": "2026-11-16T13:00", "end": "2026-11-16T17:00", "reason": "Dentist", "source": "office" }
      ]
    },
    { "id": 2, "name": "James Okafor", "visits": [], "blocks": [] }
  ]
}

A multi-day job shows as one visit on each of its days.

Errors: 422 if date is missing or not YYYY-MM-DD.

#Live board

#GET /v1/office/live

Every tech working today with a traffic-light status, what they're doing, their last known position, and their next job with an ETA. Positions come from the field app. The board includes every active person who has a job today or working hours today.

No parameters.

curl -s "$CREWLINK/v1/office/live" -H "Authorization: Bearer $KEY"

Response 200:

{
  "at": "2026-10-12T15:30:00.000Z",
  "counts": { "ok": 5, "tight": 1, "late": 1, "idle": 1 },
  "techs": [
    {
      "id": 1,
      "name": "Maria Gomez",
      "status": "late",
      "doing": "before_leaving",
      "location": { "lat": 43.04, "lng": -87.91, "at": "2026-10-12T15:29:10.000Z" },
      "next": {
        "jobId": 1188,
        "customer": "Jamie Cruz",
        "start": "2026-10-12T14:00",
        "eta": "2026-10-12T19:28:00.000Z",
        "minutesLate": 28
      }
    },
    {
      "id": 4,
      "name": "Diego Ramirez",
      "status": "idle",
      "doing": "done",
      "location": null,
      "next": null
    }
  ]
}

Status (the dot on the board):

Doing:

Fields:

#Dispatch board

#GET /v1/office/dispatch

The whole Dispatch page for one local day in one read: a lane per person working that day with their stops in order and the planned drive before each, time off, live status, position and ETA (on the tech's today), the intake queue, risks, counts and map pins. Made for apps that draw the board themselves (your platform's admin app reads it with a platform key); the full field list and an example are in platforms.md. Read-only.

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

• Lanes: every active person with working hours that weekday or a visit that day (booked or held), sorted by name. tech.hours are that day's working windows in minutes after local midnight. utilization is booked minutes over working-window minutes.
• Stops: the visits in start order, each with the job's ids (externalRefs), client, service, customer, address in parts, times (start/end instants, local/localEnd wall clock), state, jobStatus, stage, overdue, the attention flag and homeownerTexts. driveMinutesBefore is the planned drive from the previous stop (or home, or a base): from the day's plan snapshot the techs are working to (driveSource: "plan") while that tech's stops still match it, else the engine's prediction for the day as booked now ("predicted"); null for holds. eta and minutesLate are live, while the tech is on the way to that stop. risk (level on_time / at_risk / late, eta, signed minutesLate, reason, basis) covers every stop not reached yet today and every arrived stop; enRouteAt, arrivedAt, completedAt are the field taps; plannedOrder / actualOrder compare the booked order with the order of arrival; actualDriveMinutes is the drive as it happened (platforms.md).
• Live (only when date is the tech's today; null otherwise): status ok, tight, late, idle or on_job (on site and on track) and doing, by the live board's rules, plus fieldStatus (off, idle, en_route, on_site), currentJobId and nextJobId; location is the last position the field app sent (at, and accuracy, heading, speed when the phone sent them), only while the tech is on the clock (now and when it was taken), for every caller.
• Queue: the intake queue (every job with no time yet), oldest first, at most 100; counts.unscheduled counts all of it.
• Risks: late and tight (live), overdue stops on the day, and aging queue jobs (waiting 3 or more days), each with a one-line message.
• Pins: one per job on the board (lat, lng, state, stage, techIds), for a map.

Who sees what. Platform keys (read is enough) see techs as "First L." (as they are when the grant says full names), customers without a phone, and a tech's location by the grant: full-names grants while the tech is on the clock (now and the position's time both within 30 minutes before their first window or visit that day and 30 minutes after their last); other grants only while the tech is working a job and the fix is at most 15 minutes old (platforms.md). The same rule applies to location on GET /v1/office/live. People with a team or own scope see other people's jobs as busy blocks (source: "job", no customer, address or client), no live status or positions, and only their own queue jobs.

Polling. Every answer has a weak ETag (and Cache-Control: private, no-cache). Send it back as If-None-Match and an unchanged board answers 304 with no body. Poll every 30 to 60 seconds; each call, 304 or not, counts against the rate limit.

Errors: 404 not_found (unknown branch), 422 (a date that isn't YYYY-MM-DD or doesn't exist, such as 2026-02-30).

#GET /v1/office/dispatch/live

The live part of the board, light enough to poll every 30 to 60 seconds for a map: techs[] (personId, displayName, status off / idle / en_route / on_site, laneStatus, currentJobId, nextJobId, position { lat, lng, accuracy, heading, speed, recordedAt }) and jobs[] (every visible stop: jobId, personId, externalRefs, clientCompanyId, stage, start, end, local, eta, minutesLate, risk, reason, basis, enRouteAt, arrivedAt, completedAt, plannedOrder, actualOrder). Same branch and client filters, scoping, privacy and ETag as GET /v1/office/dispatch; date defaults to today in the company's zone. Pushed instead: webhooks dispatch.position and job.risk_changed. Full field list: platforms.md.

curl -s "$CREWLINK/v1/office/dispatch/live" -H "Authorization: Bearer $KEY"

#GET /v1/office/dispatch/routes

Where each working tech is and the route they are on, for a live map (the office's Map view on Dispatch). Poll every 15 to 30 seconds with If-None-Match.

curl -s "$CREWLINK/v1/office/dispatch/routes" -H "Authorization: Bearer $KEY" -H 'If-None-Match: W/"Zq1f..."'

Per tech (techs[]): personId, displayName, status (off, idle, en_route, on_site), laneStatus (the board's risk dot: ok, tight, late, on_job, idle), currentJobId, nextJobId, position { lat, lng, accuracy, heading, speed, recordedAt }, heading, positionState, navigating, route, routeSource, progressMeters, legs[] and stops[].

• route: the driving line the tech is on now, a GeoJSON LineString ([lng, lat]). When the tech is navigating in the field app (navigating: true: they opened in-app directions to their next job, tapped On my way, and the route is less than 90 minutes old) it is the route their phone is following, then the planned legs after that job (routeSource: "navigation"). Otherwise it is the planned route ("planned") from their position (or the stop they're at or last left, or where their day starts) through their remaining stops in booked order. null when nothing is left. progressMeters: how far along route the tech is (draw what is behind as driven).
• legs[]: one per remaining stop: from (position, origin = where the day starts, or job), fromJobId, toJobId, distanceMeters and durationSeconds (from a position: what is left), eta (UTC, whole minutes; chained: the later of arriving and the start, plus the booked length, plus the drive), signed minutesLate, provider (mapbox with live traffic, osrm, or straight) and endIndex (where in route.coordinates the leg ends).
• stops[]: the tech's booked stops that day in order (order), with start, end, local, stage, state, reached (done, on site or arrived), eta, risk { level, minutesLate }, customer (name only), service, client, address { full, lat, lng }, externalRefs.
• positionState says why there is or isn't a position: live (a fix in the last 15 minutes), stale (older), none (location off: no fix since they came on the clock), off_clock, hidden (this caller may not see it now); null on another day.
• mapStyle: CrewLink's map style and public map token (as on the field app's route), or null (draw without tiles). Always null for platform keys.

Privacy. A position only while the tech is on the clock (now and when the fix was taken: from 30 minutes before their first working window or visit to 30 minutes after their last), for every caller including the office; never off the clock. Platform keys need read; names and positions by the grant (who sees a position), no customer phone, and no leg from where the day starts (a home) for a short-names grant. People with a team or own scope see only techs with a stop of theirs that day, only those stops, a position only while the tech's current or next job is theirs, and the route only up to the first stop they can't see.

Routing cost. Routes come from the same provider as the field app's directions (Mapbox driving-traffic, else OSRM) and are cached: a leg between two fixed points for 30 minutes, the leg from a moving tech for 3 minutes while they stay within 300 m of it (their progress is measured along it, not re-routed). One read makes at most 6 provider calls and all reads together at most 60 a minute; a leg over that budget, or with no routing configured, is a straight line with the planned drive time (provider: "straight") until a later read fills it in. A steady poll costs no provider calls.

Errors: 404 not_found (unknown branch), 422 (a bad date or techIds).

#Team

People on the schedule. Add someone with POST /v1/office/team; to take someone off the schedule, set active: false. To let a person sign in to the field app, add a tech user for them with POST /v1/office/users.

Working hours (hours) are seven entries, Monday first. Each is [start, end] in minutes after local midnight, or null for a day off. [480, 1020] is 8:00 to 17:00. start and end are whole minutes from 0 to 1440, start before end; anything else is 422.

Several windows a day (availability): seven lists, Monday first, each a list of [start, end] windows (at most 6 a day, not overlapping; [] for a day off). [[480, 720], [780, 1020]] is 8 to 12 and 1 to 5. A visit has to fit inside one window; the gaps are never offered. Send availability instead of hours to set it; hours then reads each day's envelope (first start to last end), so code that only knows hours keeps working. Sending hours again goes back to one window a day.

The tech's own changes. When the owner allows it (techsEditHours in the pay settings, on by default), a tech can change their own hours and home address in the field app (field-app.md). Their change takes effect the next day, so the day already booked stays put; until then it shows as pendingChange. Changing the same thing here replaces it.

Designation (designation) is the tax designation: w2 (a W-2 employee) or 1099 (a 1099 contractor). It is the same as kind (employee / contractor); scheduling treats both the same. The pay report filters by it.

Max travel distance (maxTravelMiles): optional. The person is never offered a job farther than this from home (straight line; from their branch when their day starts there, see startsFrom), on top of their branch's area. Without a branch it is also their service radius.

Tax id (taxId): an SSN or EIN, stored encrypted (AES-256-GCM) and only ever shown masked (•••••6789).

Skills (skills) is a bit set: each bit is one skill your company defines (for example bit 0 = maintenance, bit 1 = repair, bit 2 = installs). A person can do a service when they have every skill bit the service needs. 7 (binary 111) has all three of those; 3 (011) can't do installs.

Service areas belong to branches: each person serves the area of their branch (branchId). Someone without a branch serves a radius around their home (around their base on a base day): their maxTravelMiles, else the company's defaultTechRadiusMiles (settings), else 40 km; serviceRadiusMiles on the person says which. A national company whose techs work from home sets defaultTechRadiusMiles (for example 150). Addresses outside every area get no online times (outsideArea); see Out-of-area requests and trips. Every automatic path keeps the same rule: recurring visits outside every area are queued for the office instead of booked (recurring), and CrewConnect work outside the partner's areas is refused (out_of_area, crewconnect.md). Only the office books past an area on purpose: accepting an out-of-area request, or naming techIds.

Where the day starts (startsFrom on the person). The first job of a day is offered only when the shift start, plus the drive from here at that time of day, plus the buffer, fits before it: the same check as every other leg, with nothing skipped. In order: their home (home, address); someone added with only a branchId starts from the branch's location (kind: "branch"; they move with the branch when an owner moves it); a home that isn't a real place (0,0) falls back to the branch; with neither, kind is none and they are never offered, auto-booked or picked by CrewLink, and naming them (techIds) is refused with "has no start location". A trip or base day starts at its base instead. The company itself has no location and is never a start. More in engine.md.

Time zone. A person's hours and day are on their own clock (timezone): the zone set on them (ownTimezone, timezone on POST or PATCH), else their branch's (the company's when the branch has none of its own), else, without a branch, the zone of their home (from its coordinates; an offline map), else the company's. [480, 1020] for a Denver tech is 8:00 to 17:00 Denver time, and for a Baltimore tech of a Chicago company without a branch it is 8:00 to 17:00 Eastern. Zones that keep the same clock are one (a Louisville home reads America/New_York). A job is planned on the clock of its address (a branch whose area holds it gives its own zone, else the address's own; if only people on another clock cover it, the nearest one's) and only people on that clock are assigned to it. When someone's zone changes (their timezone, a home in another zone, another branch), their booked jobs and time off from now on are re-expressed on the new clock keeping every instant.

#The person object

{
  "id": 1,
  "name": "Maria Gomez",
  "kind": "employee",
  "branch": "North",
  "branchId": "6a1f3c2e-9b0d-4e57-8c21-3f5a7d9e1b42",
  "designation": "w2",
  "home": { "lat": 41.93, "lng": -87.7 },
  "address": { "line1": "2150 W Roscoe St", "city": "Chicago", "region": "IL", "postalCode": "60618", "country": "US" },
  "skills": 7,
  "hours": [[480, 1020], [480, 1020], [480, 1020], [480, 1020], [480, 1020], null, null],
  "availability": [[[480, 720], [780, 1020]], [[480, 1020]], [[480, 1020]], [[480, 1020]], [[480, 1020]], [], []],
  "pendingChange": null,
  "maxTravelMiles": 30,
  "verified": true,
  "taxId": "•••••6789",
  "phone": "+13125550123",
  "email": "maria@northline.example",
  "hourlyCostCents": 3800,
  "active": true,
  "timezone": "America/Chicago",
  "ownTimezone": null,
  "hoursSource": null,
  "serviceRadiusMiles": null,
  "externalRefs": { "acme": "tech_42" },
  "availabilityManagedBy": null,
  "availabilityManagedByName": null,
  "ownAvailabilityManagedBy": null
}

#GET /v1/office/team

Everyone on the team, active or not. When an integration owns the team's hours (availabilityManagedBy), see Availability managed by an integration.

Response 200: { "people": [ <person>, ... ] }. A platform key sees names as first name and last initial (unless its grant says full names).

#GET /v1/office/team/{id}

One person: the same object as an item of GET /v1/office/team, with the same rules (your company's people only; a platform key sees "First L." unless its grant says full). Changes the tech made in the field app that are due are applied first, as on the list.

Path: id (integer) person id. Response 200: <person>. Errors: 404 not_found (no one with that id on your team, including anyone at another company). People with a team or own scope may call it, like the list.

curl -s "$CREWLINK/v1/office/team/57" -H "Authorization: Bearer $KEY"

#Availability managed by an integration

A company can let an integration (a platform) own its technicians' availability: weekly hours, time off, home, zone, travel radius and bases. availabilityManagedBy is null (managed here, the default) or the platform's slug. acme-crew is managed by acme. While it is set, only that platform's key changes those fields; everyone else (owners, field managers, dispatchers, the company API key, other platforms, and techs in the field app) gets:

{ "error": "managed_by_integration", "message": "Hours for this team are managed in Acme. Change them in Acme.", "managedBy": "acme", "managedByName": "Acme" }

on PUT /v1/office/team/{id}/availability, PATCH /v1/office/team/{id} with hours, availability, homeLat/homeLng, address, timezone or maxTravelMiles (other fields still work), POST and DELETE /v1/office/blocks, POST and DELETE /v1/office/team/{id}/bases and the field app's PATCH /v1/tech/profile. Busy time from linked Google or Outlook calendars is still synced and can still be removed. Adding people and booking are unchanged.

• Emergency override: an owner (signed in, or the company API key; never a platform) adds "force": true to the body (?force=true on the DELETEs). It is applied, recorded in the audit below, and its webhooks carry "forced": true. force from anyone else is 403 forbidden.
• Per person: PATCH /v1/office/team/{id} { "availabilityManagedBy": "crewlink" } (owner) manages one person here although the company's is an integration; a platform slug puts one person under that platform; null follows the company. Team reads carry availabilityManagedBy (the result), availabilityManagedByName and ownAvailabilityManagedBy (the person's own setting).
• The web app shows those fields read-only, with "Hours, time off and home are managed in Acme. Change them there."

#GET /v1/office/availability-management

{ "availabilityManagedBy": "acme", "availabilityManagedByName": "Acme", "people": [{ "personId": 61, "availabilityManagedBy": "crewlink" }],
  "overrides": [{ "at": "2026-10-12T16:02:00.000Z", "action": "availability_force", "actor": "user:2b7c...", "personId": 57, "method": "PUT", "path": "/v1/office/team/57/availability", "detail": { "what": "hours", "managedBy": "acme" } }] }

people: those whose own setting isn't "follow the company". overrides (owners only, [] otherwise): the latest 50 audit rows, newest first; action is availability_force (an owner overrode the integration) or availability_managed_by (who owns it changed); actor is user:<id>, api_key, admin:<id> or platform:<slug>.

#PUT /v1/office/availability-management

Body { "managedBy": "acme" } or { "managedBy": null }. Owners only (403 for field managers and dispatchers). An owner may set any platform with a live grant on the company (404 not_found otherwise) or null; a platform key may claim it for itself or release it when it owns it (403 for another slug, 409 managed_by_integration when another integration owns it). Recorded in the audit. Response 200: as GET. Ops set it for acme-crew with cli.ts platform-availability acme acme-crew on.

#POST /v1/office/team

Add a person. They're offered for work from now on: within their branch's service area, during their hours, for the services their skills cover. There is no default schedule: hours and availability are optional, and someone added without either has no working hours (every day null). A tech with no hours is never offered until hours are set (PATCH /v1/office/team/{id} or PUT /v1/office/team/{id}/availability).

Body:

Sends person.updated.

curl -s -X POST "$CREWLINK/v1/office/team" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Sam Rivera","branchId":"6a1f3c2e-9b0d-4e57-8c21-3f5a7d9e1b42","homeLat":41.94,"homeLng":-87.69,"skills":3,
       "hours":[[480,1020],[480,1020],[480,1020],[480,1020],[480,1020],null,null],"hourlyCostCents":4200}'

Response 201: the person.

Errors:

#PATCH /v1/office/team/{id}

Change someone's details, branch, home address, hours, skills, active status, mobile number, labor cost, designation, tax id, max travel distance or verified. Send at least one field. A move is homeLat/homeLng with the new address (from address search); their day starts and ends there from now on.

New hours, skills, branch and home apply to times offered from now on. Jobs already booked stay where they are; the response lists the upcoming ones (today onward) that now fall outside the person's hours, so the office can move them with POST /v1/office/jobs/{id}/move. Setting active: false lists all of that person's upcoming jobs.

Path: id (integer) person id.

Body:

curl -s -X PATCH "$CREWLINK/v1/office/team/1" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"hours":[[480,1020],[480,1020],null,[480,1020],[480,1020],null,null]}'

Response 200:

{ "id": 1, "outsideHours": [1207], "externalRefs": {}, "timezone": "America/Chicago", "rezoned": { "jobs": 0, "blocks": 0 } }

outsideHours is a list of job ids, empty when nothing is affected. timezone is their zone now; rezoned counts the booked jobs and time-off blocks moved onto a new clock (zero unless their zone changed). Sends person.updated, and availability.updated when hours was sent.

Errors:

#Documents

Files about a person: insurance certificates, licences, the W-9, ID. They go straight to storage (the API only keeps the key), and the office sees them through a link that works for 10 minutes. Link one to a credential with documentId so its expiry shows with it.

The document object:

{ "id": "1b0e4c1a-5f07-4a4e-9a51-21e7b8f6c9d0", "personId": 1, "kind": "insurance", "name": "COI 2026.pdf", "contentType": "application/pdf", "size": 120400, "expiresOn": "2027-01-01", "status": "uploaded", "createdAt": "2026-10-12T15:30:00.000Z", "url": "https://files.example.com/...?X-Amz-Signature=..." }

kind is insurance, license, w9, certification, id or other. status is pending until marked uploaded; url is null until then.

#GET /v1/office/team/{id}/documents

Response 200: { "documents": [ <document>, ... ] }, newest first. 404 not_found for someone not on your team.

#POST /v1/office/team/{id}/documents

Body: kind, name (1 to 200), contentType (application/pdf, image/jpeg, image/png, image/heic or image/webp), size (bytes, at most 25 MB), expiresOn (optional, YYYY-MM-DD).

Response 201: { "document": <document>, "uploadUrl": "..." }. PUT the file to uploadUrl with the same Content-Type within 15 minutes (storage refuses another type), then mark it uploaded.

#POST /v1/office/team/{id}/documents/{docId}/uploaded

Response 200: the document, status: "uploaded" with a url, and size set to the file's real size. CrewLink checks storage first: 409 not_uploaded when nothing is there yet (finish the PUT, then confirm again); 422 upload_mismatch when the file is bigger than the size you declared or than 25 MB, or isn't the declared type (the file and the pending document are removed: add it again); 502 storage_unavailable when storage didn't answer. Confirming twice is harmless.

#DELETE /v1/office/team/{id}/documents/{docId}

Response 200: { "deleted": true }. The file is deleted from storage. Credentials linked to it keep their details and lose the link.

#POST /v1/office/team/{id}/deactivate

Owner only. Takes them off the schedule (nothing new is offered or assigned) and turns off their field-app sign-in: every session ends and their passkeys are removed. Jobs already booked stay put.

Response 200: { "id": 7, "active": false, "signInsTurnedOff": 1, "upcoming": [1207, 1211] }: upcoming lists their booked jobs from today on, to move. Pay already earned stays in the pay report.

#POST /v1/office/team/{id}/reactivate

Owner only. Puts them back on the schedule. Their sign-in stays off; turn it back on with POST /v1/office/users/{id}/reactivate, so plan login limits apply as usual.

Response 200: { "id": 7, "active": true, "signIns": [{ "userId": "…", "active": false }] }.

#POST /v1/office/team/{id}/reset-sign-in

Owner only. For a lost phone or a shared device: signs every login of theirs out everywhere, removes their passkeys and replaces their token (the old one stops working). They sign in again with a code emailed to them; there are no passwords.

Response 200: { "id": 7, "signInsReset": 1 }.

#PUT /v1/office/team/{id}/availability

Replace someone's whole week. Body { "hours": [7 days], "timezone": "<optional>" }, Monday first; each day off (null or []), one window [start, end] or several [[start, end], ...], minutes after local midnight in the person's zone. Idempotent: the same week again changes nothing (changed: false) and sends nothing. Several windows a day are stored as sent (the person's availability; hours is each day's envelope) and merged is always []; the answer is the stored week. It replaces a change the tech made in the field app that hasn't taken effect yet. timezone, when sent, must be the person's (422 timezone_mismatch). Booked jobs stay; outsideHours lists the ones now outside. Sends availability.updated and person.updated when the week changed. force: true (owners): see Availability managed by an integration.

Response 200: { "personId": 57, "timezone": "America/Chicago", "availability": [[[480,720],[780,1020]], ...], "hours": [[480,1020], ...], "merged": [], "changed": true, "outsideHours": [] }. availability is the stored week in the request's shape (every day a list of windows, [] off): compare it with what you sent. hours is each day's envelope (first start to last end, null off), kept for code that reads one window a day; team reads carry both. Errors: 404 not_found, 409 managed_by_integration, 422 invalid_request (not 7 days, a window with start not before end, overlapping windows), 422 timezone_mismatch.

#Bases: POST, GET and DELETE /v1/office/team/{id}/bases

A base is where someone starts and ends their days for a while (lodging, a temporary address) instead of home; open times and routing use it on those days.

• POST { from, to, lat, lng, address?, reason?, externalRefs?, force? }: from/to local dates, inclusive, up to 366 days; lat/lng may come from address parts. 201: the base { id, personId, from, to, lat, lng, address, addressParts, reason, externalRefs, tripId, createdAt }. 409 trip_conflict (tripId) when a booked trip covers any of those days, 409 base_conflict (baseId) when another base does, 409 duplicate_external_ref (baseId) when one of the externalRefs ids is already on a base of your company (nothing is created).
• GET ?from=&to= (default today and the 90 days after): { "bases": [ ... ] }, the ones overlapping.
• DELETE /{baseId}: { "id": "...", "deleted": true }. A booked trip writes its own base (tripId set); removing that one is 409 trip_base.

Each change sends person.base.updated (with source, platform, forced). POST and DELETE answer 409 managed_by_integration when an integration owns the person's availability (more; owners: force: true in the body, ?force=true on DELETE).

#Branches and services

Branches are service areas: a location and a radius. People in a branch work within areaKm of its location, and its people without a home of their own start their day there. A branch without a usable location (located: false) covers nothing until an owner sets one. A branch in another time zone or country has its own timezone and country: its techs' hours and days, and the jobs it serves, run on its clock; its phone numbers get texts and address search covers its country. An address belongs to the branch whose area contains it (the nearest such branch), else to the nearest branch.

Services are what customers book. Active ones show on the booking page and to CrewConnect senders.

#The branch object

{ "id": "9c2d...", "name": "Denver", "lat": 39.7392, "lng": -104.9903, "address": "1437 Bannock St, Denver, CO 80202", "located": true, "areaKm": 40, "timezone": "America/Denver", "ownTimezone": "America/Denver", "country": "US", "ownCountry": null }

#GET /v1/office/branches

Response 200: { "branches": [ <branch>, ... ] }, sorted by name.

#POST /v1/office/branches

Add a branch.

curl -s -X POST "$CREWLINK/v1/office/branches" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Denver","lat":39.7392,"lng":-104.9903,"areaKm":40,"timezone":"America/Denver"}'

Response 201: the branch. Put people in it with branchId on POST /v1/office/team or PATCH /v1/office/team/{id}. Errors: 422 invalid_request for an unknown zone or country.

#PATCH /v1/office/branches/{id}

Change a branch. Owner only. Send only what changes: name, lat and lng together (with address, its line from address search; address: null clears the line and keeps the coordinates), areaKm, timezone (null: back to the company's), country (null: the company's).

A new location moves the centre of its area. Its people who start from the branch (added without a home of their own: their home is a copy of the branch's old spot and they have no address) move with it. Booked jobs stay as they are.

A new time zone keeps every booked instant: the branch's people's jobs from now on (booked or held) and their time off are re-expressed in the new zone, so a visit at 9:00 Chicago time shows as 8:00 Denver time; customers are not texted, because nothing moved. Working hours stay as typed (9 to 5 means 9 to 5 on the new clock).

curl -s -X PATCH "$CREWLINK/v1/office/branches/9c2d..." -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"timezone":"America/Denver"}'

Response 200: the branch plus "rezoned": { "jobs": 12, "blocks": 2 } (what was re-expressed).

Errors: 403 forbidden (not an owner), 404 not_found (not your branch), 422 invalid_request (unknown zone or country, lat without lng, an address without lat/lng for a branch that has no location yet, nothing to change).

#The service object

{
  "id": 3,
  "name": "New system install",
  "minutes": 150,
  "skills": 4,
  "peopleNeeded": 2,
  "days": 1,
  "priceCents": 450000,
  "depositCents": 50000,
  "currency": "USD",
  "active": true,
  "basePayCents": 12000,
  "paySplit": "split",
  "category": "residential",
  "daylightOnly": false
}

#GET /v1/office/services

All your services, turned-off ones included. Response 200: { "services": [ <service>, ... ] }.

#POST /v1/office/services

Add a service. Body: the fields of the service object except id. name and minutes are required; the defaults are skills: 1, peopleNeeded: 1, days: 1, priceCents: null, depositCents: 0, currency: "USD", active: true, daylightOnly: false.

curl -s -X POST "$CREWLINK/v1/office/services" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Duct cleaning","minutes":120,"peopleNeeded":2,"priceCents":34900,"depositCents":5000}'

Response 201: the service. Errors: 422 invalid_request (a field failed validation, or depositCents is more than priceCents).

#Daylight only

A service with daylightOnly: true (owners set it, on POST or PATCH; Settings, Services in the web app) is offered and booked only when the whole visit is in daylight at the job's address on that date: the start at or after local sunrise, the end (the start plus the service's booked length: minutes plus 20%, rounded up to 5) at or before local sunset, on every day of a multi-day service. Sunrise and sunset are worked out from the address and date (the NOAA solar equations, to about a minute, in the address's time zone with daylight saving). Where the sun doesn't rise that day nothing is offered; where it doesn't set, the whole day counts.

• Offered times (booking page availability, POST /v1/office/availability, first-available, client share links, the intake queue's suggestions and pick-a-new-time choices) only include daylight starts.
• Holds, bookings and moves outside it (booking page, share link and key holds, a share link booking of a held time, POST /v1/office/jobs, move, a customer's own reschedule) get 409 outside_daylight with a message that says the times, e.g. Residential survey is booked in daylight only: on 2026-12-14 at this address the sun rises at 7:12 AM and sets at 4:20 PM, so a 75-minute visit has to start between 7:12 AM and 3:05 PM. With allowQueue on POST /v1/office/jobs the request goes to the intake queue instead.
• An owner can override it: allowOutsideHours: true on POST /v1/office/jobs or a move books a daylight-only service outside daylight (working hours and every other check still apply). Dispatchers and field managers get 403 owner_only for it. On any other service allowOutsideHours stays for imports only.
• Exempt: imports (source: "import") and history written with allowPast.

#PATCH /v1/office/services/{id}

Change any of the fields, or turn the service off with active: false. Send at least one field. Changes apply to times offered and jobs booked from now on; a new basePayCents applies to jobs completed from now on.

Response 200: the service. Errors: 403 forbidden (a dispatcher sent basePayCents, paySplit or daylightOnly), 404 not_found (no service with that id in your company), 422 invalid_request (no field sent, a field failed validation, or the deposit would be more than the price).

#Time off and blocks

A block takes time off someone's calendar: time off, training, a personal appointment. Nothing new is offered or assigned inside it. Busy time from a tech's linked Google or Outlook calendar also shows up as blocks (with source google or outlook) on the schedule.

#POST /v1/office/blocks

Block time for one person. Jobs already booked inside the block are not moved: they come back as conflicts for the office to move or reassign.

Body:

curl -s -X POST "$CREWLINK/v1/office/blocks" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"personId":1,"start":"2026-11-03T14:00:00Z","end":"2026-11-03T23:00:00Z","reason":"Dentist"}'

Response 201:

{
  "id": 17,
  "personId": 1,
  "start": "2026-11-03T08:00",
  "end": "2026-11-03T17:00",
  "timezone": "America/Chicago",
  "reason": "Dentist",
  "conflicts": [],
  "externalRefs": {}
}

start and end are the person's wall clock (their branch's zone, in timezone). conflicts lists booked job ids that overlap the block.

Sends the block.created webhook event (with source, platform and forced: who added it).

Errors:

#DELETE /v1/office/blocks/{id}

Remove a block. Its times become bookable again. This works on calendar-synced blocks too, but the next calendar sync puts them back while the event is still in the person's calendar.

Path: id (integer) block id.

Response 200:

{ "id": 17, "deleted": true }

Query: force=true (owners only) removes a block although an integration owns the person's availability (recorded). Busy time from a linked calendar (source google or outlook) can always be removed.

Sends the block.deleted webhook event (with the block's externalRefs, blockSource, and source, platform, forced). Errors: 404 not_found (no block with that id in your company), 403 forbidden (force from someone who isn't an owner), 409 managed_by_integration.

#GET /v1/office/blocks

Blocked time that overlaps a date range, earliest first: blocks made here and busy time imported from linked calendars, with the person's name. Use it to list time off and remove some with DELETE.

Query:

curl -s "$CREWLINK/v1/office/blocks?from=2026-11-01&to=2026-11-30" -H "Authorization: Bearer $KEY"

Response 200:

{
  "blocks": [
    { "id": 17, "personId": 1, "person": "Maria Gomez", "start": "2026-11-03T08:00", "end": "2026-11-03T17:00", "reason": "Dentist", "source": "office" },
    { "id": 21, "personId": 2, "person": "James Okafor", "start": "2026-11-04T09:00", "end": "2026-11-04T10:00", "reason": null, "source": "google" }
  ]
}

Range and paging. At most 92 days per call (from to to, inclusive). A longer range, or to before from, is 422 invalid_request with "message": "Up to 92 days, from on or before to.". There is no cursor or page size: every block in the range comes back in one answer, ordered by start then id. To read a longer stretch, call again with the next window (from = the day after the previous to); a block that spans two windows is listed in both, so de-duplicate by id. externalSource/externalRef lookups have no range limit.

Errors: 422 invalid_request (to before from, or more than 92 days).

#Office jobs

Booking, moving and cancelling from the office uses the same safeguards as the booking page: CrewLink locks the affected days, rechecks the live schedule (everyone's other jobs, blocks, linked calendars and the drive between jobs at that hour) and only then writes. Two dispatchers can't double-book the same tech.

The customer is texted for every change (confirmation with their manage link, then a reminder; a new time; a cancellation). Texts go to mobile numbers in your company's countries (yours and every branch's): a US company texts US and Canadian numbers, one with a London branch UK numbers too. A number typed without + and a country code is read the way the job's country writes it (020 7946 0958 at a London job). The texts show the time on the clock of the branch serving the job. The customer-facing manage link is described in booking-page.md.

#POST /v1/office/first-available

Every start time a qualified tech can actually make at an address (their other jobs, calendar, hours and the drive at that hour), with who CrewLink would send, earliest first. This is the office's "first available" view, like the old app's schedule screen: unlike the booking page's availability (and POST /v1/office/availability, the same answer with a key) it lists every feasible start (the booking page hides starts whose added driving is more than 20 minutes worse than the best that day) and has no one-hour lead time (anything from now on). Times are on the clock of the branch serving the address.

Body:

curl -s -X POST "$CREWLINK/v1/office/first-available" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"serviceId": 3, "lat": 41.955, "lng": -87.675, "from": "2026-11-16"}'

Response 200:

{
  "timezone": "America/Chicago",
  "slots": [
    { "start": "2026-11-16T14:15:00.000Z", "local": "2026-11-16T08:15", "techs": [{ "id": 1, "name": "Maria Gomez" }] }
  ],
  "firstAvailable": { "start": "2026-11-16T14:15:00.000Z", "local": "2026-11-16T08:15", "techs": [{ "id": 1, "name": "Maria Gomez" }] },
  "outsideArea": false
}

techs is who would go (as many as the service needs, least added driving first; a platform key sees first name and last initial); book the time with POST /v1/office/jobs, which rechecks it under a lock. outsideArea is true when no one's service area covers the address. Errors: 404 unknown service.

#POST /v1/office/jobs

Book a job for a phone-in or walk-in customer, or for an integration. Unlike the booking page there's no hold step and no one-hour lead time: any time from now on works if someone can make it. CrewLink picks the best qualified tech(s) for that start from the people serving the address; the job is on the address's clock (timezone in the answer; with techIds, theirs). Or book a time you held with POST /v1/office/holds (or the booking page's holds): send holdId and holdSecret instead of serviceId, the time and the location; the hold's service, time, place and crew stand.

Body:

The job records who booked it (the signed-in person, or none for the company API key) and where it came from (office, or api for the company API key). People with a team or own scope see it as theirs.

curl -s -X POST "$CREWLINK/v1/office/jobs" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "serviceId": 1,
  "lat": 41.955, "lng": -87.675,
  "start": "2026-11-16T16:00:00Z",
  "customer": { "name": "Pat Quinn", "phone": "312 555 0177" },
  "address": "2210 W Addison St, Chicago",
  "notes": "Side door, dog in the yard"
}'

Response 201:

{
  "jobId": 1042,
  "start": "2026-11-16T16:00:00.000Z",
  "local": "2026-11-16T10:00",
  "timezone": "America/Chicago",
  "techs": [{ "id": 1, "name": "Maria Gomez" }],
  "manageToken": "r1Hc0vQyX9b2mN4kT7sW8zLp5uJ3eA6d",
  "externalRef": null,
  "externalSource": null,
  "externalRefs": {}
}

manageToken is the customer's manage-link token. It's shown once and is already in the confirmation text, so you only need it if you show the customer their link yourself. A platform key sees tech names as first name and last initial (Maria G.).

Sends the booking.created webhook event with source: "office" ("platform" for a platform key).

History (allowPast: true, or source: "import"). A start that has already passed is booked as given, with no lock, no availability check and no text to the customer (booking.created goes out with its techs and history: true, to webhook endpoints with historyEvents: true only; see what each path sends): the people in techIds (any of your people, active or not), else the nearest active people with the service's skills (422 when you have nobody). Each visit lasts the service's minutes. The answer is the usual 201 plus "history": true. Until it's marked done with complete (at may then go back to the job's day), it shows as overdue. A future start in the same request books normally (the lock and the recheck, with techIds if sent).

Old commitments on import (source: "import" with techIds, allowOutsideHours). A future visit the old system already confirmed with the homeowner is booked for those techs at that time even when it's outside their working hours, on a day they don't work, in the on-call window or further than the engine would drive them. Their hours are not changed. The answer adds "outsideHours": true when the visit is outside a tech's hours, and every read of the job says so too (outsideHours on the job row and on schedule visits) so the office can see it. A visit inside their hours books as usual. Still refused:

• the tech is already on another visit then (any job, any clock): 409 tech_busy with personId, conflictJobId (the job in the way) and a message; with allowQueue: true the job goes to the intake queue instead (202), as your platform's importer does;
• time off on their calendar, missing skills, or someone not on the team (or not active): 409 slot_taken with that reason, as before.

Without source: "import" nothing changes: a time outside a tech's hours is 409 slot_taken with reason: "outside_hours". A move is checked like any booking and clears outsideHours.

Queued instead (allowQueue: true). When the time can't be booked, the job is filed as unscheduled in the intake queue with the time asked for and the reason (and its external ids and address parts), the customer is texted that the office will text them a time (not for source: "import"), and request.created goes out with queued: true. Nothing is on the schedule yet; place it with move or drop it with discard. Response 202:

{
  "jobId": 1043,
  "status": "unscheduled",
  "queued": true,
  "requested": { "start": "2026-11-16T16:00:00.000Z", "local": "2026-11-16T10:00" },
  "reason": "No qualified tech can make that time: their other jobs or the drive are in the way. Pick another time."
}

Errors:

#POST /v1/office/jobs/{id}/move

Move a booked job to another time and/or other techs (a drag on the board). With techIds, those people go if the job fits their day; otherwise the request fails. Without techIds, the tech(s) already on the job stay if they still fit at the new time (a two-tech job keeps both, each checked); otherwise CrewLink picks the best tech(s) then, so one who can't make it is replaced. The office's Move panel shows everyone on the job, ticked, and sends techIds only when the office changes who goes; a drag on the board sends the whole crew with the dragged row's tech swapped. If the job needs more people than you name, CrewLink adds the rest. The customer's manage link keeps working and they're texted the new time. A move turns reminder texts back on for a job booked with remind: false (an import).

Unscheduled jobs. A job an emergency or a running-late tech moved off the board with no new time (the booking.rescheduled event had needsCall: true), or one waiting in the intake queue, is booked at start the same way: same checks, same techIds rule. The customer gets a confirmation text with a new manage link (the old one stops working), and the pick-a-new-time link they were texted stops working.

Path: id (integer) job id. Booked or unscheduled jobs (bumped or queued).

Body:

curl -s -X POST "$CREWLINK/v1/office/jobs/1042/move" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"start":"2026-11-16T19:00:00Z","techIds":[3]}'

Response 200:

{
  "jobId": 1042,
  "start": "2026-11-16T19:00:00.000Z",
  "local": "2026-11-16T13:00",
  "timezone": "America/Chicago",
  "techs": [{ "id": 3, "name": "Aisha Khan" }]
}

Sends booking.rescheduled with source: "office", from (the old local start; null for a bumped job) and techs. A queued request placed this way sends booking.created instead: it's booked for the first time. Every move sends its webhook, including history moves and moves with notify: false: notify only controls homeowner texts, never webhooks (what each path sends).

#Owners: double-booking and past times on any job

An owner may move any job (not only imports) onto a tech who is already busy, or to a time that has passed. An owner here is a signed-in user with role owner, the company API key, a super admin acting as the owner, or a platform key with write (it acts as the owner). Dispatchers and field managers sending allowOverlap or allowPast on a job that isn't an import get 403 owner_only ("Only an owner can double-book a tech (allowOverlap) on a job. ..."); their other moves are unchanged. Imports keep working as before for everyone who may move them.

• allowOverlap: true with techIds: when the only thing in the way is another visit of theirs (or the drive to it), the techs go anyway, and both jobs stay on them. Still checked, as for any move: time off, skills, the team, the test split, and (unlike an import) their working hours and the on-call reserve (409 slot_taken with the reason). The same as for an import: the answer adds doubleBooked ([{ personId, conflictJobId }], one per tech) when an overlap was actually skipped, and the moved job is flagged needs attention Double-booked with #<conflictJobId> (every job it overlaps). job.needs_attention goes out as for any flag, unless the move is notify: false (or the job's homeowner texts are off): then only the flag and its timeline entry are written. booking.rescheduled (or booking.created, from the queue) goes out either way. Without techIds: 422.
• allowPast: true: a start that has passed is written as history, exactly as for an import in the past: booked as given (techIds, else the techs already on it; 422 when there are none), no availability, hours or overlap checks, visits of the service's length, overdue until it is completed (which may then go back to the job's own day), no homeowner text and no reminder (queued ones are dropped). The answer adds "history": true; booking.rescheduled (or booking.created from the queue) goes out with the techs and history: true (history emissions reach only webhook endpoints with historyEvents: true). Without allowPast, a past start is still 409 in_the_past for everyone.

curl -s -X POST "$CREWLINK/v1/office/jobs/1043/move" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"local":"2026-10-27T09:00","techIds":[3],"allowOverlap":true}'

{ "jobId": 1043, "start": "2026-10-27T14:00:00.000Z", "local": "2026-10-27T09:00", "timezone": "America/Chicago", "techs": [{ "id": 3, "name": "Aisha Khan" }], "doubleBooked": [{ "personId": 3, "conflictJobId": 1042 }] }

The office's Move panel shows owners Book anyway (double-book) when a move is refused because the tech is busy (409 tech_busy, or 409 slot_taken with reason: "doesnt_fit"), and Record past time when it is refused as in_the_past. Dispatchers don't see either.

#Unassigning a job (techIds: [])

techIds: [] takes everyone off a booked job without changing its time. Owners, platform keys with write and dispatchers (anyone who may move the job) may do it.

• The job goes back to the intake queue as unscheduled with intakeReason: "Unassigned"; its visits are removed (it leaves the board, the techs' days and their calendars); job reads show the kept time in requested ({ start, local }), as for a bumped job. Place it again with a move and techIds (the customer then gets a confirmation with a fresh manage link, unless the job's texts are off).
• No homeowner text (their time hasn't changed), whether or not notify is sent; queued texts for the job (the reminder) are dropped. notify may still be sent to store the job's flag.
• booking.rescheduled goes out with source: "office", status: "unscheduled", techs: [], start and local null, unassigned: true, from (the old local start) and requested ({ start, local }, the time it keeps). There is no separate booking.unassigned event: subscribers to booking.rescheduled with historyEvents: true see it (endpoints without it don't get unassigns).
• Send no start or local (422); not with allowOverlap, allowPast or allowOutsideHours (422); 422 for a job that isn't booked (already in the queue) or is done.

curl -s -X POST "$CREWLINK/v1/office/jobs/1042/move" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"techIds":[]}'

{ "jobId": 1042, "status": "unscheduled", "start": "2026-11-16T19:00:00.000Z", "local": "2026-11-16T13:00", "timezone": "America/Chicago", "techs": [], "unassigned": true }

The job drawer on the board has an Unassign button that does this.

#Placing an import at its old commitment

An imported job (source: "import", from POST /v1/office/jobs) that landed in the intake queue, or is already on the board, can be placed at the time the old system had confirmed, for the techs it confirmed, the way an import with techIds is booked: send techIds (and allowOutsideHours: true, or leave it out: it is implied for imports with techIds). Those techs go even outside their working hours, on a day they don't work, in the on-call window or past the drive the engine would allow; their hours are not changed. It works from the queue (queued or unscheduled: booked now, booking.created for a queued one) and from the board (booked: moved). When the techs share a clock the job goes onto it (timezone in the answer); a local time is read on that clock. The answer adds outsideHours: true when the time is outside a tech's hours, and job reads show it until an ordinary move.

Still refused: a tech already on another visit that overlaps (whatever clock it is on; the job's own visit never counts) with 409 tech_busy (personId, conflictJobId, a message with the overlap); time off, missing skills, someone not on the team (or on the other side of the test split) with 409 slot_taken. Platform keys with write may do it.

A past time for an import (allowPast, implied). For an imported job, a start that has passed is not 409 in_the_past: the move writes it as history, the way POST /v1/office/jobs writes a past import (allowPast: false turns it off; on any other job a past start stays 409 in_the_past unless an owner sends allowPast: true, and allowPast from a dispatcher or field manager is 403 owner_only). Use it for a queued or unscheduled import the old app had booked at a time that has now passed. The job is booked as given: techIds (else the techs already on it; 422 when there are none), with no availability, hours or overlap checks, and real visits of the service's length, so it reads overdue (awaiting completion) like any past booked job never marked done; finish it with complete. No homeowner text and no reminder (queued ones are dropped); booking.created (from the queue) or booking.rescheduled always goes out, with the techs and history: true (also with notify: false: notify only controls homeowner texts) (history emissions reach only webhook endpoints with historyEvents: true). The answer adds "history": true. Any other job may be moved to a past time the same way by an owner with allowPast: true (Owners). Cancelled and done imports are corrected with POST /v1/office/jobs/{id}/history instead.

curl -s -X POST "$CREWLINK/v1/office/jobs/4570/move" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"local":"2026-09-17T09:00","techIds":[81],"notify":false}'

{ "jobId": 4570, "start": "2026-09-17T14:00:00.000Z", "local": "2026-09-17T09:00", "timezone": "America/Chicago", "techs": [{ "id": 81, "name": "Aim Torres" }], "history": true }

Keeping the old app's double-booking (allowOverlap: true). The old app let a tech be on two jobs at once; an import keeps that when the move sends allowOverlap: true with techIds. The overlap with another visit of theirs is booked anyway (no 409 tech_busy) and both jobs stay on the tech. Time off, skills and the team are still checked (409 slot_taken), and outside hours is already implied. For imported jobs with techIds (422 invalid_request without techIds, or with allowOutsideHours: false); on any other job only owners may send it (Owners; 403 owner_only for dispatchers and field managers). When an overlap was actually skipped:

• the answer adds doubleBooked: [{ "personId": 81, "conflictJobId": 4502 }] (one per tech);
• the moved job is flagged needs attention with the reason Double-booked with #4502 (imported from the old app) (every job it overlaps, when there are several techs), so the office sees it on the board and in the needs-attention tab. The other job is not changed;
• job.needs_attention goes out as for any flag, unless the move is notify: false (or the job's homeowner texts are already off): then only the flag and its timeline entry are written, and nothing is sent. The move itself behaves as any move (with notify: false: no homeowner text; booking.rescheduled or booking.created always, with the techs).

curl -s -X POST "$CREWLINK/v1/office/jobs/4568/move" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"local":"2026-10-27T09:00","techIds":[81],"allowOverlap":true,"notify":false}'

{ "jobId": 4568, "start": "2026-10-27T14:00:00.000Z", "local": "2026-10-27T09:00", "timezone": "America/Chicago", "techs": [{ "id": 81, "name": "Aim Torres" }], "doubleBooked": [{ "personId": 81, "conflictJobId": 4502 }] }

curl -s -X POST "$CREWLINK/v1/office/jobs/4568/move" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"start":"2026-10-12T19:00:00Z","techIds":[81]}'

{ "jobId": 4568, "start": "2026-10-12T19:00:00.000Z", "local": "2026-10-12T12:00", "timezone": "America/Phoenix", "techs": [{ "id": 81, "name": "Aim T." }], "outsideHours": true }

Errors:

#POST /v1/office/jobs/{id}/cancel

Cancel a booked, unscheduled or queued job, including one that is already done (below). The office has no cutoff (customers and client companies do: cancelCutoffHours, see Company, settings and the API key). The customer is texted (unless notify is false, or the job's homeowner texts are off: Homeowner messaging) and the reminder is dropped; an outstanding pick-a-new-time link stops working.

Path: id (integer) job id.

Body (optional):

Response 200:

{ "jobId": 1042, "status": "cancelled" }

Sends booking.cancelled with source: "office", reason and techs (who was going), always: notify: false only skips the homeowner's text.

#Cancelling a job that is done

Owners and dispatchers (for jobs in their scope), the company API key and a platform key with write may cancel a job that is already done. Then:

• the job reads jobStatus: "cancelled" with cancelledAfterDone: true; doneAt is kept as history;
• nobody is texted unless you send notify: true (a done job's default is false);
• booking.cancelled carries wasDone: true;
• KPIs and plan vs actual stop counting it as done (a day already reviewed is reviewed again without it);
• each tech's pay for it is taken back, listed in payReversed:
  • from a pay week that is still open, the job line is removed and that day's mileage is redone without the stop (how: "removed");
  • from a week that is closed or paid, those lines stay as they were paid and a negative adjustment, reason Job #<id> cancelled after completion, goes into the open week holding today (how: "adjustment", lineId is that line). It shows in GET /v1/office/pay/lines and the pay report like any adjustment.

{
  "jobId": 1042,
  "status": "cancelled",
  "wasDone": true,
  "payReversed": [{ "personId": 7, "amountCents": 8120, "currency": "USD", "how": "adjustment", "lineId": 5531 }]
}

amountCents is what was taken back: the job pay plus what the stop added to that day's mileage. The change is recorded in the company's audit log.

Errors: 404 not_found (no booked, unscheduled or queued job with that id), 422 invalid_request. To drop a queued request with a "we can't make it" text instead of a cancellation, use discard.

#POST /v1/office/jobs/{id}/history

Correct an imported job's history: the time and techs the old system had. For a job imported with source: "import" (POST /v1/office/jobs) that is now cancelled or done, for example an old job that was filed unscheduled and then cancelled, so it has no visit, though in the old system it was booked at a real time with real techs. The job keeps its id and externalRefs.

Test people. A cancelled job keeps whoever the old system had, test people included, because it is never booked or counted. A done job follows the test split: a test client's job takes only test people, and any other job never does.

• The time and techs are set exactly as sent: no availability, working hours, drive, time-off or overlap checks. Sending it again replaces them.
• Nothing is sent: no homeowner text or email, no tech notification, and no webhook, deliberately (the only office path that sends none: it rewrites the record of a cancelled or done import, never the schedule). The job's timeline gets a history_corrected entry (old and new time and techs), and updatedAt moves, so updatedSince picks it up: an integration mirroring techs re-reads the job from there.
• The status stays as it is: cancelled stays cancelled, done stays done (doneAt is kept).
• A cancelled job stays off the schedule, the same as a job booked and then cancelled (cancelling always removes the visits): it never blocks a booking for those techs, never shows on the schedule, dispatch, the live board, a tech's day or a linked calendar, and never counts in KPIs or pay. Job reads show its corrected start, local, end and techs; visits on the detail stays empty.
• A done job's visits are replaced (one per tech and day of the service), so it keeps counting as a done job does. What was recorded when it was completed (plan vs actual, tech pay lines) is left as it was.

Path: id (integer) job id.

Body:

curl -s -X POST "$CREWLINK/v1/office/jobs/4571/history" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"start":"2026-08-03T14:00:00Z","techIds":[81]}'

Response 200:

{ "jobId": 4571, "status": "cancelled", "start": "2026-08-03T14:00:00.000Z", "local": "2026-08-03T09:00", "end": "2026-08-03T15:50:00.000Z", "endLocal": "2026-08-03T10:50", "timezone": "America/Chicago", "techs": [{ "id": 81, "name": "Alex Rivera" }] }

Platform keys need write and see techs as "First L.".

Errors:

There is no DELETE for jobs: cancel them, and correct an import's history with this.

#GET /v1/office/jobs/{id}/photos

Photos the tech took on a job. Each url is a view link that works for 15 minutes; fetch the list again for fresh links.

Path: id (integer) job id (any status).

Response 200:

{
  "photos": [
    {
      "id": "6c1e9a52-3b7f-4d0e-a8c4-2f9d1b7e5a10",
      "url": "https://<signed view link, valid 15 minutes>",
      "caption": "Cracked heat exchanger",
      "at": "2026-10-15T15:42:07.000Z"
    }
  ]
}

Only finished uploads are listed. Errors: 404 not_found.

#GET /v1/office/jobs/{id}/texts

The conversation with the customer about a job: every text CrewLink sent or will send for it (confirmation, reminder, move, cancellation, on the way, review link, invoice, deposit, and the rest), newest first, up to 200. The customer's number is masked to its last 4 digits.

Path: id (integer) job id (any status).

curl -s "$BASE/v1/office/jobs/4182/texts" -H "Authorization: Bearer $KEY"

Response 200:

{
  "jobId": 4182,
  "texts": [
    {
      "id": 90211,
      "kind": "review",
      "channel": "sms",
      "to": "***-***-0142",
      "body": "Northline Heating & Air: thanks for having us. How did we do? It takes 10 seconds: https://go.crewlink.ai/r/4182?t=...",
      "status": "sent",
      "sendAfter": "2026-10-14T16:52:00.000Z",
      "sentAt": "2026-10-14T16:52:00.000Z"
    },
    {
      "id": 90187,
      "kind": "on_my_way",
      "channel": "sms",
      "to": "***-***-0142",
      "body": "Northline Heating & Air: Maria is on the way, about 18 min out.",
      "status": "sent",
      "sendAfter": "2026-10-14T15:02:00.000Z",
      "sentAt": "2026-10-14T15:02:00.000Z"
    }
  ]
}

kind is one of confirmed, reminder, rescheduled, cancelled, on_my_way, review, invoice, deposit, recurring_booked, bumped, request_received, request_declined, bumped_choices, request_queued. status: queued (waiting for sendAfter, e.g. a reminder), sent, failed (after three tries) or cancelled (dropped before it went out, because the job moved or was cancelled); sentAt is null unless it was sent. Errors: 404 not_found (no such job, or another company's).

#Intake and job search

Every job in one place. The intake queue holds every job that has no time yet, oldest first:

• requests nobody could take at the time asked, when whoever sent them asked to queue instead of being refused (allowQueue: true on POST /v1/office/jobs, on a booking-page hold in booking-page.md, or on a CrewConnect send in crewconnect.md),
• out-of-area requests from the booking page (see Out-of-area requests and trips),
• booked jobs an emergency or a running-late tech moved off the board with no new time.

The office places each one with move (or accept for an out-of-area request), leaves it in the queue, or drops it with discard. GET /v1/office/jobs (under Jobs for integrations: one list for the office and integrations) searches every job, past and future.

#Job statuses

Every job read (the list, the detail, intake risks) has the stored status and stage, and what people see: jobStatus and two flags. Visits on the schedule carry jobStatus, overdue and needsAttention too.

Holds in progress on the booking page are never listed.

#The job row

Every office read of a job returns the same object: the job summary below, which GET /v1/office/jobs/{id} extends. The fields for intake:

People with a team or own scope get only their own jobs in the list, the detail, the intake counts and the CSV.

#GET /v1/office/intake

How many jobs are in each tab, and the dispatch risks: jobs still unscheduled 3 or more days after they were filed (oldest first), then visits that ended without being marked done. Rows for a tab come from GET /v1/office/jobs with tab.

Query (all optional, they narrow the counts): q, techId, serviceId, source, clientCompanyId or client, filedFrom, filedTo, as for GET /v1/office/jobs.

Response 200:

{
  "counts": { "all": 412, "unscheduled": 3, "scheduled": 57, "overdue": 2, "needs_attention": 1, "done": 331, "cancelled": 21 },
  "risks": [
    { "kind": "aging", "job": { "id": 1031, "status": "unscheduled", "ageDays": 5, "...": "a job row" } },
    { "kind": "overdue", "job": { "id": 1012, "status": "scheduled", "overdue": true, "overdueDays": 1, "...": "a job row" } }
  ],
  "agingDays": 3
}

scheduled counts upcoming work only: overdue jobs count under overdue. A job can be in needs_attention and one other tab.

#GET /v1/office/jobs.csv

The list as a spreadsheet: the rows GET /v1/office/jobs would return for these filters and sort, up to 5,000, as CSV (RFC 4180, UTF-8 with a byte order mark). Columns: job_id, status, job_status, overdue, needs_attention, attention_reason, customer, phone, address, city, state, service, filed (your company's zone), scheduled, requested (the job's own zone, named in timezone), timezone, techs, source, sent_by, external_ref. Same query as the list, without limit and cursor.

#GET /v1/office/intake/{id}/options

Who could take an unscheduled job on a day: every qualified tech whose home is within radius of the job, closest first, with their open starts that day (15-minute steps) and the drive to each from where they'd set off (the job before, else home). Use it to place a job from the queue, then book the start with move and techIds (or accept for an out-of-area request).

Query: date (YYYY-MM-DD, local, required); radius (in units, 1 to 2500; default 100 mi or 160 km).

Response 200:

{
  "jobId": 1043,
  "date": "2026-10-14",
  "units": "mi",
  "radius": 100,
  "outsideArea": false,
  "techs": [
    {
      "id": 1, "name": "Maria Gomez", "distance": 2.2, "driveMinutes": 6,
      "slots": [
        { "start": "2026-10-14T13:00:00.000Z", "local": "2026-10-14T08:00", "driveMinutes": 6, "from": "home" },
        { "start": "2026-10-14T16:30:00.000Z", "local": "2026-10-14T11:30", "driveMinutes": 9, "from": "previous_job" }
      ]
    }
  ],
  "crews": []
}

Errors: 404 not_found (no unscheduled job with that id), 422 invalid_request.

#POST /v1/office/intake/{id}/discard

Drop a job from the intake queue. A queued or out-of-area request is declined and the customer is texted that you can't make it (with message added, e.g. a referral). A bumped job (it had a time before) is cancelled with the usual cancellation text and booking.cancelled event.

Body (optional): message (up to 300 characters), notify (default true; false sends no text).

Response 200: { "jobId": 1043, "status": "cancelled" }. Errors: 404 not_found (no unscheduled job with that id).

#Jobs for integrations

Reading and finishing jobs from another system: a CRM, or a platform (platforms.md walks through the whole flow). Every company key works; a platform key sees techs as first name and last initial ({ "id": 3, "displayName": "Maria G." }) and needs the scopes listed in platforms.md.

#GET /v1/office/jobs

Every job of the company, past and future: one list for syncing and for the office's search (the Jobs and Intake pages). By default ordered by when it last changed (updatedAt, then id), oldest first. Bare holds are left out unless you ask for status=held.

Response 200: { "jobs": [ <job summary>, ... ], "nextCursor": "<string or null>", "total": 38 }. A summary has id, status, stage, jobStatus, overdue, overdueDays, service (id, name, category), start/local/end/endLocal (null for jobs with no time) and timezone, address, city, state, lat, lng, customer (name, phone), tech (the first assigned) and techs, externalRef, externalSource, externalRefs, needsAttention ({ reason, at } or null), doneAt, createdAt, updatedAt, and the intake fields in the job row. The full shape, with an example, is in platforms.md. total counts every match. Errors: 422 invalid_request (an unknown status, a bad date or range, a cursor this endpoint didn't give out). GET /v1/office/jobs.csv returns the same search as CSV.

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

One job in full: the summary plus customer (name, phone, email), addressParts, notes (from booking), visits (each tech-day with times), timeline (created, then en_route, arrived, checkin, done, note, attention, attention_cleared, history_corrected, each with at, by tech/office/system, the tech and any text), attachments (with 15-minute download links), textsCount and arrivedAt. Like every job read (the list and intake too) it has homeownerTexts: false when the job sends its homeowner nothing (Homeowner messaging). Errors: 404 not_found.

#POST /v1/office/jobs/{id}/complete

Mark a booked job done for work finished outside the field app.

Always: the stage becomes done (doneAt = at), each visit is recorded as done in plan vs actual (on the day of at, or the person's last visit before it when the work was marked done later; KPIs count the job on the day it started) and queued reminder texts are dropped. Unless silent: the customer is texted the review link (30 minutes after at, or now), a CrewConnect payout is scheduled when a partner did the work, and job.completed goes out with source: "api" (a company or platform key) or "office" (a signed-in user).

Response 200: { "jobId": 1042, "stage": "done", "doneAt": "...", "silent": false, "minutesOnSite": 94 } (minutesOnSite is null without an arrival tap). Errors: 404 not_found, 409 already (it's done), 409 not_booked (not a booked job), 422 invalid_at.

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

{ "text": "Gate code 4411" } (1 to 4000 characters). Adds an office note to the timeline; the tech sees it in the job's history in the field app. Response 201: { "id": 88, "at": "..." }. Errors: 404 not_found.

#POST /v1/office/jobs/{id}/attention and DELETE /v1/office/jobs/{id}/attention

POST { "reason": "Roof access unclear" } (1 to 500 characters) flags the job: needsAttention shows on the list and the detail, the timeline gets an attention entry and job.needs_attention goes out. Flagging again replaces the reason. DELETE clears it (timeline: attention_cleared; no webhook). The same flag (timeline entry and webhook) is raised by a tech's office_review check-in (source: "tech"), by a customer text that fails after three tries (source: "system", only when the job isn't flagged already) and by a job not closed out (source: "system", by: "closeout"). Responses 200: { "jobId": 1042, "needsAttention": { "reason": "...", "at": "..." } } and { "jobId": 1042, "needsAttention": null }. Errors: 404 not_found.

#Not closed out

Every 15 minutes CrewLink looks for booked jobs that should be finished but aren't marked done, and flags them needs attention (shown on Dispatch's risks, the Needs attention tab and the job), so the office can chase the tech or close the job:

• When: 3 hours after the job's last visit's scheduled end, or at 21:00 on that day when that comes sooner (and the visit has ended), in the job's own time zone. A visit ending at 11:15 is flagged at 14:15; one ending at 19:30 at 21:00; one ending at 22:00 at 01:00.
• Which: status booked and not done, whatever its stage (not started, on the way, on site). Not imports (source: "import") or anything written as history (booked at or after its own start: allowPast on a new job or from the queue), not held, queued or cancelled jobs, and only visits that ended in the last two days. Test jobs are included.
• Reason: Not closed out: still <stage> since <time>: not started since 10:00 (the scheduled start), on the way since 09:40 (the on-the-way tap), on site since 13:05 (arrival); the date is added when it isn't today.
• Once per job. A job already flagged for something else keeps that flag (it's looked at again once that flag is cleared). After the office clears a not-closed-out flag (DELETE), it is never flagged again for this.
• What goes out: the flag, an attention timeline entry and job.needs_attention with source: "system", by: "closeout", also for a job whose notify is false (notify only controls homeowner texts and emails, never webhooks). No text or email to the homeowner and no push to the tech.

#GET /v1/office/catalog

The company and its active services, the same answer as the public GET /v1/public/{slug} (each service with category), for a caller with a key.

#POST /v1/office/availability

Open start times at an address, the same body and answer as the public POST /v1/public/{slug}/availability, without the per-IP limits, plus:

There is no cap on days for a fine grid, but the answer grows with it: on a busy 8-tech company a 28-day search at stepMinutes: 1 returned about 6,000 starts (400 KB) in under a second, against about 400 at 15. Ask for the days you will show.

Any start it returns, on any grid, holds and books as given: POST /v1/office/holds with its start, or POST /v1/office/jobs with its local (and the same techIds from first-available, if you want those people).

A platform key needs only the read scope for it.

#POST /v1/office/holds

{ serviceId, lat, lng, start }, plus optional leadMinutes (default 0), earliestDay (next_business_day, as on availability) and notify. Rechecks the time under a lock, assigns the best tech(s) and holds it for 5 minutes. Unlike the booking page's holds there is no per-IP cap and no one-hour lead unless you send one; the time just must not have passed. notify: false books the job with no homeowner texts or emails at all, kept when the hold is booked (the default when your platform grant has homeownerMessaging: "off"). Book it with POST /v1/office/jobs { holdId, holdSecret, customer, ... }. Response 201: { "holdId": 1043, "holdSecret": "...", "start": "...", "local": "...", "expiresAt": "...", "notify": true }. Errors: 404 (service), 409 in_the_past, 409 too_soon (inside leadMinutes, or before the next business day with earliestDay), 409 slot_taken.

#Files on a job

Proposals, photos and documents (PDF, JPEG, PNG, HEIC, WebP, plain text, CSV, .docx, .xlsx), up to 20 MB each. Techs on the job see them in the field app (GET /v1/tech/jobs/{id}/attachments). Each upload sends attachment.uploaded.

The attachment object: id, jobId, kind, name, contentType, bytes, status (pending until confirmed, uploaded), uploadedBy ({ kind: "platform" | "user" | "company", id }), createdAt, uploadedAt, url (null until uploaded; the download carries the file's name).

#Sites

A job in CrewLink's API (jobId, bookingId) is one visit: one appointment on the schedule. A site is one property (address) for one client company (or your own work), holding every visit ever made there, forever: the survey, revisits, a visit cancelled and booked again, next year's cleaning. Every visit belongs to one site (siteId on job reads, on the 201/202 of POST /v1/office/jobs, and on every webhook about a job). The office's Jobs page shows one card per site; Dispatch and the field app stay per visit and say "Visit 3 at this site". Nothing about visits changed: their ids, externalRefs and booking.* webhooks mean what they did. Design: data-model.md.

#How visits are grouped

When a visit is created (or, for one booked before sites existed, at its next event or the backfill), it goes to a site by the first rule that fits:

1. siteId sent on POST /v1/office/jobs.
2. The same external id as another visit or a site, on a booking that isn't an import, such as your platform's acme id (one platform job = one site). Per-visit ids never group: a source ending in Visit (acmeVisit) and the old CrewLink's request ids (crewlink-v1); nor do an import's ids (source: "import").
3. The same address and client company. The address is compared by its normalized street line (12 N. Elm Street, Apt 2 = 12 north elm st #2) within 500 m; without an address, within 30 m. The customer doesn't matter (the homeowner can change), and neither does how long ago.
4. Your own work (no client company) goes to the client's site at that address when exactly one client company has a site there; otherwise to your own site.
5. Otherwise a new site.

Two client companies never share a site. A visit of a client placed at an address where your own site already is folds your own site into the client's (site.merged). An external id may be on more than one live visit only when they share a site: a revisit service carrying it joins that site, and any other visit needs siteId (else 409 duplicate_external_ref as before). Per-visit ids are never shared.

#Status

lastVisit and nextVisit say when someone was last there and is next going.

#The site object

People with a team or own scope see the sites that hold one of their visits, and only those visits, and a merged site only when the site it was merged into holds one of their visits (a merged site has no visits of its own); merge, split and PATCH are for everyone else. Platform keys see techs as "First L." (and need write for PATCH, merge and split).

#GET /v1/office/sites

One row per site, each with its visits. Takes every filter of GET /v1/office/jobs except sort (q, jobStatus, tab, status, from/to, filedFrom/filedTo, techId, serviceId, source, clientCompanyId, client): a site is listed when any of its visits matches, and shows all of them. q finds a site by customer name, phone, address, city or any visit's external id; #123 by a visit id. Plus:

Response 200: { "sites": [ <site>, ... ], "nextCursor": "<string or null>", "total": 12 }.

{
  "id": 482,
  "status": "active",
  "address": "1420 W Elm St, Phoenix, AZ 85013",
  "city": "Phoenix",
  "state": "AZ",
  "lat": 33.51,
  "lng": -112.09,
  "customer": { "name": "Pat Quinn", "phone": "+16025550177" },
  "client": { "id": "57f6...", "name": "Globex Solar" },
  "externalRefs": { "acme": "job_7731" },
  "mergedIntoId": null,
  "firstFiledAt": "2026-10-01T15:02:11.000Z",
  "updatedAt": "2026-10-12T15:30:00.000Z",
  "counts": { "visits": 3, "active": 1, "done": 1, "cancelled": 1 },
  "lastVisit": { "jobId": 9120, "at": "2026-10-07T18:40:00.000Z", "service": "Residential Solar Site Survey" },
  "nextVisit": { "jobId": 9188, "start": "2026-10-14T16:00:00.000Z", "service": "Residential Survey Revisit" },
  "visits": [ { "id": 9104, "status": "cancelled", "siteVisit": { "number": null, "of": 2, "revisit": false } }, { "id": 9120, "...": "..." }, { "id": 9188, "...": "..." } ]
}

#GET /v1/office/sites/{id}

The site plus timeline (oldest first) and activity ([{ jobId, photos, texts, messages }]; messages is 0 for platform keys). Each timeline entry is { kind, at, jobId, visit, service, by, tech, text }: kind is requested or booked (each visit filed), en_route, arrived, checkin, done, note, attention, attention_cleared, history_corrected, cancelled, photo, text (a text to the customer), or the site's own site_created, linked (a visit joined, and by which rule), merged, merged_into, split, split_from, refs; visit is the visit's place at the site; by is tech, office, customer or system. A merged site answers with status: "merged", mergedIntoId and no visits. 404 when it isn't yours (or, for a team or own scope, holds none of your visits; a merged site: the site it was merged into holds none).

#PATCH /v1/office/sites/{id}

{ "externalRefs": { "hubspot": "deal-7", "crm": null } }: sets each source's id for the site; null removes it; other sources stay. Audited (refs on the timeline); sends site.updated. 200 with the site; 409 already_merged on a merged site.

#POST /v1/office/sites/{id}/merge

{ "fromSiteId": 481 }: every visit of site 481 moves to this one (the survivor), their ids join this site's (this site's win when both have the same source), and 481 is kept with status: "merged" and mergedIntoId (so GET /v1/office/sites/481 still answers, and siteId: 481 on a new visit lands at the survivor). The same client company, or your own work into a client's site (it keeps the client). Audited on both timelines; sends site.updated and site.merged. 200 with the survivor plus mergedSiteId and movedJobIds. Errors: 422 different_client (two client companies, or a client's site into your own work), 422 invalid_request (into itself), 409 already_merged, 404.

#POST /v1/office/sites/{id}/split

{ "jobId": 9188 } takes that visit out of this site to a new site of its own; with "toSiteId": 475 it moves to that site instead (the same client company, or a client's site for your own work; 422 different_client otherwise). 409 only_visit when it is the site's only visit and there's no toSiteId. When the last visit moves out, this site is kept as merged into toSiteId. Audited on both timelines; sends site.updated for each (site.created for a new one). The backfill never merges a split site back. 200: { "from": <this site, or null when emptied>, "to": <the site it went to> }.