Housecall Pro Operation Actor

One-shot Pattern-A Apify Actor that executes exactly one Housecall Pro operation per run, pushes structured output to dataset, and exits.

MCP Client Instructions (Claude, Codex, OpenClaw, etc.)

• Always pass operation as the exact registered tool name with the hcp_ prefix.
• Valid example: hcp_get_customers
• Invalid alias example: get_customers
• Send operation arguments only inside args as a JSON object.
• After the actor run completes, read full results using get-actor-output with the returned datasetId from the actor call response.
• Do not rely on output preview alone, because previews can be truncated.

Authentication

• Required input field: hcpApiKey (stored as an Apify secret input)
• Optional input companyId is sent as X-Company-Id header on all API calls

Input Model

Required:

• hcpApiKey (Housecall Pro API key)
• companyTimezone (IANA timezone, validated on startup)

Optional:

• operation (AI/integration-supplied operation name for the run, for example hcp_get_jobs)
• companyId (adds X-Company-Id header)
• args (JSON object passed directly to the selected operation handler)

Important:

• operation must start with hcp_ and match a real operation name exactly.
• The actor validates operation names strictly and returns an error for unknown operations.

Example:

{
  "hcpApiKey": "your_hcp_api_key",
  "companyTimezone": "America/Los_Angeles",
  "operation": "hcp_get_jobs",
  "args": {
    "page": 1,
    "page_size": 10,
    "sort_by": "created_at",
    "sort_direction": "desc"
  }
}

Categories and Example Operations

• Customers: hcp_get_customers, hcp_create_customer
• Jobs: hcp_get_jobs, hcp_create_job, hcp_update_job_schedule
• Job Appointments: hcp_get_job_appointments, hcp_create_job_appointment
• Estimates: hcp_get_estimates, hcp_create_estimate
• Leads: hcp_get_leads, hcp_create_lead, hcp_convert_lead
• Invoices: hcp_get_invoices, hcp_get_invoice, hcp_preview_invoice
• Additional categories: Employees, Tags, Job Types, Price Book Services, Material Categories, Materials, Schedule, Events, Webhooks, Checklists, Job Invoices, Lead Sources, Lead Line Items

Charging Model

• Uses Apify pay-per-event configuration from .actor/pay_per_event.json
• Event price is $0.01 for each GET/POST/PUT/DELETE tool call
• Auto-pagination tools charge once per page fetched (not once per high-level operation request)

Destructive Confirmation Pattern

Delete-style tools follow a two-step safety flow:

1. First call without confirm: true returns a warning preview
2. Second call with confirm: true executes deletion and charges the delete event

Output

Each run pushes one dataset item:

• metadata: operation, companyTimezone, companyIdUsed, credentialSource
• result: parsed JSON when possible, otherwise plain text
• rawCallToolResult: raw MCP-style call result payload

For MCP integrations:

• Actor call responses may include an output preview only.
• Use datasetId from the actor call response with get-actor-output to retrieve complete output.