Back to top

API Documentation

Tours

Overview

A Tour is a dedicated CRM entity used to schedule and track property tours. Every Tour is linked one-to-one to a Tour CRM task. The Tour stores only its own fields. Assignees, associations, reminders and files remain owned by the linked CRM task.

Tours can be prepared on behalf of another agent by passing created_by (the “Act As” agent). The acting user must be an Admin of the brand and the target must be a member of the same brand.

Data model

Tour

Default value for status is PENDING.

Field Type Required? Notes
created_by User Agent the Tour is prepared for (defaults to caller)
title String ✓
description String
due_date Timestamp UTC timestamp in seconds
end_date Timestamp UTC timestamp in seconds
all_day Boolean Defaults to false
status String Enum PENDING, DONE
crm_task UUID Id of the backing CRM task
metadata Object
type String tour

Tour’s available model associations are as follows:

  • tour.created_by

  • tour.updated_by

  • tour.crm_task

To retrieve task-owned data with a Tour, request tour.crm_task together with the required task associations, such as crm_task.assignees, crm_task.associations, crm_task.reminders or crm_task.files. Those fields are returned under data.crm_task, not on the Tour itself.

List tours

List tours
GET/crm/tours

Example URI

GET /crm/tours
URI Parameters
HideShow
associations
string (required) Example: tour.created_by
limit
string (required) Example: 10
order
string (required) Example: -created_at
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "180d09e8-ac29-4962-804d-65ac34823619",
      "created_at": 1788495198.068629,
      "updated_at": 1788495198.068629,
      "deleted_at": null,
      "created_by": {
        "type": "user",
        "username": null,
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+16567324069",
        "created_at": 1788495198.202675,
        "id": "14c8ca07-86af-496d-901a-4777cfe69838",
        "address_id": null,
        "cover_image_url": null,
        "profile_image_url": null,
        "updated_at": 1788495198.202687,
        "user_status": "Active",
        "profile_image_thumbnail_url": null,
        "cover_image_thumbnail_url": null,
        "email_confirmed": false,
        "timezone": "America/Chicago",
        "user_type": "Agent",
        "deleted_at": null,
        "phone_confirmed": false,
        "is_shadow": null,
        "personal_room": "889bb101-180d-47fb-8055-4202c0b53db9",
        "brand": null,
        "fake_email": null,
        "features": null,
        "last_seen_at": null,
        "email_signature": "This is my signature.",
        "daily_enabled": false,
        "email_quota": 30000,
        "website": null,
        "instagram": null,
        "twitter": null,
        "linkedin": null,
        "youtube": null,
        "facebook": null,
        "designation": null,
        "tiktok": null,
        "mfa_enabled": false,
        "xpressdocs_user_id": null,
        "bio": "This is my bio.",
        "current_time": "11:13 PM - Thursday Sep 03, 2026",
        "push_allowed": true,
        "agents": null,
        "last_seen_type": null,
        "active_brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
        "display_name": "John Doe",
        "abbreviated_display_name": "John",
        "online_state": "Offline",
        "has_password": true
      },
      "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
      "title": "Act As Tour",
      "description": "Prepared in the agent context",
      "due_date": 1788581598.606,
      "end_date": 1788585198.606,
      "status": "PENDING",
      "all_day": false,
      "metadata": null,
      "kind": "Tour",
      "task_type": "Tour",
      "type": "tour"
    }
  ],
  "info": {
    "count": 1,
    "total": 1
  }
}

Create a new tour

Create a new tour
POST/crm/tours

Pass created_by to prepare the Tour on behalf of another agent (Act As).

Example URI

