---
title: dispatch.suggest | Doing Work API
description: Read only: for an urgent or emergency visit, the shop's field workers and owners ranked by who is free (no overlapping visit, not on time off, inside their
url: https://doingwork.work/docs/reference/dispatch-suggest/
---

# dispatch.suggest

Read only: for an urgent or emergency visit, the shop's field workers and owners ranked by who is free (no overlapping visit, not on time off, inside their hours) and then by the fewest visits that day. Suggestions only; assign with visits.assign.

|  |  |
|---|---|
| Who | Agents can call this |
| REST | `GET /v1/dispatch/suggest` |
| MCP tool | `dispatch_suggest` |
| Writes | no |
| Area | [Shop](https://doingwork.work/docs/reference/#shop) |

## When to use it

Read only: for an urgent or emergency visit, the shop's field workers and owners ranked by who is free (no overlapping visit, not on time off, inside their hours) and then by the fewest visits that day. Suggestions only; assign with visits.assign.

## What to tell the owner

Tell them what you found in plain words. Don't read back raw fields.

## Input

| Field | Type | Required |
|---|---|---|
| `visit_id` | string (uuid) | yes |
| `limit` | integer | no |

## Example

```http
GET https://doingwork.work/v1/dispatch/suggest?visit_id=00000000-0000-4000-8000-000000000000
```

## Output

| Field | Type | Always there |
|---|---|---|
| `visit_id` | string (uuid) | yes |
| `priority` | string | yes |
| `starts_at` | string (date-time) | yes |
| `ends_at` | string (date-time) | yes |
| `assignee_ids` | array | yes |
| `candidates` | array | yes |
| `candidates[].person_id` | string (uuid) | yes |
| `candidates[].display_name` | ['string', 'null'] | yes |
| `candidates[].role` | string | yes |
| `candidates[].free` | boolean | yes |
| `candidates[].conflicts` | integer | yes |
| `candidates[].time_off` | boolean | yes |
| `candidates[].outside_hours` | boolean | yes |
| `candidates[].visits_that_day` | integer | yes |
| `candidates[].already_assigned` | boolean | yes |

```json
{
  "visit_id": "00000000-0000-4000-8000-000000000000",
  "priority": "...",
  "starts_at": "...",
  "ends_at": "...",
  "assignee_ids": [
    "00000000-0000-4000-8000-000000000000"
  ],
  "candidates": [
    {
      "person_id": "00000000-0000-4000-8000-000000000000",
      "display_name": "...",
      "role": "...",
      "free": true,
      "conflicts": 1,
      "time_off": true,
      "outside_hours": true,
      "visits_that_day": 1,
      "already_assigned": true
    }
  ]
}
```

## Errors

| Code | Status | What to do |
|---|---|---|
| `invalid_input`, `invalid_token`, `rate_limited` |  | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |