Tours API
Tours in the Broker & Agent API: list showing tours; plan a tour; get a tour; change a tour; add a stop; put the stops in a new
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List showing tours:
GET /tours - Plan a tour:
POST /tours - Get a tour:
GET /tours/{id} - Change a tour:
PATCH /tours/{id} - Add a stop:
POST /tours/{id}/stops - Put the stops in a new order:
PATCH /tours/{id}/stops - Change a stop, or mark it shown:
PATCH /tours/{id}/stops/{stopId} - Remove a stop:
DELETE /tours/{id}/stops/{stopId}
List showing tours#
GET /tours
Newest first; a tour with a client follows the client’s sight rule. Pass limit to page; without it the answer
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
limit |
query | integer | How many to answer with, 1 to 200; without it, all of them. |
cursor |
query | string or null | The nextCursor of the page before; absent for the first page. Cut to 200 characters. |
curl https://workspace.brokerandagent.com/api/public/v1/tours \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
Tours with their stops. | { tours: array of Tour, nextCursor: string or null } |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Plan a tour#
POST /tours
Without a title it reads “Tour with
Scope: crm.write · Role:
Body
| Field | Type | |
|---|---|---|
contactId |
string or null | Cut to 64 characters. |
title |
string or null | Cut to 200 characters. |
date |
string or null |
curl -X POST https://workspace.brokerandagent.com/api/public/v1/tours \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"contactId":"ct_…","title":"Call Dana back"}'Responses
| Status | Returns | |
|---|---|---|
201 |
The tour. | { tour: Tour } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
409 |
A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Get a tour#
GET /tours/{id}
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
curl https://workspace.brokerandagent.com/api/public/v1/tours/ID \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
The tour. | { tour: Tour } |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Change a tour#
PATCH /tours/{id}
Relink the client (null unlinks), rename it, mark it done or move its day. An absent field
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
contactId |
string or null | Cut to 64 characters. |
title |
string or null | Cut to 200 characters. |
status |
planned, done |
An unknown value is ignored, not refused. |
date |
string or null |
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/tours/ID \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"contactId":"ct_…","title":"Call Dana back"}'Responses
| Status | Returns | |
|---|---|---|
200 |
The tour. | { tour: Tour } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Add a stop#
POST /tours/{id}/stops
Without lat and lng the address is looked up for the map; a miss leaves the stop
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
note |
string or null | Cut to 2000 characters. |
time |
string or null | Cut to 40 characters. |
price |
number | An unknown value is ignored, not refused. |
beds |
number | An unknown value is ignored, not refused. |
baths |
number | An unknown value is ignored, not refused. |
sqft |
number | An unknown value is ignored, not refused. |
listingUrl |
string or null | Cut to 2000 characters. |
address (required) |
string | Cut to 300 characters. |
lat |
number | An unknown value is ignored, not refused. |
lng |
number | An unknown value is ignored, not refused. |
curl -X POST https://workspace.brokerandagent.com/api/public/v1/tours/ID/stops \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"address":"41 Oak St, Kansas City, MO"}'Responses
| Status | Returns | |
|---|---|---|
201 |
The tour, with the stop at the end. | { tour: Tour } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
409 |
A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Put the stops in a new order#
PATCH /tours/{id}/stops
Stops not listed keep their order after
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
orderedIds (required) |
array of string |
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/tours/ID/stops \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"orderedIds":["stop_…","stop_…"]}'Responses
| Status | Returns | |
|---|---|---|
200 |
The tour. | { tour: Tour } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Change a stop, or mark it shown#
PATCH /tours/{id}/stops/{stopId}
Marking a stop shown logs the showing on the client’s timeline. A stop’s address and place in the order
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string | |
stopId (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
note |
string or null | Cut to 2000 characters. |
time |
string or null | Cut to 40 characters. |
price |
number | An unknown value is ignored, not refused. |
beds |
number | An unknown value is ignored, not refused. |
baths |
number | An unknown value is ignored, not refused. |
sqft |
number | An unknown value is ignored, not refused. |
listingUrl |
string or null | Cut to 2000 characters. |
shown |
boolean |
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/tours/ID/stops/STOPID \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"note":"…","time":"…"}'Responses
| Status | Returns | |
|---|---|---|
200 |
The tour. | { tour: Tour } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Remove a stop#
DELETE /tours/{id}/stops/{stopId}
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string | |
stopId (required) |
path | string |
curl -X DELETE https://workspace.brokerandagent.com/api/public/v1/tours/ID/stops/STOPID \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
The tour. | { tour: Tour } |
202 |
Held for the person to approve in the app: the connection asks before sending or deleting. Nothing has run yet. | { proposal: object } |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Something missing or wrong? Email support@brokerandagent.com and