# 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.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [List showing tours](#list-showing-tours): `GET /tours`
- [Plan a tour](#plan-a-tour): `POST /tours`
- [Get a tour](#get-a-tour): `GET /tours/{id}`
- [Change a tour](#change-a-tour): `PATCH /tours/{id}`
- [Add a stop](#add-a-stop): `POST /tours/{id}/stops`
- [Put the stops in a new order](#put-the-stops-in-a-new-order): `PATCH /tours/{id}/stops`
- [Change a stop, or mark it shown](#change-a-stop-or-mark-it-shown): `PATCH /tours/{id}/stops/{stopId}`
- [Remove a stop](#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 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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 <client>".

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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
curl https://workspace.brokerandagent.com/api/public/v1/tours/ID \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The tour. | { `tour`: [Tour](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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). |  |

---

Source: https://brokerandagent.com/developers/api/reference/tours
