Housecall Pro

What this is

Housecall Pro is a field-service management platform popular with home-service businesses (plumbing, HVAC, electrical, etc.). LeadRails creates a new customer in HCP for each lead, optionally tagging the customer with a Lead Source string. From there your HCP workflow takes over: estimates, scheduling, dispatch.

Where to find your API key

1. Sign in to housecallpro.com as an admin.
2. Click your name (top right) → "My Profile".
3. Scroll to the "Integrations" section.
4. Locate "API Token" — click "Generate" if none exists, or "Reveal" if one already does.
5. Copy the token immediately — HCP doesn't show it again after you navigate away.
6. If your account has multiple users with API access, label the token with what it's for (e.g. "LeadRails").

Permission scopes

The API token inherits permissions from the user who generated it. For LeadRails, that means: the user needs the "Create Customer" permission. Account owners and admins have this by default.

Set up your destination in LeadRails

1. Sign in → Destinations → New.
2. Adapter type: Housecall Pro.
3. API Key: paste your token.
4. Lead Source (optional): a string that gets attached to every customer LeadRails creates (e.g. "Website form", "Google Ads"). Useful for filtering in HCP reports — without it, leads appear unattributed.
5. Click Create.

Confirm credentials work (without creating test data)

1. Open the destination → Advanced → Verify connection.
2. LeadRails hits HCP's /company endpoint, which returns 200 if the token is valid (no real lead created).
3. Green checkmark = ready to go.

Send a test lead

1. Sources → your source → Settings → ensure a route exists from this source to your HCP destination.
2. Click "Send test event".
3. A test customer ("Test Lead" with email test+leadrails@example.com) appears in your HCP customer list within seconds.
4. Result panel deep-links to the Jobs page for delivery confirmation.
5. Clean up the test customer in HCP after verifying.

Customer record shape

• Default mapping: lead name → customer first_name + last_name (split on first space), email → customer email, phone → customer mobile_number, lead_source field → customer lead_source tag (if configured).
• Additional fields (company, notes) can be added via per-route mapping in LeadRails Routes → Mapping editor.

Common issues

401 "Invalid API token"

Token was revoked or the generating user lost API access. Generate a fresh one.

403 "Permission denied"

Token user lacks "Create Customer" permission. Promote the user or use an admin's token.

422 "Duplicate customer"

A customer with that email already exists in HCP. HCP enforces email uniqueness. LeadRails treats this as a permanent_failure — review whether you want duplicates merged.

Phone format errors

HCP expects US-formatted phone numbers. International leads may need format normalization via per-route mapping.

Lead Source not showing in reports

Verify the Lead Source string EXACTLY matches an existing value in HCP, OR is a brand-new string HCP auto-adds to its picklist.

Housecall Pro API limits

• Free HCP accounts have stricter API rate limits. If you're routing >1000 leads/day, talk to HCP about a higher tier.
• LeadRails respects HCP's Retry-After header on 429s and backs off automatically.