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

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
crm_task UUID Id of the backing CRM task
type String tour

end_date, status, all_day and metadata are not fields on the Tour model. They remain available on the linked CRM task. status can also be forwarded through the Tour update endpoint; other task-specific operations use /crm/tasks.

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": "f63177aa-5e87-4894-b39c-57c1fb837bf4",
      "created_at": 1792423572.874494,
      "updated_at": 1792423572.874494,
      "deleted_at": null,
      "created_by": {
        "type": "user",
        "username": null,
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+17788723535",
        "created_at": 1792423572.939415,
        "id": "39a25cc6-9adc-4b6c-94ea-dfcaa2214ee0",
        "address_id": null,
        "cover_image_url": null,
        "profile_image_url": null,
        "updated_at": 1792423572.939421,
        "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": "dccc4772-e3f1-4afa-975d-abbd65c65bc9",
        "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": "10:26 AM - Monday Oct 19, 2026",
        "push_allowed": true,
        "agents": null,
        "last_seen_type": null,
        "active_brand": "2095677a-9095-4c43-ba56-0484306f98cf",
        "display_name": "John Doe",
        "abbreviated_display_name": "John",
        "online_state": "Offline",
        "has_password": true
      },
      "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
      "title": "Tour through task endpoint",
      "description": null,
      "due_date": 1792509973.124,
      "kind": "Tour",
      "task_type": "Tour",
      "type": "tour"
    },
    {
      "id": "7676c934-5f54-4639-8f7d-ffac9e34d2c7",
      "created_at": 1792423572.874494,
      "updated_at": 1792423572.874494,
      "deleted_at": null,
      "created_by": {
        "type": "user",
        "username": null,
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+17788723535",
        "created_at": 1792423572.939415,
        "id": "39a25cc6-9adc-4b6c-94ea-dfcaa2214ee0",
        "address_id": null,
        "cover_image_url": null,
        "profile_image_url": null,
        "updated_at": 1792423572.939421,
        "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": "dccc4772-e3f1-4afa-975d-abbd65c65bc9",
        "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": "10:26 AM - Monday Oct 19, 2026",
        "push_allowed": true,
        "agents": null,
        "last_seen_type": null,
        "active_brand": "2095677a-9095-4c43-ba56-0484306f98cf",
        "display_name": "John Doe",
        "abbreviated_display_name": "John",
        "online_state": "Offline",
        "has_password": true
      },
      "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
      "title": "Act As Tour",
      "description": "Prepared in the agent context",
      "due_date": 1792509973.091,
      "kind": "Tour",
      "task_type": "Tour",
      "type": "tour"
    }
  ],
  "info": {
    "count": 2,
    "total": 2
  }
}

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": "39a25cc6-9adc-4b6c-94ea-dfcaa2214ee0",
  "title": "Act As Tour",
  "description": "Prepared in the agent context",
  "due_date": 1792509973.091,
  "end_date": 1792513573.091,
  "status": "DONE",
  "all_day": true,
  "metadata": {
    "ignored": true
  }
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "7676c934-5f54-4639-8f7d-ffac9e34d2c7",
    "created_at": 1792423572.874494,
    "updated_at": 1792423572.874494,
    "deleted_at": null,
    "created_by": {
      "type": "user",
      "username": null,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+17788723535",
      "created_at": 1792423572.939415,
      "id": "39a25cc6-9adc-4b6c-94ea-dfcaa2214ee0",
      "address_id": null,
      "cover_image_url": null,
      "profile_image_url": null,
      "updated_at": 1792423572.939421,
      "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": "dccc4772-e3f1-4afa-975d-abbd65c65bc9",
      "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": "10:26 AM - Monday Oct 19, 2026",
      "push_allowed": true,
      "agents": null,
      "last_seen_type": null,
      "active_brand": "2095677a-9095-4c43-ba56-0484306f98cf",
      "display_name": "John Doe",
      "abbreviated_display_name": "John",
      "online_state": "Offline",
      "has_password": true
    },
    "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
    "crm_task": {
      "id": "14349613-272b-4a5f-b442-72549e913c84",
      "created_at": 1792423572.874494,
      "updated_at": 1792423572.874494,
      "deleted_at": null,
      "title": "Act As Tour",
      "description": "Prepared in the agent context",
      "due_date": 1792509973.091,
      "end_date": null,
      "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": "+17788723535",
          "created_at": 1792423572.939415,
          "id": "39a25cc6-9adc-4b6c-94ea-dfcaa2214ee0",
          "address_id": null,
          "cover_image_url": null,
          "profile_image_url": null,
          "updated_at": 1792423572.939421,
          "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": "dccc4772-e3f1-4afa-975d-abbd65c65bc9",
          "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": "10:26 AM - Monday Oct 19, 2026",
          "push_allowed": true,
          "agents": null,
          "last_seen_type": null,
          "active_brand": "2095677a-9095-4c43-ba56-0484306f98cf",
          "display_name": "John Doe",
          "abbreviated_display_name": "John",
          "online_state": "Offline",
          "has_password": true
        }
      ],
      "reminders": null,
      "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
      "type": "crm_task"
    },
    "title": "Act As Tour",
    "description": "Prepared in the agent context",
    "due_date": 1792509973.091,
    "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: 7676c934-5f54-4639-8f7d-ffac9e34d2c7
