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 order; and more.

Generated from the product on Nov 17, 2026

Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.

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 is every tour.

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.
Shell
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: agent or above

Body

Field Type
contactId string or null Cut to 64 characters.
title string or null Cut to 200 characters.
date string or null
Shell
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
Shell
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 is left alone.

Scope: crm.write · Role: agent or above

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
Shell
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 without a pin.

Scope: crm.write · Role: agent or above

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.
Shell
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 the listed ones.

Scope: crm.write · Role: agent or above

Parameters

Name In Type
id (required) path string

Body

Field Type
orderedIds (required) array of string
Shell
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 don’t change here.

Scope: crm.write · Role: agent or above

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
Shell
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: agent or above

Parameters

Name In Type
id (required) path string
stopId (required) path string
Shell
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 we’ll fix it.