POST /crm/tours
URI Parameters
HideShow
associations
string (required) Example: tour.created_by,tour.crm_task,crm_task.assignees,crm_task.reminders
Request
HideShow
Body
{
  "created_by": "14c8ca07-86af-496d-901a-4777cfe69838",
  "title": "Act As Tour",
  "description": "Prepared in the agent context",
  "due_date": 1788581598.606,
  "end_date": 1788585198.606,
  "status": "PENDING"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "180d09e8-ac29-4962-804d-65ac34823619",
    "created_at": 1788495198.068629,
    "updated_at": 1788495198.068629,
    "deleted_at": null,
    "created_by": {
      "type": "user",
      "username": null,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+16567324069",
      "created_at": 1788495198.202675,
      "id": "14c8ca07-86af-496d-901a-4777cfe69838",
      "address_id": null,
      "cover_image_url": null,
      "profile_image_url": null,
      "updated_at": 1788495198.202687,
      "user_status": "Active",
      "profile_image_thumbnail_url": null,
      "cover_image_thumbnail_url": null,
      "email_confirmed": false,
      "timezone": "America/Chicago",
      "user_type": "Agent",
      "deleted_at": null,
      "phone_confirmed": false,
      "is_shadow": null,
      "personal_room": "889bb101-180d-47fb-8055-4202c0b53db9",
      "brand": null,
      "fake_email": null,
      "features": null,
      "last_seen_at": null,
      "email_signature": "This is my signature.",
      "daily_enabled": false,
      "email_quota": 30000,
      "website": null,
      "instagram": null,
      "twitter": null,
      "linkedin": null,
      "youtube": null,
      "facebook": null,
      "designation": null,
      "tiktok": null,
      "mfa_enabled": false,
      "xpressdocs_user_id": null,
      "bio": "This is my bio.",
      "current_time": "11:13 PM - Thursday Sep 03, 2026",
      "push_allowed": true,
      "agents": null,
      "last_seen_type": null,
      "active_brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
      "display_name": "John Doe",
      "abbreviated_display_name": "John",
      "online_state": "Offline",
      "has_password": true
    },
    "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
    "crm_task": {
      "id": "73249edb-0cd0-4e02-b5f9-de69471e4e46",
      "created_at": 1788495198.068629,
      "updated_at": 1788495198.068629,
      "deleted_at": null,
      "title": "Act As Tour",
      "description": "Prepared in the agent context",
      "due_date": 1788581598.606,
      "end_date": 1788585198.606,
      "status": "PENDING",
      "task_type": "Tour",
      "all_day": false,
      "metadata": null,
      "kind": "Tour",
      "assignees": [
        {
          "type": "user",
          "username": null,
          "first_name": "John",
          "last_name": "Doe",
          "email": "[email protected]",
          "phone_number": "+16567324069",
          "created_at": 1788495198.202675,
          "id": "14c8ca07-86af-496d-901a-4777cfe69838",
          "address_id": null,
          "cover_image_url": null,
          "profile_image_url": null,
          "updated_at": 1788495198.202687,
          "user_status": "Active",
          "profile_image_thumbnail_url": null,
          "cover_image_thumbnail_url": null,
          "email_confirmed": false,
          "timezone": "America/Chicago",
          "user_type": "Agent",
          "deleted_at": null,
          "phone_confirmed": false,
          "is_shadow": null,
          "personal_room": "889bb101-180d-47fb-8055-4202c0b53db9",
          "brand": null,
          "fake_email": null,
          "features": null,
          "last_seen_at": null,
          "email_signature": "This is my signature.",
          "daily_enabled": false,
          "email_quota": 30000,
          "website": null,
          "instagram": null,
          "twitter": null,
          "linkedin": null,
          "youtube": null,
          "facebook": null,
          "designation": null,
          "tiktok": null,
          "mfa_enabled": false,
          "xpressdocs_user_id": null,
          "bio": "This is my bio.",
          "current_time": "11:13 PM - Thursday Sep 03, 2026",
          "push_allowed": true,
          "agents": null,
          "last_seen_type": null,
          "active_brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
          "display_name": "John Doe",
          "abbreviated_display_name": "John",
          "online_state": "Offline",
          "has_password": true
        }
      ],
      "reminders": null,
      "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
      "type": "crm_task"
    },
    "title": "Act As Tour",
    "description": "Prepared in the agent context",
    "due_date": 1788581598.606,
    "end_date": 1788585198.606,
    "status": "PENDING",
    "all_day": false,
    "metadata": null,
    "kind": "Tour",
    "task_type": "Tour",
    "type": "tour"
  }
}

