--- title: schedule.findTime | Doing Work API description: Find open times for a visit of a given length; each slot has starts_at in UTC plus local shop time and tz (for example local 2026-11-10 8:00 AM, tz. url: https://doingwork.work/docs/reference/schedule-findtime/ --- # schedule.findTime Find open times for a visit of a given length; each slot has starts_at in UTC plus local shop time and tz (for example local 2026-11-10 8:00 AM, tz America/Boise). Looks inside shop hours (or Monday to Friday 08:00 to 17:00 when none are set), skips worker time off and times outside a worker's own hours, and keeps the shop's travel buffer clear around booked visits. Give person_ids or a saved crew_id (or both) to check those workers (together: all of them free at once, the default; or any one of them). Leave it out to check every worker in the shop and get back who is free. A lead can check the crews they belong to or lead. Field workers can only check themselves. Nothing is booked; call visits.create with a slot. | | | |---|---| | Who | Agents can call this | | REST | `POST /v1/schedule/find-time` | | MCP tool | `schedule_findTime` | | Writes | no | | Area | [Scheduling and visits](https://doingwork.work/docs/reference/#scheduling-and-visits) | ## When to use it Find open times for a visit of a given length; each slot has starts_at in UTC plus local shop time and tz (for example local 2026-11-10 8:00 AM, tz America/Boise). Looks inside shop hours (or Monday to Friday 08:00 to 17:00 when none are set), skips worker time off and times outside a worker's own hours, and keeps the shop's travel buffer clear around booked visits. ## What to tell the owner Tell them what you found in plain words. Don't read back raw fields. ## Input | Field | Type | Required | |---|---|---| | `shop_id` | string (uuid) | yes | | `duration_minutes` | integer | yes | | `from` | string (date-time) | no | | `to` | string (date-time) | no | | `person_ids` | array | no | | `crew_id` | string (uuid) | no | | `together` | boolean | no | | `step_minutes` | integer | no | | `limit` | integer | no | ## Example ```http POST https://doingwork.work/v1/schedule/find-time content-type: application/json Idempotency-Key: 3f1c... { "shop_id": "00000000-0000-4000-8000-000000000000", "duration_minutes": 1 } ``` ## Output | Field | Type | Always there | |---|---|---| | `time_zone` | string | yes | | `hours_source` | string (one of shop, default) | yes | | `buffer_minutes` | integer | yes | | `arrival_window_minutes` | integer | no | | `slots` | array | yes | | `slots[].starts_at` | string (date-time) | yes | | `slots[].ends_at` | string (date-time) | yes | | `slots[].arrive_by` | string (date-time) | yes | | `slots[].person_ids` | array | yes | | `slots[].local` | string | yes | | `slots[].tz` | string | yes | ```json { "time_zone": "...", "hours_source": "shop", "buffer_minutes": 1, "slots": [ { "starts_at": "...", "ends_at": "...", "arrive_by": "...", "person_ids": [ "00000000-0000-4000-8000-000000000000" ], "local": "...", "tz": "..." } ] } ``` ## Errors | Code | Status | What to do | |---|---|---| | `invalid_input`, `invalid_token`, `rate_limited` | | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |