Crisphive

View saved version →

---
name: crisphive-book-job
description: Book a field-service job end-to-end with Crisphive — find or create the customer, check real availability windows, create the booking, quote the work, and confirm an exact appointment slot with automatic technician assignment. Use whenever the user wants to schedule, book, or arrange a service visit, repair, installation, or maintenance job for a customer.
---

# Book a field-service job with Crisphive

You are driving a deterministic scheduling engine. Follow the steps in order —
each step feeds the next. A job cannot be confirmed before it is quoted.

Every tool returns the envelope `{"error_code": 0 | "CODE", "message": "…",
"data": {…}}`. `error_code` 0 = success; otherwise it is a stable string
explaining the failure — read it before retrying.

## Environments: sandbox vs production

This skill works identically in BOTH environments — same tools, same fields,
same responses. The credential decides which one you are in:

- **Sandbox** — API key starting `chsk_test_`, or an OAuth connection the
  business owner authorized while their dashboard was in sandbox mode. All
  data is an isolated test copy: bookings here never reach a real customer
  and send no real notifications. Use it to experiment freely and to rehearse
  a flow before running it live.
- **Production** — API key starting `chsk_live_`, or an OAuth connection
  authorized from a live dashboard session. Every step below creates or
  changes REAL business data, and a confirmed booking schedules a REAL
  technician visit and notifies a REAL customer.

You cannot switch environments with a parameter; reconnect with the other
credential. **In production, recap the details and get the user's explicit
go-ahead before step 5 (`confirmJobRequest`).**

## 1. Resolve the customer

- Search first: `listCustomers` with the `q` filter (matches name, phone,
  email). Reuse the existing customer's `id` if found.
- Otherwise `createCustomer`. **Include the street address AND
  `address.latitude`/`address.longitude`** — the engine needs coordinates to
  compute travel times and match service areas; an address string alone is
  stored but NOT geocoded server-side. Use coordinates you know with
  confidence for the stated address, or confirm the location with the user.
  Pass an `idempotency_key` so a retried create never duplicates.

## 2. Check real availability windows

- `listJobRequestBookingWindows` with `x_timezone` = the CUSTOMER's IANA
  timezone (e.g. `America/Toronto`). Never invent windows.
- The response is a grid of days × periods (`morning` / `afternoon` /
  `evening`). These are *preference windows*, not exact appointment times.
- Offer the user only windows present in the response.

## 3. Create the booking

- `createJobRequest` with `customer_id` and `job_dates` — an array of
  `{date: "YYYY-MM-DD", periods: [{period: "morning"}]}` picked in step 2.
- Optional: `job_type_id` (discover via `listJobTypes`), `skill_ids`
  (discover via `listSkills`) when the user described the kind of work, and
  `description` (free text). Pass an `idempotency_key`.
- Do not set `priority` unless the job is genuinely urgent (see the
  crisphive-emergency-dispatch skill); omitted bookings get the business's
  default priority.

## 4. Quote the work

- `quoteJobRequest` with `job_duration_minutes` (on-site work time) plus
  `mobilization_minutes` / `demobilization_minutes` (travel/setup before and
  after). If the user gave no durations, propose sensible ones and confirm
  with the user before quoting.
- Quotes are time bundles only — Crisphive job requests carry NO prices,
  amounts, or currency. Never invent monetary fields.

## 5. Confirm an exact slot

- The confirm API needs an exact start time, not a window. Fetch the exact
  bookable start times with `listMatchingSlots` (optional `step_minutes`,
  default 30), then call `confirmJobRequest` with:
  - `scheduled_at` — the chosen slot's business-local naive datetime
    (`2026-08-04T09:00:00`, NO timezone offset — take the
    `business_time.datetime` value from the slot response verbatim).
  - `status_version` — echo the value from your last `getJobRequest` read to
    fence against concurrent edits (optional but recommended).
  - `technician_id` — ONLY when the user explicitly demands a specific
    person; otherwise omit it and the matching engine auto-assigns the best
    technician by skills, travel time, and availability.
- Pass an `idempotency_key`.

## 6. Verify and report

- Read back with `getJobRequest` / `getJobRequestTimeline`: assigned
  technician, arrival window, scheduled start/end, and the next workflow
  action. Summarize these for the user.

## Recovering from errors

- `JOB_REQUEST_NO_TECHNICIAN_AVAILABLE` on confirm: that exact time has no
  feasible technician. Re-run `listMatchingSlots` and offer the nearest
  alternatives — do not retry the same time.
- Empty booking windows / empty slots: the business may have no technicians
  with availability in that service area. Say so instead of inventing times.
