openapi: 3.1.0
info:
  title: Housecall Pro Public API
  version: '1.0'
  description: |
    The Housecall Pro Public API exposes core resources of the Housecall Pro home services
    business management platform — customers, leads, jobs, estimates, invoices, payments,
    employees, schedule items, line items, and webhooks. The API is available to Pros on
    the MAX plan and is documented on Stoplight at https://docs.housecallpro.com/.
  contact:
    name: Housecall Pro
    url: https://www.housecallpro.com
  license:
    name: Proprietary
servers:
  - url: https://api.housecallpro.com
    description: Production
security:
  - bearerAuth: []
  - apiKey: []
tags:
  - name: Customers
  - name: Leads
  - name: Jobs
  - name: Estimates
  - name: Invoices
  - name: Payments
  - name: Employees
  - name: Companies
  - name: Schedule Items
  - name: Line Items
  - name: Webhooks
paths:
  /customers:
    get:
      tags: [Customers]
      summary: List Customers
      operationId: listCustomers
      parameters:
        - name: page
          in: query
          schema: { type: integer }
        - name: page_size
          in: query
          schema: { type: integer }
        - name: q
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Customer collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items: { $ref: '#/components/schemas/Customer' }
    post:
      tags: [Customers]
      summary: Create Customer
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Customer' }
      responses:
        '201': { description: Customer created. }
  /customers/{customer_id}:
    get:
      tags: [Customers]
      summary: Get Customer
      operationId: getCustomer
      parameters:
        - name: customer_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Single customer.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Customer' }
    put:
      tags: [Customers]
      summary: Update Customer
      operationId: updateCustomer
      parameters:
        - { name: customer_id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Customer' }
      responses:
        '200': { description: Customer updated. }
    delete:
      tags: [Customers]
      summary: Delete Customer
      operationId: deleteCustomer
      parameters:
        - { name: customer_id, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: Customer deleted. }
  /leads:
    get:
      tags: [Leads]
      summary: List Leads
      operationId: listLeads
      responses:
        '200': { description: Lead collection. }
    post:
      tags: [Leads]
      summary: Create Lead
      operationId: createLead
      responses:
        '201': { description: Lead created. }
  /jobs:
    get:
      tags: [Jobs]
      summary: List Jobs
      operationId: listJobs
      parameters:
        - { name: page, in: query, schema: { type: integer } }
        - { name: page_size, in: query, schema: { type: integer } }
        - { name: scheduled_start_min, in: query, schema: { type: string, format: date-time } }
        - { name: scheduled_start_max, in: query, schema: { type: string, format: date-time } }
        - { name: customer_id, in: query, schema: { type: string } }
        - { name: employee_ids, in: query, schema: { type: array, items: { type: string } } }
      responses:
        '200':
          description: Job collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items: { $ref: '#/components/schemas/Job' }
    post:
      tags: [Jobs]
      summary: Create Job
      operationId: createJob
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Job' }
      responses:
        '201': { description: Job created. }
  /jobs/{job_id}:
    get:
      tags: [Jobs]
      summary: Get Job
      operationId: getJob
      parameters:
        - { name: job_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Single job.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
    put:
      tags: [Jobs]
      summary: Update Job
      operationId: updateJob
      parameters:
        - { name: job_id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Job updated. }
    delete:
      tags: [Jobs]
      summary: Delete Job
      operationId: deleteJob
      parameters:
        - { name: job_id, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: Job deleted. }
  /jobs/{job_id}/line_items:
    get:
      tags: [Line Items]
      summary: List Job Line Items
      operationId: listJobLineItems
      parameters:
        - { name: job_id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Line item collection. }
    post:
      tags: [Line Items]
      summary: Create Job Line Item
      operationId: createJobLineItem
      parameters:
        - { name: job_id, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Line item created. }
  /jobs/{job_id}/appointments:
    get:
      tags: [Schedule Items]
      summary: List Job Appointments
      operationId: listJobAppointments
      parameters:
        - { name: job_id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Appointment collection. }
  /estimates:
    get:
      tags: [Estimates]
      summary: List Estimates
      operationId: listEstimates
      responses:
        '200':
          description: Estimate collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  estimates:
                    type: array
                    items: { $ref: '#/components/schemas/Estimate' }
    post:
      tags: [Estimates]
      summary: Create Estimate
      operationId: createEstimate
      responses:
        '201': { description: Estimate created. }
  /estimates/{estimate_id}:
    get:
      tags: [Estimates]
      summary: Get Estimate
      operationId: getEstimate
      parameters:
        - { name: estimate_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Single estimate.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Estimate' }
  /invoices:
    get:
      tags: [Invoices]
      summary: List Invoices
      operationId: listInvoices
      responses:
        '200':
          description: Invoice collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items: { $ref: '#/components/schemas/Invoice' }
    post:
      tags: [Invoices]
      summary: Create Invoice
      operationId: createInvoice
      responses:
        '201': { description: Invoice created. }
  /invoices/{invoice_id}:
    get:
      tags: [Invoices]
      summary: Get Invoice
      operationId: getInvoice
      parameters:
        - { name: invoice_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Single invoice.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Invoice' }
  /invoices/{invoice_id}/payments:
    get:
      tags: [Payments]
      summary: List Invoice Payments
      operationId: listInvoicePayments
      parameters:
        - { name: invoice_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Payment collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    items: { $ref: '#/components/schemas/Payment' }
  /employees:
    get:
      tags: [Employees]
      summary: List Employees
      operationId: listEmployees
      responses:
        '200':
          description: Employee collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  employees:
                    type: array
                    items: { $ref: '#/components/schemas/Employee' }
  /employees/{employee_id}:
    get:
      tags: [Employees]
      summary: Get Employee
      operationId: getEmployee
      parameters:
        - { name: employee_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Single employee.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Employee' }
  /companies:
    get:
      tags: [Companies]
      summary: List Companies
      operationId: listCompanies
      responses:
        '200': { description: Company collection. }
  /webhooks:
    get:
      tags: [Webhooks]
      summary: List Webhook Subscriptions
      operationId: listWebhooks
      responses:
        '200': { description: Webhook collection. }
    post:
      tags: [Webhooks]
      summary: Create Webhook Subscription
      operationId: createWebhook
      responses:
        '201': { description: Webhook subscription created. }
  /webhooks/{webhook_id}:
    delete:
      tags: [Webhooks]
      summary: Delete Webhook Subscription
      operationId: deleteWebhook
      parameters:
        - { name: webhook_id, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: Webhook deleted. }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer token using the API key generated from the MAX-plan App Store API card.
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key passed as `Authorization: Token {key}`.
  schemas:
    Customer:
      type: object
      properties:
        id: { type: string }
        first_name: { type: string }
        last_name: { type: string }
        email: { type: string, format: email }
        mobile_number: { type: string }
        home_number: { type: string }
        work_number: { type: string }
        company: { type: string }
        notifications_enabled: { type: boolean }
        lead_source: { type: string }
        tags:
          type: array
          items: { type: string }
        addresses:
          type: array
          items: { $ref: '#/components/schemas/Address' }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    Address:
      type: object
      properties:
        id: { type: string }
        type: { type: string, enum: [billing, service] }
        street: { type: string }
        street_line_2: { type: string }
        city: { type: string }
        state: { type: string }
        zip: { type: string }
        country: { type: string }
    Job:
      type: object
      properties:
        id: { type: string }
        invoice_number: { type: string }
        description: { type: string }
        customer: { $ref: '#/components/schemas/Customer' }
        address: { $ref: '#/components/schemas/Address' }
        notes: { type: string }
        work_status: { type: string, enum: [unscheduled, scheduled, in_progress, complete, completed_unrated, user_canceled, pro_canceled] }
        work_timestamps:
          type: object
          properties:
            on_my_way_at: { type: string, format: date-time }
            started_at: { type: string, format: date-time }
            completed_at: { type: string, format: date-time }
        schedule:
          type: object
          properties:
            scheduled_start: { type: string, format: date-time }
            scheduled_end: { type: string, format: date-time }
            arrival_window: { type: integer }
        total_amount: { type: integer, description: Amount in cents. }
        outstanding_balance: { type: integer }
        assigned_employees:
          type: array
          items: { $ref: '#/components/schemas/Employee' }
        tags:
          type: array
          items: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    Estimate:
      type: object
      properties:
        id: { type: string }
        estimate_number: { type: string }
        work_status: { type: string }
        customer: { $ref: '#/components/schemas/Customer' }
        address: { $ref: '#/components/schemas/Address' }
        total_amount: { type: integer }
        approval_status: { type: string, enum: [pro_approved, customer_approved, declined, pending] }
        options:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              name: { type: string }
              total_amount: { type: integer }
        created_at: { type: string, format: date-time }
    Invoice:
      type: object
      properties:
        id: { type: string }
        invoice_number: { type: string }
        status: { type: string, enum: [draft, sent, paid, voided, canceled] }
        amount: { type: integer }
        outstanding_balance: { type: integer }
        customer_id: { type: string }
        job_id: { type: string }
        due_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
    Payment:
      type: object
      properties:
        id: { type: string }
        invoice_id: { type: string }
        amount: { type: integer }
        payment_method: { type: string, enum: [cash, check, credit_card, ach, other] }
        status: { type: string, enum: [succeeded, pending, failed, refunded] }
        processed_at: { type: string, format: date-time }
    Employee:
      type: object
      properties:
        id: { type: string }
        first_name: { type: string }
        last_name: { type: string }
        email: { type: string, format: email }
        mobile_number: { type: string }
        role: { type: string, enum: [admin, office_staff, field_tech] }
        color_hex: { type: string }
        avatar_url: { type: string }
        permissions:
          type: object
          additionalProperties: { type: boolean }