appointments_getlist

Retrieve a list of appointments from ServiceTitan filtered by criteria like date, customer, job, status, or technician. Supports pagination, sorting, and optional total count inclusion.

Input Schema

Name	Required	Description
`createdBefore`	No	Format - date-time (as date-time in RFC3339). Return appointments created before a certain date/time (in UTC)
`createdOnOrAfter`	No	Format - date-time (as date-time in RFC3339). Return appointments created on or after a certain date/time (in UTC)
`customerId`	No	Format - int64. Return appointments for the specified Customer
`ids`	No	Perform lookup by multiple IDs (maximum 50)
`includeTotal`	No	Whether total count should be returned
`jobId`	No	Format - int64. Return all appointments for this job
`modifiedBefore`	No	Format - date-time (as date-time in RFC3339). Return appointments modified before a certain date/time (in UTC)
`modifiedOnOrAfter`	No	Format - date-time (as date-time in RFC3339). Return appointments modified on or after a certain date/time (in UTC)
`number`	No	Return all appointments with this appointment number
`page`	No	Format - int32. The logical number of page to return, starting from 1
`pageSize`	No	Format - int32. How many records to return (50 by default)
`projectId`	No	Format - int64. Return all appointments for jobs that are part of this project
`sort`	No	Applies sorting by the specified field: "?sort=+FieldName" for ascending order, "?sort=-FieldName" for descending order. Available fields are: Id, ModifiedOn, CreatedOn.
`startsBefore`	No	Format - date-time (as date-time in RFC3339). Return appointments that start before the specified date/time (in UTC)
`startsOnOrAfter`	No	Format - date-time (as date-time in RFC3339). Return appointments that start on or after the specified date/time (in UTC)
`status`	No	Return items with specified status AppointmentStatus Values: [Scheduled, Dispatched, Working, Hold, Done, Canceled]
`technicianId`	No	Format - int64. Return appointments this technician is assigned to
`tenant`	Yes	Format - int64. Tenant ID
`unused`	No	Return appointments that are unused

Input Schema (JSON Schema)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "createdBefore": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - date-time (as date-time in RFC3339). Return appointments created before a certain date/time (in UTC)"
    },
    "createdOnOrAfter": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - date-time (as date-time in RFC3339). Return appointments created on or after a certain date/time (in UTC)"
    },
    "customerId": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - int64. Return appointments for the specified Customer"
    },
    "ids": {
      "description": "Perform lookup by multiple IDs (maximum 50)",
      "type": [
        "string",
        "null"
      ]
    },
    "includeTotal": {
      "description": "Whether total count should be returned",
      "type": [
        "boolean",
        "null"
      ]
    },
    "jobId": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - int64. Return all appointments for this job"
    },
    "modifiedBefore": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - date-time (as date-time in RFC3339). Return appointments modified before a certain date/time (in UTC)"
    },
    "modifiedOnOrAfter": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - date-time (as date-time in RFC3339). Return appointments modified on or after a certain date/time (in UTC)"
    },
    "number": {
      "description": "Return all appointments with this appointment number",
      "type": [
        "string",
        "null"
      ]
    },
    "page": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - int32. The logical number of page to return, starting from 1"
    },
    "pageSize": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - int32. How many records to return (50 by default)"
    },
    "projectId": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - int64. Return all appointments for jobs that are part of this project"
    },
    "sort": {
      "description": "Applies sorting by the specified field:\n\"?sort=+FieldName\" for ascending order,\n\"?sort=-FieldName\" for descending order.\n\nAvailable fields are: Id, ModifiedOn, CreatedOn.",
      "type": [
        "string",
        "null"
      ]
    },
    "startsBefore": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - date-time (as date-time in RFC3339). Return appointments that start before the specified date/time (in UTC)"
    },
    "startsOnOrAfter": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - date-time (as date-time in RFC3339). Return appointments that start on or after the specified date/time (in UTC)"
    },
    "status": {
      "description": "Return items with specified status AppointmentStatus\nValues: [Scheduled, Dispatched, Working, Hold, Done, Canceled]",
      "type": [
        "string",
        "null"
      ]
    },
    "technicianId": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Format - int64. Return appointments this technician is assigned to"
    },
    "tenant": {
      "description": "Format - int64. Tenant ID",
      "type": "integer"
    },
    "unused": {
      "description": "Return appointments that are unused",
      "type": [
        "boolean",
        "null"
      ]
    }
  },
  "required": [
    "tenant"
  ],
  "type": "object"
}

ServiceTitan MCP Server

appointments_getlist

Input Schema

Input Schema (JSON Schema)

Other Tools from ServiceTitan MCP Server

Related Tools