- `JOB_REQUEST_STAGE_CONFLICT` (409): someone changed the job concurrently —
  re-read with `getJobRequest` and redo the step with the fresh
  `status_version`.
- `IDEMPOTENCY_KEY_REUSE` (422): you reused a key with a different body —
  generate a fresh key.

View saved version →

---
name: crisphive-emergency-dispatch
description: Handle urgent field-service work with Crisphive — raise a job's priority, find emergency-capable technicians ranked by ETA, and preview then commit a cascade reschedule that safely pushes lower-priority appointments to make room. Use when the user reports an emergency, an urgent job, an SLA at risk, or asks to move or reshuffle scheduled jobs.
---

# Emergency dispatch & rescheduling with Crisphive

Crisphive schedules by a four-level priority model: `p0` (emergency,
interrupt-driven) > `p1` (top, may carry an SLA deadline) > `p2` (standard,
the default) > `p3` (deferrable). Only a `p0` may displace other jobs.

All `start_at` / `sla_deadline` values below are BUSINESS-LOCAL naive
datetimes (`2026-08-04T14:00:00`, no timezone offset) and must be in the
future.

## Environments: sandbox vs production

This skill works identically in BOTH environments — same tools, same fields,
same responses. The credential decides which one you are in:

- **Sandbox** — API key `chsk_test_…`, or an OAuth connection authorized from
  a sandbox dashboard session. Displacements here move only isolated test
  data and notify nobody. Rehearse an emergency flow here first when
  possible.
- **Production** — API key `chsk_live_…`, or an OAuth connection authorized
  from a live session. A committed cascade MOVES REAL customers'
  appointments and the platform notifies them immediately.

You cannot switch environments with a parameter; reconnect with the other
credential. **In production, never call `commitEmergencyReschedule` or
`commitJobRequestMove` without showing the user the full preview (every
displaced job) and getting explicit approval.**

## Raising priority

- `updateJobPriority` with `priority` (required) and optional `note`.
  Escalate to `p0` only for true emergencies (safety issue, no heat in
  winter, active leak) — `p0` work is allowed to push other customers.
- For urgent-but-not-emergency work use `p1`, optionally with `sla_deadline`
  to arm automatic escalation as breach risk grows.

## The emergency insert flow (ALWAYS preview before commit)

1. **Candidates** — `listEmergencyCandidates` with `emergency_job_id`,
   `mode`, and the desired `start_at`. `mode` is the cascade style the
   preview assumes: `overtime` (displaced jobs stay same-day; the technician
   works late) or `next_day` (overflow rolls to the next working day).
   Returns technicians ranked by ETA with per-candidate feasibility.
2. **Preview** — `previewEmergencyReschedule` with the SAME
   `emergency_job_id`/`mode`/`start_at` plus the chosen `technician_id`.
   Optional `displacement_mode`: `reschedule` (default — displaced jobs move
   to new times) or `reassign` (displaced jobs keep their times on alternate
   technicians when possible). **Nothing is persisted by a preview.** The
   response lists exactly which jobs move and to when.
3. **Approve** — show the user the emergency slot AND every displaced job.
   Get explicit approval.
4. **Commit** — `commitEmergencyReschedule` with the SAME
   `emergency_job_id`/`mode`/`start_at`/`technician_id`/`displacement_mode`
   as the preview, plus:
   - `expected_move_ids`: echo the displaced job IDs the preview returned
     (both `days[].moves[].job_id` and `reassignments[].job_id`) — the commit
     fails safe if the schedule drifted since the preview.
   - `emergency_expected_version`: the previewed job's version fence.
   - An `idempotency_key`.
   Displaced customers are notified automatically by the platform — do not
   message them yourself.

## Moving a single job (dispatch-board move)

- `previewJobRequestMove` with the job `id`, `start_at`, `technician_id`
  (the target technician — pass the current one for a time-only move) and
  `mode` (`overtime` | `next_day`, for any jobs the move displaces). Read the
  hard blocks and warnings it returns.
- Then `commitJobRequestMove` with the same fields plus `expected_move_ids` /
  `expected_version` from the preview and an `idempotency_key`. Never commit
  a move that was not previewed.
- Landing on an occupied slot or in the past is rejected — offer the
  preview's alternatives instead.

## Constraints the engine enforces (do not fight them)

- Multi-day jobs and multi-person crew jobs are frozen anchors for the
  emergency cascade — they are never pushed, and a crew job cannot itself be
  the emergency insert (the API rejects it).
- In-progress jobs (the technician already started) cannot be moved.
- Version fences (`expected_version` / `emergency_expected_version` /
  `expected_move_ids`) exist to catch concurrent edits: on a conflict,
  re-read with `getJobRequest`, re-preview, and try again — never bypass by
  omitting them after a conflict.