Get a tour by id

Get a tour by id
GET/crm/tours/:id

Example URI

GET /crm/tours/:id
URI Parameters
HideShow
id
string (required) Example: 180d09e8-ac29-4962-804d-65ac34823619
associations
string (required) Example: tour.crm_task,crm_task.associations,crm_association.contact
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "180d09e8-ac29-4962-804d-65ac34823619",
    "created_at": 1788495198.068629,
    "updated_at": 1788495198.068629,
    "deleted_at": null,
    "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
    "crm_task": {
      "id": "73249edb-0cd0-4e02-b5f9-de69471e4e46",
      "created_at": 1788495198.068629,
      "updated_at": 1788495198.068629,
      "deleted_at": null,
      "title": "Act As Tour",
      "description": "Prepared in the agent context",
      "due_date": 1788581598.606,
      "end_date": 1788585198.606,
      "status": "PENDING",
      "task_type": "Tour",
      "all_day": false,
      "metadata": null,
      "kind": "Tour",
      "associations": [
        {
          "id": "ee7cd72a-96c3-4fdc-8ca4-72ecc31f2a11",
          "created_at": 1788495198.889951,
          "updated_at": 1788495198.889951,
          "deleted_at": null,
          "created_by": "1cf3813c-b191-4520-afe3-c2aeee22e9b2",
          "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
          "association_type": "contact",
          "crm_task": "73249edb-0cd0-4e02-b5f9-de69471e4e46",
          "contact": {
            "id": "648015d8-3723-47db-881b-182f4e2a5b42",
            "display_name": "Tour Client",
            "partner_name": null,
            "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
            "brand_id": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
            "user_id": "1cf3813c-b191-4520-afe3-c2aeee22e9b2",
            "sort_field": "Tour Client",
            "last_touch": null,
            "last_touch_action": null,
            "next_touch": null,
            "touch_freq": null,
            "ios_address_book_id": null,
            "android_address_book_id": null,
            "created_at": 1788495198.573521,
            "updated_at": 1788495198.068629,
            "deleted_at": null,
            "created_for": "direct_request",
            "updated_for": "direct_request",
            "deleted_for": null,
            "title": null,
            "first_name": "Tour Client",
            "partner_first_name": null,
            "middle_name": null,
            "last_name": null,
            "partner_last_name": null,
            "marketing_name": null,
            "nickname": null,
            "email": "[email protected]",
            "primary_email": "[email protected]",
            "emails": [
              "[email protected]"
            ],
            "parked": false,
            "partner_email": null,
            "phone_number": null,
            "primary_phone_number": null,
            "phone_numbers": null,
            "company": null,
            "birthday": null,
            "profile_image_url": null,
            "cover_image_url": null,
            "job_title": null,
            "source_type": null,
            "source": null,
            "website": null,
            "tags": null,
            "address": null,
            "type": "contact"
          },
          "index": null,
          "metadata": null,
          "type": "crm_association"
        }
      ],
      "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
      "type": "crm_task",
      "contacts": [
        "648015d8-3723-47db-881b-182f4e2a5b42"
      ],
      "deals": [],
      "listings": [],
      "emails": []
    },
    "title": "Act As Tour",
    "description": "Prepared in the agent context",
    "due_date": 1788581598.606,
    "end_date": 1788585198.606,
    "status": "PENDING",
    "all_day": false,
    "metadata": null,
    "kind": "Tour",
    "task_type": "Tour",
    "type": "tour"
  }
}

Update a tour

Update a tour
PUT/crm/tours/:id

created_by and crm_task cannot be changed on update. Update task-owned assignees, associations, reminders and files through the linked CRM task and its endpoints under /crm/tasks/:crm_task.

Example URI

