Customers

Manage customer information and relationships

Overview

Customers are the core entity representing clients who receive pool services. They can be residential or commercial, and include contact information, service addresses, and billing details.

List Customers

Retrieve a paginated list of customers with optional filtering and search.

query InfiniteCustomers($first: Int!, $after: String, $filter: CustomerFilter, $search: String) {
  infiniteCustomers(first: $first, after: $after, filter: $filter, search: $search) {
    edges {
      node {
        id
        firstName
        lastName
        email
        phone
        status
        street
        city
        state
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

# Variables
{
  "first": 20,
  "search": "Smith",
  "filter": {
    "status": "ACTIVE"
  }
}

Response:

{
  "data": {
    "infiniteCustomers": {
      "edges": [
        {
          "node": {
            "id": "cust_456",
            "firstName": "John",
            "lastName": "Smith",
            "email": "john@example.com",
            "phone": "555-0123",
            "status": "ACTIVE",
            "street": "123 Main St",
            "city": "Austin",
            "state": "TX"
          },
          "cursor": "eyJpZCI6ImN1c3RfNDU2In0="
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6ImN1c3RfNDU2In0="
      },
      "totalCount": 150
    }
  }
}

Get Single Customer

Retrieve a single customer by ID.

query Customer($selector: CustomerSelector!) {
  customer(selector: $selector) {
    id
    firstName
    lastName
    email
    phone
    mobilePhone
    companyName
    street
    city
    state
    zipCode
    status
    tags {
      id
      name
      color
    }
    notes
    quickbooksId
    createdAt
    updatedAt
  }
}

# Variables
{
  "selector": {
    "id": "cust_456"
  }
}

Response:

{
  "data": {
    "customer": {
      "id": "cust_456",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john@example.com",
      "phone": "555-0123",
      "mobilePhone": "555-0124",
      "companyName": null,
      "street": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "status": "ACTIVE",
      "tags": [
        {
          "id": "tag_001",
          "name": "Premium",
          "color": "#4F46E5"
        }
      ],
      "notes": "Prefers morning appointments",
      "quickbooksId": "QB-12345",
      "createdAt": "2023-06-15T10:00:00Z",
      "updatedAt": "2024-01-10T14:30:00Z"
    }
  }
}

Create Customer

Create a new customer record.

mutation CreateCustomer($input: CreateCustomerInput!) {
  createCustomer(input: $input) {
    id
    firstName
    lastName
    email
    status
    createdAt
  }
}

# Variables
{
  "input": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "555-0200",
    "street": "456 Oak Ave",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78702",
    "status": "ACTIVE",
    "tagIds": ["tag_001"]
  }
}

Response:

{
  "data": {
    "createCustomer": {
      "id": "cust_457",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "status": "ACTIVE",
      "createdAt": "2024-01-20T09:00:00Z"
    }
  }
}

Update Customer

Update an existing customer.

mutation UpdateCustomer($id: ID!, $input: UpdateCustomerInput!) {
  updateCustomer(id: $id, input: $input) {
    id
    firstName
    lastName
    email
    phone
    status
    updatedAt
  }
}

# Variables
{
  "id": "cust_456",
  "input": {
    "phone": "555-0999",
    "notes": "Updated contact preference: email only"
  }
}

Response:

{
  "data": {
    "updateCustomer": {
      "id": "cust_456",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john@example.com",
      "phone": "555-0999",
      "status": "ACTIVE",
      "updatedAt": "2024-01-20T10:30:00Z"
    }
  }
}

Bulk Operations

Perform bulk updates on multiple customers.

mutation BulkUpdateCustomers($input: BulkUpdateCustomersInput!) {
  bulkUpdateCustomers(input: $input) {
    success
    updatedCount
    errors {
      id
      message
    }
  }
}

# Variables
{
  "input": {
    "ids": ["cust_456", "cust_457", "cust_458"],
    "update": {
      "status": "INACTIVE"
    }
  }
}

Response:

{
  "data": {
    "bulkUpdateCustomers": {
      "success": true,
      "updatedCount": 3,
      "errors": []
    }
  }
}

REST Endpoints

Export customers to CSV format.

GET/customers/export/csv

Export all customers to CSV format

curl -X GET "https://api.poolservicemanager.com/customers/export/csv?status=ACTIVE" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o customers.csv

GET/customers/:id/pricing/csv

Export customer-specific pricing to CSV

curl -X GET "https://api.poolservicemanager.com/customers/cust_456/pricing/csv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o customer-pricing.csv

Field Reference

Field	Type	Description
`id`	`ID!`	Unique identifier
`firstName`	`String`(nullable)	Customer's first name
`lastName`	`String`(nullable)	Customer's last name
`email`	`String`(nullable)	Email address
`phone`	`String`(nullable)	Primary phone number
`mobilePhone`	`String`(nullable)	Mobile phone number
`companyName`	`String`(nullable)	Business name (for commercial customers)
`street`	`String`(nullable)	Street address
`city`	`String`(nullable)	City
`state`	`String`(nullable)	State/Province
`zipCode`	`String`(nullable)	Postal code
`status`	`CustomerStatus!`	Status (ACTIVE, INACTIVE, LEAD)
`tags`	`[Tag!]!`	Associated tags for categorization
`notes`	`String`(nullable)	Internal notes
`quickbooksId`	`String`(nullable)	QuickBooks customer ID
`createdAt`	`DateTime!`	Creation timestamp
`updatedAt`	`DateTime!`	Last update timestamp