HouseCall Pro Jobs API Integration

This project provides a comprehensive API integration with HouseCall Pro to fetch jobs data. It includes a reusable TypeScript module and an HTTP endpoint for easy access to jobs information.

1. Log into your HouseCall Pro account
2. Go to Settings > Integrations > API
3. Generate or copy your API key

In Val Town, set your environment variable:

• Key: HOUSECALL_PRO_API_KEY
• Value: Your HouseCall Pro API key

• housecall-pro-api.ts: Core API module with TypeScript types and functions
• main.ts: HTTP endpoint for accessing the API
• README.md: This documentation

• GET / or GET /jobs: Get jobs with optional query parameters
• GET /jobs/today: Get jobs scheduled for today
• GET /jobs/this-week: Get jobs scheduled for this week
• GET /jobs/status/{status}: Get jobs by specific status
• GET /docs or GET /help: API documentation

• needs_scheduling
• scheduled
• in_progress
• completed
• canceled

• page: Page number (default: 1)
• page_size: Items per page (default: 50, max: 100)
• get_all: Set to 'true' to fetch all jobs across all pages

• work_status: Filter by work status
• employee_ids: Comma-separated employee IDs
• customer_ids: Comma-separated customer IDs
• address_city: Filter by city
• address_state: Filter by state
• address_zip: Filter by ZIP code
• tags: Comma-separated tags
• lead_source: Filter by lead source
• business_unit_id: Filter by business unit ID

• scheduled_start_min: Minimum scheduled start date
• scheduled_start_max: Maximum scheduled start date
• scheduled_end_min: Minimum scheduled end date
• scheduled_end_max: Maximum scheduled end date
• created_min: Minimum created date
• created_max: Maximum created date
• updated_min: Minimum updated date
• updated_max: Maximum updated date

• sort: Sort field (created_at, updated_at, scheduled_start, scheduled_end)
• sort_direction: Sort direction (asc, desc)

# Get first 10 jobs
GET /?page_size=10

# Get completed jobs
GET /?work_status=completed

# Get jobs for specific employee
GET /?employee_ids=emp_123

# Get jobs in New York
GET /?address_city=New York

# Get jobs scheduled for January 2024
GET /?scheduled_start_min=2024-01-01&scheduled_start_max=2024-01-31

# Get all jobs (across all pages)
GET /?get_all=true

# Get today's jobs
GET /jobs/today

# Get this week's jobs
GET /jobs/this-week

# Get scheduled jobs
GET /jobs/status/scheduled

import { getHouseCallProJobs, getJobsByDateRange, getJobsByStatus, getAllJobs } from './housecall-pro-api.ts';

// Get jobs with custom parameters
const jobs = await getHouseCallProJobs({
  page: 1,
  page_size: 50,
  work_status: 'scheduled',
  address_city: 'New York'
});

// Get jobs for a date range
const jobsInRange = await getJobsByDateRange('2024-01-01', '2024-01-31');

// Get jobs by status
const completedJobs = await getJobsByStatus('completed');

// Get all jobs (handles pagination automatically)
const allJobs = await getAllJobs({
  work_status: 'scheduled'
});

The API returns jobs data in the following format:

{
  "jobs": [
    {
      "id": "job_123",
      "number": "12345",
      "customer": {
        "id": "cust_456",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "mobile_number": "+1234567890",
        "company": "Acme Corp"
      },
      "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "start_date": "2024-01-15T09:00:00Z",
      "end_date": "2024-01-15T17:00:00Z",
      "work_status": "scheduled",
      "total_amount": 250.00,
      "outstanding_balance": 0.00,
      "assigned_employees": [
        {
          "id": "emp_789",
          "first_name": "Jane",
          "last_name": "Smith"
        }
      ],
      "tags": ["plumbing", "emergency"],
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-12T14:30:00Z"
    }
  ],
  "total_items": 150,
  "total_pages": 3,
  "page_number": 1,
  "page_size": 50
}

The API includes comprehensive error handling:

• 401 Unauthorized: Invalid or missing API key
• 400 Bad Request: Invalid parameters
• 404 Not Found: Invalid endpoint
• 500 Internal Server Error: API or network errors

All errors return JSON with error details:

{
  "error": "Error message",
  "type": "ErrorType",
  "timestamp": "2024-01-15T10:00:00Z"
}

• ✅ Full TypeScript support with proper interfaces
• ✅ Comprehensive query parameter support
• ✅ Pagination handling (manual and automatic)
• ✅ Date range filtering
• ✅ Multiple filtering options
• ✅ Helper functions for common use cases
• ✅ Error handling and validation
• ✅ Built-in API documentation
• ✅ Special endpoints for common queries

The code is structured for easy maintenance and extension:

• Type Safety: Full TypeScript interfaces for all API responses
• Modular Design: Separate API module for reuse in other projects
• Helper Functions: Convenient functions for common operations
• Error Handling: Comprehensive error catching and reporting
• Documentation: Built-in API documentation endpoint

1. Set your HOUSECALL_PRO_API_KEY environment variable
2. Test the API endpoints
3. Customize the filtering and parameters as needed
4. Integrate with your application or workflow

For more information about the HouseCall Pro API, visit: https://docs.housecallpro.com/docs/housecall-public-api/