Scheduling Requests

A scheduling request is the record in TimeZest which tracks all the details related to booking an individual appointment.

A scheduling request will be created at the earliest time that TimeZest knows about a potential appointment. For appointments requested through a PSA system, this scheduling request will be created at the time of the request, even though the end user has not yet selected a time for their appointment. For appointments booked with a shareable URL or with URL-based scheduling, TimeZest will create the scheduling request at the same time the appointment is booked.

Statuses

TimeZest uses a series of statuses to track how scheduling request move through their life cycle. These statuses are:

new - A newly created scheduling request, which TimeZest has not sent any emails to the end user about.
sent - A scheduling request where TimeZest has successfully sent at least one email to the end user.
scheduled - A scheduling request where the end user has selected a time for their appointment.
cancelled - A scheduling request which has been cancelled, either by the end user or an agent.
closed - A scheduling request which has been closed out by a workflow action, and which can no longer used to schedule an appointment.

Associated Entities

Associated Entities is what TimeZest uses to link a scheduling request to other entities in your systems, such as a ConnectWise Manage ticket, or an Autotask contact. Each associated entity is identified by a type and other attributes.

Type	Properties
`autotask/company`	A company in Autotask. Name `id` Type number Description Identifier of the company in the Autotask API. e.g. `23149`
`autotask/contact`	A contact in Autotask. Name `id` Type number Description Identifier of the client in the Autotask API. e.g. `1778`
`autotask/ticket`	A ticket in Autotask. Name `id` Type number Description Identifier of the ticket in the Autotask API. This is not the ticket number. e.g. `13281` Name `number` Type string Description The number of the ticket as displayed in Autotask. e.g. `T20230401.0001`
`connectwise_psa/company`	A company in ConnectWise PSA. Name `id` Type number Description Identifier of the company in the ConnectWise PSA API. e.g. `154309`
`connectwise_psa/contact`	A contact in ConnectWise PSA. Name `id` Type number Description Identifier of the client in the ConnectWise PSA API. e.g. `9065`
`connectwise_psa/project_ticket`	A project ticket in ConnectWise PSA. Name `id` Type number Description Identifier of the ticket in the ConnectWise PSA API. This slightly differs to the ticket number in that it does not start with a `#`. e.g. `2134554` Name `number` Type string Description The number of the ticket as displayed in ConnectWise PSA. e.g. `#2134554`
`connectwise_psa/service_ticket`	A service ticket in ConnectWise PSA. Name `id` Type number Description Identifier of the ticket in the ConnectWise PSA API. This slightly differs to the ticket number in that it does not start with a `#`. e.g. `2134554` Name `number` Type string Description The number of the ticket as displayed in ConnectWise PSA. e.g. `#2134554`

The Scheduling Request object

Some text about the scheduling request object.

Name
id
Type
string
Description
Unique identifier for the scheduling request.
Name
object
Type
string
Description
The type of the object. For a scheduling_request, this will always be the string scheduling_request.
Name
appointment_type_id
Type
string
Description
An identifier for the appointment type of the scheduling request.
Name
end_user_email
Type
string
Description
The email address of the end user who is to select a time for the appointment.
Name
end_user_name
Type
string
Description
The name of the end user who is to select a time for the appointment.
Name
associated_entities
Type
array
Description
The entities associated with the scheduling request.
Name
resources
Type
array
Description
The resources with which the appointment is to be booked.
Name
scheduled_agents
Type
array
Description
The agents with which the appointment has been booked. When the end user has not yet booked an appointment, this will be an empty array. This property differs to the resources property in that TimeZest will select a specific agent from any team specified as a resource when the appointment is booked.
Name
scheduled_at
Type
timestamp
Description
The time when the end user booked their appointment. This may be null when the end user has not yet booked their appointment. It is not the time of the booked appointment.
Name
scheduling_url
Type
string
Description
The URL which the end user can use to schedule, reschedule and cancel their appointment.
Name
selected_start_time
Type
timestamp
Description
The time the end user has selected for their appointment. This may be null where the end user has not yet booked their appointment.
Name
selected_time_zone
Type
string
Description
The time zone the end user was using when they selected the time for their appointment. This property can be used to display the appointment time in the local time zone of the user where needed. This may be null where the end user has not yet booked their appointment.
Name
status
Type
string
Description
The status of the scheduling request. Valid values are detailed above.
Name
created_at
Type
timestamp
Description
The time the scheduling request was created.
Name
updated_at
Type
timestamp
Description
The most recent time the scheduling request was updated.

