Agents

An agent is an actual person who can have an appointment scheduled for them.

Elsewhere, and historically, in TimeZest, we have called agents users. We will be moving away from this terminology in the future as it causes confusion between "users who have appointments booked" (i.e. engineers and MSP employees) and "users who book appointments" (i.e. end users at your customers).

The Agent object

The agent object describes an agent and their attributes.

  • Name
    id
    Type
    string
    Description

    Unique identifier for the agent.

  • Name
    object
    Type
    string
    Description

    The type of the object. For an agent, this will always be the string agent.

  • Name
    name
    Type
    string
    Description

    The name of the agent.

  • Name
    email
    Type
    string
    Description

    The email address associated with the agent. This email address is used to link their identity to accounts in other systems, as well as allowing them to log in to TimeZest directly where authorized.

  • Name
    role
    Type
    string
    Description

    The role of the agent in TimeZest. This will be a string with one of two values: either user or administrator. An agent with the administrator role can administer all aspects of TimeZest, and an agent with the user role can only make changes to their own details.

  • Name
    schedulable
    Type
    boolean
    Description

    A schedulable agent is one with an active TimeZest license, and for whom appointments can be scheduled. Non-schedulable agents (such as dispatchers) can login and administer TimeZest with the appropriate role, but are not charged for, and cannot have appointments scheduled for them.

  • Name
    two_factor_enabled
    Type
    boolean
    Description

    Whether the agent has two-factor authentication enabled on their TimeZest account.

  • Name
    url_slug
    Type
    string
    Description

    The URL slug for the agent, which is the identifier used in URLs built in TimeZest to enable appointments to be scheduled for the agent with shareable URLs or URL-based scheduling. This property may be null.

  • Name
    created_at
    Type
    timestamp
    Description

    The time the agent record was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    The most recent time the agent record was updated.

Example Agent object

{
  "id": "agnt_2wvARLFjTDmO4djuOBf3r",
  "object": "agent",
  "name": "Teresa Smith",
  "email": "[email protected]",
  "role": "administrator",
  "schedulable": true,
  "two_factor_enabled": false,
  "url_slug": "teresa-smith",
  "created_at": 1692172402,
  "updated_at": 1692172694
}
GET/v1/agents

Retrieve all agents

This endpoint returns a list of all agents.

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

Supported TQL Attributes

The agents endpoint can be filtered using the following TQL attributes:

AttributeTypeSupported Operators
agent.nameStringEQ, NOT_EQ, LIKE, NOT_LIKE, IN, NOT_IN
agent.emailStringEQ, NOT_EQ, LIKE, NOT_LIKE, IN, NOT_IN
agent.roleStringEQ, NOT_EQ, LIKE, NOT_LIKE, IN, NOT_IN
agent.schedulableBooleanEQ, NOT_EQ
agent.two_factor_enabledBooleanEQ, NOT_EQ
agent.url_slugStringEQ, NOT_EQ, LIKE, NOT_LIKE, IN, NOT_IN
agent.created_atTimestampEQ, NOT_EQ, LT, LTE, GT, GTE

Request

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

Response

{
  "object": "list",
  "next_page": "https://api.timezest.com/v1/agents?starting_after=agnt_9F0TBgg6RoPeqo6hLAP0H",
  "previous_page": null,
  "data": [
    {
      "id": "agnt_2wvARLFjTDmO4djuOBf3r",
      "object": "agent",
      "name": "Teresa Smith",
      "email": "[email protected]",
      "role": "administrator",
      "schedulable": true,
      "two_factor_enabled": false,
      "url_slug": "teresa-smith",
      "created_at": 1692172402,
      "updated_at": 1692172694
    },
    {
      "id": "agnt_9F0TBgg6RoPeqo6hLAP0H",
      "object": "agent",
      "name": "Derryn Adams",
      "email": "[email protected]",
      "role": "administrator",
      "schedulable": true,
      "two_factor_enabled": true,
      "url_slug": "derryn-adams",
      "created_at": 1692173112,
      "updated_at": 1692173112
    }
  ]
}