الحجوزات›Book, schedule and confirm a job in one call
Book, schedule and confirm a job in one call
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.