Example Scheduling Request object

{
  "id":"sreq_p4fvlg5FUuKSviNNemZzAO",
  "object":"scheduling_request",
  "appointment_type_id":"apty_2s211C0S1I5gqIaA8wbDu6",
  "end_user_email":"[email protected]",
  "end_user_name":"Rodney Smith",
  "associated_entities":[
      {
        "type":"connectwise_psa/service_ticket",
        "id":1234,
        "number":"#1234"
      },
      {
        "type":"connectwise_psa/contact",
        "id":31762
      },
      {
        "type":"connectwise_psa/company",
        "id":209116
      }
  ],
  "resources":[
      {
        "type":"agent",
        "id":"agnt_2wvARLFjTDmO4djuOBf3r",
        "name":"Samantha Jones"
      }
  ],
  "scheduled_agents":[

  ],
  "scheduled_at":1691931421,
  "scheduling_url":"https://example.timezest.com/schedule/JMBEl2BVfZLGg5imfjnp",
  "selected_start_time":1692363445,
  "selected_time_zone":"Eastern Time (US & Canada)",
  "status":"scheduled",
  "created_at":1691585916,
  "updated_at":1691931421
}

GET/v1/scheduling_requests

Retrieve all scheduling requests

This endpoint returns a list of all scheduling requests.

The response returned will be a paginated list object, whose data field will be an array of Scheduling Request objects as detailed above.

Request

curl https://api.timezest.com/v1/scheduling_requests \
-H "Authorization: Bearer <Your API Token>"

Response

{
  "next_page": null,
  "previous_page": null,
  "object": "list",
  "data": [
    {
      "id": "sreq_p4fvlg5FUuKSviNNemZzAO",
      "object": "scheduling_request",
      "appointment_type_id": "apty_2s211C0S1I5gqIaA8wbDu6",
      "end_user_email": "[email protected]",
      "end_user_name": "Rodney Smith",
      "associated_entities": [],
      "resources": [],
      "scheduled_agents": [],
      "scheduled_at": 1691931421,
      "scheduling_url": "https://example.timezest.com/schedule/JMBEl2BVfZLGg5imfjnp",
      "selected_start_time": 1692363445,
      "selected_time_zone": "Eastern Time (US & Canada)",
      "status": "scheduled",
      "created_at": 1691585916,
      "updated_at": 1691931421
    },
    {
      "id": "sreq_c94wl0BRlCwzFkAkrEWze",
      "object": "scheduling_request",
      "appointment_type_id": "apty_2Nd3r74J71Koi1mAS5a55",
      "end_user_email": "[email protected]",
      "end_user_name": "Jane Adams",
      "associated_entities": [],
      "resources": [],
      "scheduled_agents": [],
      "scheduled_at": 1692864713,
      "scheduling_url": "https://example.timezest.com/schedule/g40iofTifJG7sP3Nrsjs",
      "selected_start_time": 1692968400,
      "selected_time_zone": "Eastern Time (US & Canada)",
      "status": "scheduled",
      "created_at": 1692864713,
      "updated_at": 1692864713
    }
  ]
}

Supported TQL Attributes

The appointment types endpoint can be filtered using the following TQL attributes:

Attribute	Type	Supported Operators
`scheduling_request.autotask_company_id`	ID	`EQ`, `NOT_EQ`
`scheduling_request.autotask_contact_id`	ID	`EQ`, `NOT_EQ`
`scheduling_request.autotask_ticket_number`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.connectwise_psa_company_id`	ID	`EQ`, `NOT_EQ`
`scheduling_request.connectwise_psa_contact_id`	ID	`EQ`, `NOT_EQ`
`scheduling_request.connectwise_psa_ticket_number`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.connectwise_psa_project_ticket_number`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.connectwise_psa_service_ticket_number`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.halo_psa_client_id`	ID	`EQ`, `NOT_EQ`
`scheduling_request.halo_psa_user_id`	ID	`EQ`, `NOT_EQ`
`scheduling_request.halo_psa_ticket_number`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.end_user_name`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.end_user_email`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.status`	String	`EQ`, `NOT_EQ`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`
`scheduling_request.selected_start_time`	Timestamp	`EQ`, `NOT_EQ`, `LT`, `LTE`, `GT`, `GTE`
`scheduling_request.scheduled_at`	Timestamp	`EQ`, `NOT_EQ`, `LT`, `LTE`, `GT`, `GTE`
`scheduling_request.created_at`	Timestamp	`EQ`, `NOT_EQ`, `LT`, `LTE`, `GT`, `GTE`

