Appointments

Manage scheduled service appointments for customers

Overview

Appointments represent scheduled service visits. They can be assigned to technicians, linked to customers, and include multiple services. Appointments track status from scheduling through completion.

List Appointments

Retrieve a paginated list of appointments with optional filtering.

query PaginatedAppointments($page: Int!, $limit: Int!, $selector: AppointmentsSelector) {
  paginatedAppointments(page: $page, limit: $limit, selector: $selector) {
    edges {
      node {
        id
        title
        scheduledAt
        status
        customer {
          id
          firstName
          lastName
        }
        assignedTo {
          id
          firstName
          lastName
        }
      }
    }
    pagination {
      total
      page
      limit
      totalPages
    }
  }
}

# Variables
{
  "page": 1,
  "limit": 20,
  "selector": {
    "filters": {
      "status": { "eq": "SCHEDULED" },
      "scheduledAt": { "gte": "2024-01-01T00:00:00Z" }
    }
  }
}

Response:

{
  "data": {
    "paginatedAppointments": {
      "edges": [
        {
          "node": {
            "id": "apt_123",
            "title": "Weekly Pool Service",
            "scheduledAt": "2024-01-15T09:00:00Z",
            "status": "SCHEDULED",
            "customer": {
              "id": "cust_456",
              "firstName": "John",
              "lastName": "Smith"
            },
            "assignedTo": {
              "id": "user_789",
              "firstName": "Mike",
              "lastName": "Johnson"
            }
          }
        }
      ],
      "pagination": {
        "total": 45,
        "page": 1,
        "limit": 20,
        "totalPages": 3
      }
    }
  }
}

Get Single Appointment

Retrieve a single appointment by ID using a selector filter.

query Appointment($page: Int!, $limit: Int!, $selector: AppointmentsSelector!) {
  paginatedAppointments(page: $page, limit: $limit, selector: $selector) {
    edges {
      node {
        id
        title
        description
        scheduledAt
        duration
        status
        customer {
          id
          firstName
          lastName
          email
          phone
        }
        assignedTo {
          id
          firstName
          lastName
        }
        services {
          id
          name
          price
        }
        address {
          street
          city
          state
          zipCode
        }
        notes
        createdAt
        updatedAt
      }
    }
  }
}

# Variables
{
  "page": 1,
  "limit": 1,
  "selector": {
    "filters": {
      "id": { "eq": "apt_123" }
    }
  }
}

Response:

{
  "data": {
    "paginatedAppointments": {
      "edges": [
        {
          "node": {
            "id": "apt_123",
            "title": "Weekly Pool Service",
            "description": "Regular maintenance visit",
            "scheduledAt": "2024-01-15T09:00:00Z",
            "duration": 60,
            "status": "SCHEDULED",
            "customer": {
              "id": "cust_456",
              "firstName": "John",
              "lastName": "Smith",
              "email": "john@example.com",
              "phone": "555-0123"
            },
            "assignedTo": {
              "id": "user_789",
              "firstName": "Mike",
              "lastName": "Johnson"
            },
            "services": [
              {
                "id": "svc_001",
                "name": "Pool Cleaning",
                "price": 75.00
              }
            ],
            "address": {
              "street": "123 Main St",
              "city": "Austin",
              "state": "TX",
              "zipCode": "78701"
            },
            "notes": null,
            "createdAt": "2024-01-01T10:00:00Z",
            "updatedAt": "2024-01-01T10:00:00Z"
          }
        }
      ]
    }
  }
}

Create Appointment

Create a new appointment for a customer.

mutation CreateAppointment($input: CreateAppointmentInput!) {
  createAppointment(input: $input) {
    id
    title
    scheduledAt
    status
    customer {
      id
      firstName
      lastName
    }
  }
}

# Variables
{
  "input": {
    "title": "Pool Inspection",
    "description": "Annual pool inspection",
    "customerId": "cust_456",
    "scheduledAt": "2024-02-01T10:00:00Z",
    "duration": 90,
    "assignedToId": "user_789",
    "serviceIds": ["svc_001", "svc_002"]
  }
}

Response:

{
  "data": {
    "createAppointment": {
      "id": "apt_124",
      "title": "Pool Inspection",
      "scheduledAt": "2024-02-01T10:00:00Z",
      "status": "SCHEDULED",
      "customer": {
        "id": "cust_456",
        "firstName": "John",
        "lastName": "Smith"
      }
    }
  }
}

Update Appointment

Update an existing appointment.

mutation UpdateAppointment($id: ID!, $input: UpdateAppointmentInput!) {
  updateAppointment(id: $id, input: $input) {
    id
    title
    scheduledAt
    status
    updatedAt
  }
}

# Variables
{
  "id": "apt_123",
  "input": {
    "status": "IN_PROGRESS",
    "notes": "Technician on site"
  }
}

Response:

{
  "data": {
    "updateAppointment": {
      "id": "apt_123",
      "title": "Weekly Pool Service",
      "scheduledAt": "2024-01-15T09:00:00Z",
      "status": "IN_PROGRESS",
      "updatedAt": "2024-01-15T09:15:00Z"
    }
  }
}

Delete Appointment

Delete an appointment. This performs a soft delete.

mutation DeleteAppointment($id: ID!) {
  deleteAppointment(id: $id) {
    success
    message
  }
}

# Variables
{
  "id": "apt_123"
}

Response:

{
  "data": {
    "deleteAppointment": {
      "success": true,
      "message": "Appointment deleted successfully"
    }
  }
}

REST Endpoints

Export appointments to CSV or PDF format.

GET/appointments/export/csv

Export appointments to CSV format

curl -X GET "https://api.poolservicemanager.com/appointments/export/csv?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o appointments.csv

GET/appointments/export/pdf

Export appointments schedule as PDF

curl -X GET "https://api.poolservicemanager.com/appointments/export/pdf?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o appointments.pdf

Field Reference

Field	Type	Description
`id`	`ID!`	Unique identifier
`title`	`String`(nullable)	Appointment title
`description`	`String`(nullable)	Detailed description
`scheduledAt`	`DateTime!`	Scheduled date and time
`duration`	`Int`(nullable)	Duration in minutes
`status`	`AppointmentStatus!`	Current status (SCHEDULED, IN_PROGRESS, COMPLETED, CANCELLED)
`customer`	`Customer`(nullable)	Associated customer
`assignedTo`	`User`(nullable)	Assigned technician
`services`	`[Service!]!`	Services included in appointment
`address`	`Address`(nullable)	Service location
`notes`	`String`(nullable)	Internal notes
`createdAt`	`DateTime!`	Creation timestamp
`updatedAt`	`DateTime!`	Last update timestamp