customers.search
Find customers by name, company, email, phone or property address.
| |
|---|
| Who | Agents can call this |
| REST | GET /v1/customers/search |
| MCP tool | customers_search |
| Writes | no |
| Area | Shop |
When to use it
Find customers by name, company, email, phone or property address.
What to tell the owner
Tell them what you found in plain words. Don't read back raw fields.
| Field | Type | Required |
|---|
shop_id | string (uuid) | yes |
q | string | yes |
include_archived | boolean | no |
limit | integer | no |
Example
GET https://doingwork.work/v1/customers/search?shop_id=00000000-0000-4000-8000-000000000000&q=...
Output
| Field | Type | Always there |
|---|
data | array | yes |
data[].customer_id | string (uuid) | yes |
data[].shop_id | string (uuid) | yes |
data[].kind | string | yes |
data[].name | string | yes |
data[].company_name | ['string', 'null'] | yes |
data[].email | ['string', 'null'] | yes |
data[].phone | ['string', 'null'] | yes |
data[].billing_address | ['object', 'null'] | yes |
data[].lead_source | ['string', 'null'] | yes |
data[].tags | array | yes |
data[].notes | ['string', 'null'] | yes |
data[].archived_at | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | yes |
data[].merged_into | ['string', 'null', ' ', '(', 'u', 'u', 'i', 'd', ')'] | yes |
data[].erased_at | ['string', 'null', ' ', '(', 'd', 'a', 't', 'e', '-', 't', 'i', 'm', 'e', ')'] | yes |
data[].created_at | string (date-time) | yes |
data[].updated_at | string (date-time) | yes |
{
"data": [
{
"customer_id": "00000000-0000-4000-8000-000000000000",
"shop_id": "00000000-0000-4000-8000-000000000000",
"kind": "...",
"name": "Ruiz Plumbing",
"company_name": "...",
"email": "owner@example.com",
"phone": "...",
"billing_address": "...",
"lead_source": "...",
"tags": [
"..."
],
"notes": "...",
"archived_at": "...",
"merged_into": "00000000-0000-4000-8000-000000000000",
"erased_at": "...",
"created_at": "...",
"updated_at": "..."
}
]
}
Errors
| Code | Status | What to do |
|---|
invalid_input, invalid_token, rate_limited | | Can happen on any call. See errors. |