PUT /crm/tours/:id
URI Parameters
HideShow
id
string (required) Example: 180d09e8-ac29-4962-804d-65ac34823619
associations
string (required) Example: tour.created_by
Request
HideShow
Body
{
  "title": "Updated Act As Tour",
  "description": "Rescheduled for later in the week",
  "due_date": 1788667998.972,
  "end_date": 1788671598.972,
  "status": "PENDING"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "180d09e8-ac29-4962-804d-65ac34823619",
    "created_at": 1788495198.068629,
    "updated_at": 1788495198.068629,
    "deleted_at": null,
    "created_by": {
      "type": "user",
      "username": null,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+16567324069",
      "created_at": 1788495198.202675,
      "id": "14c8ca07-86af-496d-901a-4777cfe69838",
      "address_id": null,
      "cover_image_url": null,
      "profile_image_url": null,
      "updated_at": 1788495198.202687,
      "user_status": "Active",
      "profile_image_thumbnail_url": null,
      "cover_image_thumbnail_url": null,
      "email_confirmed": false,
      "timezone": "America/Chicago",
      "user_type": "Agent",
      "deleted_at": null,
      "phone_confirmed": false,
      "is_shadow": null,
      "personal_room": "889bb101-180d-47fb-8055-4202c0b53db9",
      "brand": null,
      "fake_email": null,
      "features": null,
      "last_seen_at": null,
      "email_signature": "This is my signature.",
      "daily_enabled": false,
      "email_quota": 30000,
      "website": null,
      "instagram": null,
      "twitter": null,
      "linkedin": null,
      "youtube": null,
      "facebook": null,
      "designation": null,
      "tiktok": null,
      "mfa_enabled": false,
      "xpressdocs_user_id": null,
      "bio": "This is my bio.",
      "current_time": "11:13 PM - Thursday Sep 03, 2026",
      "push_allowed": true,
      "agents": null,
      "last_seen_type": null,
      "active_brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
      "display_name": "John Doe",
      "abbreviated_display_name": "John",
      "online_state": "Offline",
      "has_password": true
    },
    "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
    "title": "Updated Act As Tour",
    "description": "Rescheduled for later in the week",
    "due_date": 1788667998.972,
    "end_date": 1788671598.972,
    "status": "PENDING",
    "all_day": false,
    "metadata": null,
    "kind": "Tour",
    "task_type": "Tour",
    "type": "tour"
  }
}

Change a tour's status

Change a tour's status
PATCH/crm/tours/:id/status

Marking a Tour DONE clears the linked CRM task’s pending reminders and normalizes the Tour dates.

Example URI

PATCH /crm/tours/:id/status
URI Parameters
HideShow
id
string (required) Example: 180d09e8-ac29-4962-804d-65ac34823619
associations
string (required) Example: tour.crm_task,crm_task.reminders
Request
HideShow
Body
{
  "status": "DONE"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "180d09e8-ac29-4962-804d-65ac34823619",
    "created_at": 1788495198.068629,
    "updated_at": 1788495198.068629,
    "deleted_at": null,
    "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
    "crm_task": {
      "id": "73249edb-0cd0-4e02-b5f9-de69471e4e46",
      "created_at": 1788495198.068629,
      "updated_at": 1788495198.068629,
      "deleted_at": null,
      "title": "Updated Act As Tour",
      "description": "Rescheduled for later in the week",
      "due_date": 1788495199.085,
      "end_date": 1788498799.085,
      "status": "DONE",
      "task_type": "Tour",
      "all_day": false,
      "metadata": null,
      "kind": "Tour",
      "reminders": null,
      "brand": "55bc073d-bd9d-4d2e-9a0a-f831803633a0",
      "type": "crm_task"
    },
    "title": "Updated Act As Tour",
    "description": "Rescheduled for later in the week",
    "due_date": 1788495199.085,
    "end_date": 1788498799.085,
    "status": "DONE",
    "all_day": false,
    "metadata": null,
    "kind": "Tour",
    "task_type": "Tour",
    "type": "tour"
  }
}

Delete a tour

Delete a tour
DELETE/crm/tours/:id

Example URI

DELETE /crm/tours/:id
URI Parameters
HideShow
id
string (required) Example: 180d09e8-ac29-4962-804d-65ac34823619
Response  204

Generated by aglio on 04 Sep 2026