jobs.brief
Everything already on a job, for a read before a visit or a proposal: notes (full text, paged), recordings and private truck notes (marked internal), photos and videos, this job's quotes and invoices, texts, calls (owner or office) and emails, other jobs at the same property, equipment, daily logs, open tasks, and similar past quotes. Pass visit_id when the read is for one visit. notes_cursor and media_cursor fetch the next page. Read only. Prices show only to people who can see prices. Nothing is sent.
| |
|---|
| Who | Agents can call this |
| REST | GET /v1/jobs/brief |
| MCP tool | jobs_brief |
| Writes | no |
| Area | Shop |
When to use it
Everything already on a job, for a read before a visit or a proposal: notes (full text, paged), recordings and private truck notes (marked internal), photos and videos, this job's quotes and invoices, texts, calls (owner or office) and emails, other jobs at the same property, equipment, daily logs, open tasks, and similar past quotes. Pass visit_id when the read is for one visit.
What to tell the owner
Tell them what you found in plain words. Don't read back raw fields.
| Field | Type | Required |
|---|
job_id | string (uuid) | yes |
visit_id | string (uuid) | no |
notes_cursor | string | no |
media_cursor | string | no |
Example
GET https://doingwork.work/v1/jobs/brief?job_id=00000000-0000-4000-8000-000000000000
Output
| Field | Type | Always there |
|---|
job | object | yes |
job.job_id | string (uuid) | yes |
job.summary | ['string', 'null'] | yes |
job.status | string | yes |
job.customer_id | ['string', 'null', ' ', '(', 'u', 'u', 'i', 'd', ')'] | yes |
job.customer_name | ['string', 'null'] | yes |
job.address | ['string', 'null'] | yes |
visit | ['object', '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 |
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 |
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 |
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 |
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 |
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 |
{
"job": {
"job_id": "00000000-0000-4000-8000-000000000000",
"summary": "...",
"status": "...",
"customer_id": "00000000-0000-4000-8000-000000000000",
"customer_name": "...",
"address": "..."
},
"visit": "...",
"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": "..."
}
],
"messages": [
{
"at": "...",
"direction": "...",
"channel": "...",
"customer_text": "...",
"shop_text": "..."
}
],
"calls": [
{
"at": "...",
"direction": "...",
"duration_s": "...",
"summary": "..."
}
],
"emails": [
{
"at": "...",
"channel": "...",
"kind": "...",
"subject": "...",
"body": "..."
}
],
"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": "..."
}
],
"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": "..."
}
]
}
],
"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. |