--- title: visits.brief | Doing Work API description: One page brief before a visit: the visit and customer, the address, the request it came from, recent texts with the customer (customer words come wrapped as. url: https://doingwork.work/docs/reference/visits-brief/ --- # visits.brief One page brief before a visit: the visit and customer, the address, the request it came from, recent texts with the customer (customer words come wrapped as untrusted text) and calls (owner or office only), emails, notes with their full text and channel, recordings and private truck notes (marked internal), photos and videos with who provided each file (shop or customer) and the channel it arrived on, this job's quotes and invoices, other jobs at the same property, equipment, daily logs, open tasks, and similar past quotes. Notes and media are paged (notes_cursor, media_cursor). Read only. Prices show only to people who can see prices. next_actions suggests what to do at or after the visit. | | | |---|---| | Who | Agents can call this | | REST | `GET /v1/visits/brief` | | MCP tool | `visits_brief` | | Writes | no | | Area | [Scheduling and visits](https://doingwork.work/docs/reference/#scheduling-and-visits) | ## When to use it One page brief before a visit: the visit and customer, the address, the request it came from, recent texts with the customer (customer words come wrapped as untrusted text) and calls (owner or office only), emails, notes with their full text and channel, recordings and private truck notes (marked internal), photos and videos with who provided each file (shop or customer) and the channel it arrived on, this job's quotes and invoices, other jobs at the same property, equipment, daily logs, open tasks, and similar past quotes. Notes and media are paged (notes_cursor, media_cursor). ## 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 | | `notes_cursor` | string | no | | `media_cursor` | string | no | ## Example ```http GET https://doingwork.work/v1/visits/brief?visit_id=00000000-0000-4000-8000-000000000000 ``` ## Output | Field | Type | Always there | |---|---|---| | `visit` | object | yes | | `visit.visit_id` | string (uuid) | yes | | `visit.job_id` | string (uuid) | yes | | `visit.starts_at` | string (date-time) | yes | | `visit.ends_at` | string (date-time) | yes | | `visit.status` | string | yes | | `visit.title` | ['string', 'null'] | yes | | `visit.job_summary` | ['string', 'null'] | yes | | `customer` | object | yes | | `customer.customer_id` | ['string', 'null', ' ', '(', 'u', 'u', 'i', 'd', ')'] | yes | | `customer.name` | ['string', 'null'] | yes | | `customer.phone` | ['string', 'null'] | yes | | `customer.email` | ['string', 'null'] | yes | | `customer.address` | ['string', 'null'] | yes | | `request` | ['object', 'null'] | yes | | `messages` | array | yes | | `messages[].at` | string (date-time) | yes | | `messages[].direction` | string | yes | | `messages[].channel` | string | yes | | `messages[].customer_text` | ['object', 'null'] | yes | | `messages[].shop_text` | ['string', 'null'] | yes | | `calls` | array | yes | | `calls[].at` | string (date-time) | yes | | `calls[].direction` | string | yes | | `calls[].duration_s` | ['integer', 'null'] | yes | | `calls[].summary` | ['string', 'null'] | yes | | `notes` | array | yes | | `notes[].note_id` | string (uuid) | yes | | `notes[].at` | string (date-time) | yes | | `notes[].source` | string | yes | | `notes[].channel` | ['string', 'null'] | yes | | `notes[].pinned` | boolean | yes | | `notes[].body` | string | yes | | `notes_cursor` | ['string', 'null'] | yes | | `media` | array | yes | | `media[].media_id` | string (uuid) | yes | | `media[].kind` | string | yes | | `media[].stage` | string | yes | | `media[].provided_by` | string | yes | | `media[].channel` | string | yes | | `media[].summary` | ['string', 'null'] | yes | | `media[].measurements` | ['array', 'object', 'null'] | yes | | `media_cursor` | ['string', 'null'] | yes | | `recordings` | array | yes | | `recordings[].recording_id` | string (uuid) | yes | | `recordings[].visit_id` | string (uuid) | yes | | `recordings[].described_as` | ['string', 'null'] | yes | | `recordings[].clip_ref` | ['string', 'null'] | yes | | `recordings[].transcript` | ['string', 'null'] | yes | | `recordings[].worker_notes` | ['object', 'null'] | yes | | `quotes` | array | yes | | `quotes[].quote_id` | string (uuid) | yes | | `quotes[].status` | string | yes | | `quotes[].historical` | boolean | yes | | `quotes[].total_minor` | ['integer', 'null'] | yes | | `invoices` | array | yes | | `invoices[].invoice_id` | string (uuid) | yes | | `invoices[].status` | string | yes | | `invoices[].total_minor` | ['integer', 'null'] | yes | | `other_jobs` | array | yes | | `other_jobs[].job_id` | string (uuid) | yes | | `other_jobs[].summary` | ['string', 'null'] | yes | | `other_jobs[].status` | string | yes | | `equipment` | array | yes | | `equipment[].equipment_id` | string (uuid) | yes | | `equipment[].kind` | string | yes | | `equipment[].make` | ['string', 'null'] | yes | | `equipment[].model` | ['string', 'null'] | yes | | `equipment[].serial` | ['string', 'null'] | yes | | `daily_logs` | array | yes | | `daily_logs[].log_id` | string (uuid) | yes | | `daily_logs[].log_date` | string | yes | | `daily_logs[].body` | string | yes | | `emails` | array | yes | | `emails[].at` | string (date-time) | yes | | `emails[].channel` | string | yes | | `emails[].kind` | string | yes | | `emails[].subject` | string | yes | | `emails[].body` | string | yes | | `open_tasks` | array | yes | | `open_tasks[].task_id` | string (uuid) | yes | | `open_tasks[].title` | string | yes | | `open_tasks[].due_at` | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | yes | | `similar_quotes` | array | yes | | `similar_quotes[].quote_id` | string (uuid) | yes | | `similar_quotes[].job_id` | string (uuid) | yes | | `similar_quotes[].status` | string | yes | | `similar_quotes[].created_at` | string (date-time) | yes | | `similar_quotes[].job_summary` | ['string', 'null'] | yes | | `similar_quotes[].customer_name` | ['string', 'null'] | yes | | `similar_quotes[].total_minor` | ['integer', 'null'] | yes | | `similar_quotes[].matched` | array | yes | | `similar_quotes[].lines` | array | yes | | `similar_quotes[].lines[].description` | string | yes | | `similar_quotes[].lines[].quantity` | number | yes | | `similar_quotes[].lines[].unit_price_minor` | ['integer', 'null'] | yes | | `has_quote` | boolean | yes | | `next_actions` | array | yes | | `next_actions[].say` | string | yes | | `next_actions[].op` | ['string', 'null'] | yes | | `next_actions[].when` | string (one of now, later, check, tell_human) | yes | | `next_actions[].due_at` | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | no | | `next_actions[].args_hint` | string | no | ```json { "visit": { "visit_id": "00000000-0000-4000-8000-000000000000", "job_id": "00000000-0000-4000-8000-000000000000", "starts_at": "...", "ends_at": "...", "status": "...", "title": "...", "job_summary": "..." }, "customer": { "customer_id": "00000000-0000-4000-8000-000000000000", "name": "Ruiz Plumbing", "phone": "...", "email": "owner@example.com", "address": "..." }, "request": "...", "messages": [ { "at": "...", "direction": "...", "channel": "...", "customer_text": "...", "shop_text": "..." } ], "calls": [ { "at": "...", "direction": "...", "duration_s": "...", "summary": "..." } ], "notes": [ { "note_id": "00000000-0000-4000-8000-000000000000", "at": "...", "source": "...", "channel": "...", "pinned": true, "body": "..." } ], "notes_cursor": "...", "media": [ { "media_id": "00000000-0000-4000-8000-000000000000", "kind": "...", "stage": "...", "provided_by": "...", "channel": "...", "summary": "...", "measurements": "..." } ], "media_cursor": "...", "recordings": [ { "recording_id": "00000000-0000-4000-8000-000000000000", "visit_id": "00000000-0000-4000-8000-000000000000", "described_as": "...", "clip_ref": "...", "transcript": "...", "worker_notes": "..." } ], "quotes": [ { "quote_id": "00000000-0000-4000-8000-000000000000", "status": "...", "historical": true, "total_minor": "..." } ], "invoices": [ { "invoice_id": "00000000-0000-4000-8000-000000000000", "status": "...", "total_minor": "..." } ], "other_jobs": [ { "job_id": "00000000-0000-4000-8000-000000000000", "summary": "...", "status": "..." } ], "equipment": [ { "equipment_id": "00000000-0000-4000-8000-000000000000", "kind": "...", "make": "...", "model": "...", "serial": "..." } ], "daily_logs": [ { "log_id": "00000000-0000-4000-8000-000000000000", "log_date": "...", "body": "..." } ], "emails": [ { "at": "...", "channel": "...", "kind": "...", "subject": "...", "body": "..." } ], "open_tasks": [ { "task_id": "00000000-0000-4000-8000-000000000000", "title": "...", "due_at": "..." } ], "similar_quotes": [ { "quote_id": "00000000-0000-4000-8000-000000000000", "job_id": "00000000-0000-4000-8000-000000000000", "status": "...", "created_at": "...", "job_summary": "...", "customer_name": "...", "total_minor": "...", "matched": [ "..." ], "lines": [ { "description": "40 gallon gas heater, installed", "quantity": "...", "unit_price_minor": "..." } ] } ], "has_quote": true, "next_actions": [ { "say": "...", "op": "...", "when": "now" } ] } ``` ## Errors | Code | Status | What to do | |---|---|---| | `invalid_input`, `invalid_token`, `rate_limited` | | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |