Back to top

API Documentation

Calendar

Overview

This document describes the set of APIs used in the calendar view.

Data Model

A calendar_event object is a common representation of event-like objects throughout Rechat system.

Field Type Description
id string Id of the underlying event-like object
created_by uuid
created_at number
updated_at number
brand uuid
object_type Enum Type of the underlying object. crm_task or deal_context or contact_attribute
event_type string Type of the event. Used to infer icons on calendar events.
type_label string Label used for type column in the Web UI.
timestamp number The exact timestamp of the event. In case of recurring events, the original user input is returned.
end_date number End time of the event, if defined.
recurring boolean Whether this a recurring event or not. Currently only applies to birthday and important_date
next_occurance number Next time the event is supposed to occur, if it’s a recurring event.
title string Title of the event record. Usually enough for direct use on clients.
crm_task uuid Related crm_task object
deal uuid Related deal object
contact uuid related contact object
campaign uuid related email campaign
thread_key string related email thread key
people_len number Total number of people associated with the event. Meant to be used in conjuction with people association.
metadata json arbitrary metadata associated with the event. usually holds data related to specific object types.

Associations

Associations defined for the calendar_event object are listed below.

Association Type Description
people Mixed array of Contact or Agent 5 items from contacts or agents associated with the event.
full_crm_task CrmTask Separate association for the full crm_task object instead of id.
full_deal Deal Separate association for the full deal object instead of id.
full_contact Contact Separate association for the full contact object instead of id.
full_campaign EmailCampaign Separate association for the full campaign object instead of id.
activity Activity Separate association for the full activity object instead of id.
full_thread EmailThread Separate association for the full email_thread object instead of id.
holiday Holiday Separate association for the holiday object

Object types

Since calendar events come from all sorts of different sources, an object_type field is given in each event that indicates the entity type from which the event has originated from.

Due to some performance considerations, calendar events have two representations in the calendar API, depending on whether they are intended to be queried for associated objects or not. For instance, a crm_task object type has another representation, crm_association which is used to query crm events for a specific contact, deal or listing. The full list of object types and their dual representation is given in the following table:

Object type Dual representation Dual is per each Description
contact contact contact contact next touch dates
contact_attribute contact_attribute contact contact touch dates like birthdays and anniversaries
deal_context - deal critical dates
crm_task crm_association contact, deal, listing normal CRM events
email_campaign email_campaign_recipient contact email campaigns, both scheduled and executed
email_thread email_thread_recipient contact synchronized email threads
activity activity contact activities of client users associated with a contact
holiday public holidays

Note that if you request a dual object type without specifying a filter on an associated object (mostly contact), you’ll get several copies of the same events per each of those associated objects. In essense, duals have been provided to perform queries on associated objects with good performance.

Tip: As a rule of thumb, always use the dual object type when querying events for a specific contact, to build a timeline view for instance.

Event types

Possible values for event_type field are:

  • If object_type = crm_task or crm_association:

    • Call
    • Message
    • Todo
    • Closing
    • Inspection
    • Tour
    • Listing appointment
    • Follow up
    • Open House

  • If object_type = deal_context:

    • list_date
    • expiration_date
    • contract_date
    • inspection_date
    • option_period
    • financing_due
    • title_due
    • t47_due
    • closing_date
    • possession_date
    • lease_executed
    • lease_application_date
    • lease_begin
    • lease_end
    • home_anniversary (this is a virtual event type coming from closing_date or lease_end)

  • If object_type = contact_attribute:

    • birthday
    • child_birthday
    • wedding_anniversary
    • home_anniversary
    • work_anniversary
    • any other custom attribute with a date type

  • If object_type = email_campaign:

    • scheduled_email
    • executed_email

  • If object_type = email_thread:

    • gmail
    • outlook

  • If object_type = activity:

    • possible activity types is too long and the list can grow even longer

Get Calendar events

Get Calendar events
GET/calendar

Example URI

GET /calendar
URI Parameters
HideShow
low
number (required) Example: 1764288000

Lower bound for date range

high
number (required) Example: 1766880000

Upper bound for date range

users
array (optional) 