GET/v1/scheduling_requests/:id

Retrieve a Scheduling Request

This endpoint can be used to retrieve a single scheduling request. The response will be a single scheduling request object, and this endpoint does not support filtering or pagination.

Request

curl https://api.timezest.com/v1/scheduling_requests/sreq_c94wl0BRlCwzFkAkrEWze \
-H "Authorization: Bearer <Your API Token>"

Response

{
  "id":"sreq_p4fvlg5FUuKSviNNemZzAO",
  "object":"scheduling_request",
  "appointment_type_id":"apty_2s211C0S1I5gqIaA8wbDu6",
  "end_user_email":"[email protected]",
  "end_user_name":"Rodney Smith",
  "associated_entities":[
      {
        "type":"connectwise_psa/service_ticket",
        "id":1234,
        "number":"#1234"
      },
      {
        "type":"connectwise_psa/contact",
        "id":31762
      },
      {
        "type":"connectwise_psa/company",
        "id":209116
      }
  ],
  "resources":[
      {
        "type":"agent",
        "id":"agnt_2wvARLFjTDmO4djuOBf3r",
        "name":"Samantha Jones"
      }
  ],
  "scheduled_agents":[

  ],
  "scheduled_at":1691931421,
  "scheduling_url":"https://example.timezest.com/schedule/JMBEl2BVfZLGg5imfjnp",
  "selected_start_time":1692363445,
  "selected_time_zone":"Eastern Time (US & Canada)",
  "status":"scheduled",
  "created_at":1691585916,
  "updated_at":1691931421
}

POST/v1/scheduling_requests

Create a Scheduling Request

This endpoint can be used to create a new scheduling request.

This endpoint accepts the following parameters:

Name
appointment_type_id
Type
string required
Description
An identifier for the appointment type of the appointment you wish the end user to schedule.
Name
end_user_name
Type
string optional
Description
The name of the end user. A value for this field is required, but can be omitted here if a valid associated entity is specified where TimeZest can obtain this information.
Name
end_user_email
Type
string optional
Description
The email address of the end user. A value for this field is required, but can be omitted here if a valid associated entity is specified where TimeZest can obtain this information.
Name
end_user_company
Type
string optional
Description
The company name of the end user. A value for this field is required, but can be omitted here if a valid associated entity is specified where TimeZest can obtain this information.
Name
trigger_mode
Type
string required
Description
This property tells TimeZest which workflow trigger to fire when creating the scheduling request. It can have two possible values: pod, in which case TimeZest will execute the workflow as though the scheduling request had been created in the pod/insight, or generate_url, in which case TimeZest will execute the workflow as though the "Generate URL" option had been used in the pod. In TimeZest's default configuration, the generate_url does nothing.
Name
associated_entities
Type
array optional
Description
Entities to associate with the scheduling request.
Name
resource_ids
Type
array required
Description
An array of resource IDs (i.e. agent IDs or team IDs) for the resources who will be scheduled on the appointment.

Request

  curl -X POST https://api.timezest.com/v1/scheduling_requests \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Your API Token>' \
  -d '{ \
    "appointment_type_id":"apty_2s211C0S1I5gqIaA8wbDu6", \
    "trigger_mode":"pod", \
    "associated_entities:[ \
      { "type":"connectwise_psa/service_ticket", "number":"#1234" } \
    ], \
    "resource_ids":[ \
      "agnt_2wvARLFjTDmO4djuOBf3r", \
      "team_W4hPN4gKvru7c4BWerF4d" \
    ] \
  }'

How TimeZest retrieves end user details

There is a lot of flexibility in specifying the name, email and company name of the end user who will schedule with the scheduling request. This information can be specified directly in the end_user_name and similar fields, or it can be obtained by TimeZest from an associated entity.

TimeZest will take the end_user_name, end_user_email and end_user_company from the following sources, in order of preference:

From a connectwise/contact, autotask/contact or halo_psa/user associated entity.
From the contact/user associated with a connect_wise/service_ticket, connectwise/project_ticket, autotask/ticket or halo_psa/ticket.
From the value provided in the end_user_name and end_user_email fields.

TimeZest will return a validation error if a value for the end user name and email cannot be found in any of these places.