associations
string (required) Example: tour.crm_task,crm_task.associations,crm_association.contact
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "7676c934-5f54-4639-8f7d-ffac9e34d2c7",
    "created_at": 1792423572.874494,
    "updated_at": 1792423572.874494,
    "deleted_at": null,
    "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
    "crm_task": {
      "id": "14349613-272b-4a5f-b442-72549e913c84",
      "created_at": 1792423572.874494,
      "updated_at": 1792423572.874494,
      "deleted_at": null,
      "title": "Act As Tour",
      "description": "Prepared in the agent context",
      "due_date": 1792509973.091,
      "end_date": null,
      "status": "PENDING",
      "task_type": "Tour",
      "all_day": false,
      "metadata": null,
      "kind": "Tour",
      "associations": [
        {
          "id": "648b53b0-fbd4-48fd-8f3d-420785f2ae98",
          "created_at": 1792423573.230318,
          "updated_at": 1792423573.230318,
          "deleted_at": null,
          "created_by": "e53c6647-85c7-4bac-b55b-92d4d1c7762d",
          "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
          "association_type": "contact",
          "crm_task": "14349613-272b-4a5f-b442-72549e913c84",
          "contact": {
            "id": "2d786586-46dc-4d28-9e0b-7c38d677926b",
            "display_name": "Tour Client",
            "partner_name": null,
            "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
            "brand_id": "2095677a-9095-4c43-ba56-0484306f98cf",
            "user_id": "e53c6647-85c7-4bac-b55b-92d4d1c7762d",
            "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": 1792423573.080775,
            "updated_at": 1792423572.874494,
            "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": "2095677a-9095-4c43-ba56-0484306f98cf",
      "type": "crm_task",
      "contacts": [
        "2d786586-46dc-4d28-9e0b-7c38d677926b"
      ],
      "deals": [],
      "listings": [],
      "emails": []
    },
    "title": "Act As Tour",
    "description": "Prepared in the agent context",
    "due_date": 1792509973.091,
    "kind": "Tour",
    "task_type": "Tour",
    "type": "tour"
  }
}

Update a tour

Update a tour
PUT/crm/tours/:id

This is a partial update. Omitted fields retain their current values, and created_by and crm_task cannot be changed. status may be supplied to update the linked CRM task without sending redundant task fields such as title or task_type. It remains absent from the top-level Tour response.

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: 7676c934-5f54-4639-8f7d-ffac9e34d2c7
associations
string (required) Example: tour.created_by
Request
HideShow
Body
{
  "title": "Updated Act As Tour",
  "description": "Rescheduled for later in the week",
  "due_date": 1792596373.263
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "7676c934-5f54-4639-8f7d-ffac9e34d2c7",
    "created_at": 1792423572.874494,
    "updated_at": 1792423572.874494,
    "deleted_at": null,
    "created_by": {
      "type": "user",
      "username": null,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+17788723535",
      "created_at": 1792423572.939415,
      "id": "39a25cc6-9adc-4b6c-94ea-dfcaa2214ee0",
      "address_id": null,
      "cover_image_url": null,
      "profile_image_url": null,
      "updated_at": 1792423572.939421,
      "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": "dccc4772-e3f1-4afa-975d-abbd65c65bc9",
      "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": "10:26 AM - Monday Oct 19, 2026",
      "push_allowed": true,
      "agents": null,
      "last_seen_type": null,
      "active_brand": "2095677a-9095-4c43-ba56-0484306f98cf",
      "display_name": "John Doe",
      "abbreviated_display_name": "John",
      "online_state": "Offline",
      "has_password": true
    },
    "brand": "2095677a-9095-4c43-ba56-0484306f98cf",
    "title": "Updated Act As Tour",
    "description": "Rescheduled for later in the week",
    "due_date": 1792596373.263,
    "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: 7676c934-5f54-4639-8f7d-ffac9e34d2c7
Response  204

Generated by aglio on 19 Oct 2026