Filter by specific users

Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "42f004eb-5283-4a33-a82c-f0e3bb07d0a7",
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "created_at": 1765163411.873558,
      "updated_at": 1765163411.873558,
      "deleted_at": null,
      "parent_deleted_at": null,
      "last_updated_at": "2025-12-08T03:10:11.873Z",
      "object_type": "contact_attribute",
      "event_type": "birthday",
      "type_label": "Spouse Birthday",
      "timestamp": 1764720000,
      "date": "2025-12-03T00:00:00.000Z",
      "next_occurence": "2026-12-03T00:00:00.000Z",
      "end_date": null,
      "recurring": true,
      "title": "John Doe's Spouse's Birthday (Jane Doe)",
      "crm_task": null,
      "all_day": true,
      "deal": null,
      "contact": "b045c2ee-a172-4bea-a71b-4be02bab5601",
      "campaign": null,
      "credential_id": null,
      "thread_key": null,
      "showing": null,
      "flow": null,
      "accessible_to": null,
      "people_len": 1,
      "status": null,
      "metadata": {
        "is_partner": true
      },
      "timestamp_readable": "2025-12-03T00:00:00.000Z",
      "timestamp_midday": "2025-12-03T12:00:00.000Z",
      "type": "calendar_event",
      "sort_timestamp": 1764720000
    },
    {
      "id": "a684768c-cd3f-4b50-9c4a-9c023c11be8a",
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "created_at": 1765163411.873429,
      "updated_at": 1765163411.873429,
      "deleted_at": null,
      "parent_deleted_at": null,
      "last_updated_at": "2025-12-08T03:10:11.873Z",
      "object_type": "contact_attribute",
      "event_type": "wedding_anniversary",
      "type_label": "Wedding Anniversary",
      "timestamp": -5335372800,
      "date": "1800-12-06T00:00:00.000Z",
      "next_occurence": "2026-12-06T00:00:00.000Z",
      "end_date": null,
      "recurring": true,
      "title": "John Doe's Wedding Anniversary",
      "crm_task": null,
      "all_day": true,
      "deal": null,
      "contact": "b045c2ee-a172-4bea-a71b-4be02bab5601",
      "campaign": null,
      "credential_id": null,
      "thread_key": null,
      "showing": null,
      "flow": null,
      "accessible_to": null,
      "people_len": 1,
      "status": null,
      "metadata": {
        "is_partner": false
      },
      "timestamp_readable": "1800-12-06T00:00:00.000Z",
      "timestamp_midday": "1800-12-06T12:00:00.000Z",
      "type": "calendar_event",
      "sort_timestamp": 1764979200
    },
    {
      "id": "78441e13-4f16-47c9-b675-fdf85a3e2781",
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "created_at": 1765163411.872911,
      "updated_at": 1765163411.872911,
      "deleted_at": null,
      "parent_deleted_at": null,
      "last_updated_at": "2025-12-08T03:10:11.872Z",
      "object_type": "contact_attribute",
      "event_type": "birthday",
      "type_label": "Birthday",
      "timestamp": 1765065600,
      "date": "2025-12-07T00:00:00.000Z",
      "next_occurence": "2026-12-07T00:00:00.000Z",
      "end_date": null,
      "recurring": true,
      "title": "John Doe's Birthday",
      "crm_task": null,
      "all_day": true,
      "deal": null,
      "contact": "b045c2ee-a172-4bea-a71b-4be02bab5601",
      "campaign": null,
      "credential_id": null,
      "thread_key": null,
      "showing": null,
      "flow": null,
      "accessible_to": null,
      "people_len": 1,
      "status": null,
      "metadata": {
        "is_partner": false
      },
      "timestamp_readable": "2025-12-07T00:00:00.000Z",
      "timestamp_midday": "2025-12-07T12:00:00.000Z",
      "type": "calendar_event",
      "sort_timestamp": 1765065600
    },
    {
      "id": "fba0a00e-1628-48e6-8338-ddebc771391a",
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "created_at": 1765163411.873622,
      "updated_at": 1765163411.873622,
      "deleted_at": null,
      "parent_deleted_at": null,
      "last_updated_at": "2025-12-08T03:10:11.873Z",
      "object_type": "contact_attribute",
      "event_type": "birthday",
      "type_label": "Birthday",
      "timestamp": 1765238400,
      "date": "2025-12-09T00:00:00.000Z",
      "next_occurence": "2025-12-09T00:00:00.000Z",
      "end_date": null,
      "recurring": true,
      "title": "Gholi Gholavi's Birthday",
      "crm_task": null,
      "all_day": true,
      "deal": null,
      "contact": "bee50e19-000e-470b-96f4-d29e9122f42b",
      "campaign": null,
      "credential_id": null,
      "thread_key": null,
      "showing": null,
      "flow": null,
      "accessible_to": null,
      "people_len": 1,
      "status": null,
      "metadata": {
        "is_partner": false
      },
      "timestamp_readable": "2025-12-09T00:00:00.000Z",
      "timestamp_midday": "2025-12-09T12:00:00.000Z",
      "type": "calendar_event",
      "sort_timestamp": 1765238400
    }
  ],
  "info": {
    "low": "Fri, 28 Nov 2025 00:00:00 GMT",
    "high": "Sun, 28 Dec 2025 00:00:00 GMT",
    "count": 4,
    "total": 0
  }
}

Get iCal feed url

Get iCal feed url
GET/calendar/feed

Example URI

GET /calendar/feed
Request
HideShow
Body
{
  "types": [
    "birthday",
    "wedding_anniversary",
    "option_period"
  ],
  "filter": [
    {
      "brand": "0762b361-873a-4fc2-94cc-66a5c9c80038"
    }
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": "http://localhost/calendar/akZ6WXUyMWVhM2IxMForTFF6SnhWdnNraEtlZkxWV1BRRGRiSzRwUFl5VGFEV2tyU3RDVHV1Qkh6QzhWUVhDbnpBPT0.iCal?timestamp=1765163412"
}

Get global notification settings

Get global notification settings
GET/calendar/settings/notifications

Example URI

GET /calendar/settings/notifications
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "cc9a6566-8bc1-44b6-8f68-cf13120862aa",
      "extract": 1765163410.240692,
      "object_type": "contact_attribute",
      "event_type": "birthday",
      "reminder": 86400,
      "type": "calendar_notification_setting"
    }
  ],
  "info": {
    "count": 1,
    "total": 0
  }
}

Set global notification settings

Set global notification settings
PUT/calendar/settings/notifications

Example URI

PUT /calendar/settings/notifications
Request
HideShow
Body
{
  "settings": [
    {
      "object_type": "contact_attribute",
      "event_type": "birthday",
      "reminder": 86400
    }
  ]
}
Response  204

Generated by aglio on 08 Dec 2025