Creates the job, quotes it (job_duration_minutes, or the job type's default_duration_minutes) and confirms it at scheduled_at on the customer's behalf — the dashboard's "book for a caller" in a single request, built for voice agents and automation platforms that cannot run create → quote → slots → confirm.
Customer: send `customer_id`, or `customer` (+ `address`) to match-or-create by phone/email — a caller who already exists is matched, never duplicated. Find a caller first with listCustomers?phone=.
Every input is validated BEFORE anything is written (time and business timezone, future start, a duration or a job-type default, active job type, phone format); those failures are ordinary 4xx and create nothing.
⚠️ Once the job is created it is never discarded, and the call answers 200 even if scheduling then fails: `confirmed: false` with `refusal` (stage + the exact error_code/data the quote or confirm endpoint would have returned, e.g. JOB_REQUEST_NO_TECHNICIAN_AVAILABLE with blockers). The job is then quoted and waiting in the coordinator's queue — tell the caller the office will confirm a time. Retry with the SAME Idempotency-Key to replay the result; a new key books a second job.
인수
Idempotency-Keystringheader선택
Makes retries safe: a repeat send with the same key returns the original result instead of booking again
▾addressobjectbody선택
Service address. REQUIRED with `customer`; ignored with `customer_id` (the stored customer address is used). Missing coordinates are geocoded.
citystringbody선택
countrystringbody선택
formattedstringbody선택
latitudenumberbody선택
linestringbody선택
line2stringbody선택
longitudenumberbody선택
postal_codestringbody선택
statestringbody선택
▾customerobjectbody선택
A caller who may or may not exist yet: matched by phone/email against the business's customers (no duplicate is created for a known caller), created otherwise. Send this OR `customer_id`.
emailstringbody선택
Email. Phone or email is required.
full_namestringbody선택
Customer's full name. Required with `customer`.
phonestringbody선택
Phone in E.164 with the leading + (e.g. +16135550142); separators are stripped. A bare national number is refused with PHONE_INVALID. Phone or email is required.
sms_opt_inbooleanbody선택
Record SMS consent ONLY if the caller explicitly agreed to texts (a voice agent must ask). Without it the customer gets email, never SMS.
customer_idstringbody선택
UUID of an existing customer. Send this OR `customer`, not both.
descriptionstringbody선택
Free-text description of the work. Optional; max 2000 chars.
job_duration_minutesintegerbody선택
Hands-on work minutes. Optional when the job type has a default_duration_minutes.
job_type_idstringbody선택
UUID of the job type: it classifies the job and supplies default_duration_minutes when job_duration_minutes is omitted. Optional: omitted, the business's DEFAULT job type (is_default, the seeded "General", 60 min + 15 + 15 unless the business changed it) is used.
priorityenumbody선택
Scheduling priority p0–p3. Optional; omitted = the business default.
scheduled_atstringbody선택
Start time — a BUSINESS-LOCAL wall clock, same rule as confirmJobRequest: canonical `2026-09-30T10:00:00`, seconds optional, a space may replace the T; an offset is accepted only when it agrees with the business timezone. Must be in the future.
skill_idsarray<string>body선택
UUIDs of skills the work needs. Optional; up to 20.
technician_idstringbody선택
Force a specific lead technician (feasibility still enforced). Omit to let Crisphive pick.