## Reporting back

After any commit, read `getJobRequestTimeline` for the emergency job and
summarize: who is coming, when, and which other appointments moved. In live
mode remind the user that affected customers have been notified
automatically.

View saved version →

---
name: crisphive-roster-sync
description: Manage a field-operations team in Crisphive — create, update, and remove technicians and keep their skills, service areas, crew relations (leads/buddies), and vehicles in sync, e.g. when onboarding staff or syncing from an HR system. Use when the user wants to add or remove a technician, change someone's skills or coverage area, or set up who works with whom.
---

# Manage the technician roster with Crisphive

The technician roster feeds the scheduling engine directly: skills, service
areas, start locations and crew relations all change who gets matched to
which job. Keep them accurate.

## Environments: sandbox vs production

This skill works identically in BOTH environments — same tools, same fields,
same responses. The credential decides which one you are in:

- **Sandbox** — API key `chsk_test_…`, or an OAuth connection authorized from
  a sandbox dashboard session. The sandbox has its OWN isolated roster: test
  technicians here never appear in the live team and receive no
  notifications. One extra rule applies: Owner/Administrator role groups
  cannot be created in sandbox (operational roles like Technician work
  everywhere).
- **Production** — API key `chsk_live_…`, or an OAuth connection authorized
  from a live session. Creating a member with an email/phone sends them a
  real "you've been added" notification, and roster changes immediately
  affect real job matching. Create real people only, and confirm removals
  with the user before calling `deleteTechnician`.

You cannot switch environments with a parameter; reconnect with the other
credential.

## Creating a technician

`createTechnician` — required fields:

- `business_group_id` — the role group (Technician, Supervisor, …).
  **Group IDs are not discoverable through this API**; the business copies
  them from the Crisphive dashboard (Settings → Permissions). Ask the user
  for it if you don't have one from an earlier call in this conversation.
- `full_name`.
- At least one of `email` / `phone`. Phone numbers are validated as REAL
  E.164 numbers (libphonenumber: real dial code + per-country pattern) —
  placeholder numbers are rejected with `PHONE_INVALID`. If neither contact
  is valid you get `TECHNICIAN_CONTACT_REQUIRED`.

Strongly recommended at create time:

- `assignment_tier` — how the crew matcher treats them: `lead` (can head a
  job), `buddy` (crew helper), `float` (excluded from auto crew-assign).
- `start_location_type` (`home` | `office`) **plus explicit
  `start_location_lat` / `start_location_long`** — the engine computes travel
  times from this point. Note: choosing `office` snapshots the business
  location at creation time; set the coordinates explicitly to be safe.
- `service_area_ids` — which geographic areas they cover (discover via
  `listServiceAreas`). A technician with no service area is never matched.
- `buddy_ids` (when creating a lead) or `lead_ids` (when creating a buddy) —
  see crew relations below.

No invite email is sent; sign-in is passwordless and handled by the platform
later.

## Keeping attributes in sync

- Skills: `replaceTechnicianSkills` (PATCH, replace-semantics — send the FULL
  list; `[]` clears). Discover skill IDs via `listSkills` /
  `listSkillCategories`. Skills matter twice: as a hard filter when a job
  demands them and as a soft ranking signal.
- Service areas: `replaceTechnicianServiceAreas` (replace-semantics).
- Vehicles: `replaceTechnicianVehicles` — the vehicles this technician can
  use (discover via `listVehicles`). Vehicle-to-tech links are edited only
  from the technician side.
- Profile fields: `updateTechnician` is a FULL replace — read the current
  record with `getTechnician` first and send every field back, changing only
  what the user asked for.

## Crew relations (leads & buddies)

- The relation is DIRECTIONAL and owned by the lead: a lead's `buddy_ids`
  lists who can crew under them. `replaceTechnicianBuddies` edits a lead's
  list (replace-semantics; self-buddy is rejected).
- `replaceTechnicianLeads` is the buddy-side write of the SAME relation — it
  adds/removes this technician in the named leads' buddy lists.
- Buddies matter for multi-person jobs: the matcher prefers a lead's own
  buddies when building a crew.

## Removing a technician

- `deleteTechnician` removes them from the active roster and automatically
  scrubs references (buddy lists, vehicle ownership). It is a soft delete
  server-side, but treat it as destructive: confirm with the user first.
- Suspending rather than removing (status changes) is a dashboard operation,
  not available through this API.

## Verifying

`listTechnicians` / `getTechnician` embed the synced state: skills, service
areas, buddies/leads, vehicles, tier, start location. After a batch of
changes, read back and summarize what changed.