Housecall Pro

What this is

Housecall Pro is a field-service tool popular with home-service businesses. Plumbers, HVAC, electrical, and the like. LeadRails creates a new lead in Housecall Pro for each lead you send it. The lead carries a customer (name, email, mobile number), an optional address, an optional source label, and any notes from the form. From there your Housecall Pro process takes over: estimates, scheduling, dispatch.

Where to find your API token

1. Sign in to housecallpro.com as an admin.
2. Click your name (top right), then "My Profile".
3. Scroll to the "Integrations" section.
4. Find "API Token". Click "Generate" if none exists, or "Reveal" if one already does.
5. Copy the token right away. Housecall Pro doesn't show it again after you navigate away.

The token inherits the creating user's permissions

A Housecall Pro API token carries the exact permissions of the user who generated it. LeadRails creates leads, so that user needs the "Create Customer" permission. Account owners and admins have it by default. If you generate the token from a restricted user, LeadRails can still connect but deliveries fail. Generate the token from an admin to avoid that.

Set up your destination in LeadRails

1. Sign in, then Destinations, then New.
2. Adapter type: Housecall Pro.
3. API Token: paste your token.
4. Lead Source (optional): a label attached to every lead LeadRails creates, like "Website form" or "Google Ads". Handy for filtering in Housecall Pro reports. Leave it blank and LeadRails falls through to the lead's own UTM source.
5. Assigned Employee ID (optional): the Housecall Pro employee id to assign every lead to. You'll find it in the URL when you open that employee in Housecall Pro.
6. Default Tags (optional): comma-separated tags added to every lead, like website, hot-lead.
7. Click Create.

Confirm your token works (without creating test data)

1. Open the destination, then Advanced, then Verify connection.
2. LeadRails reads Housecall Pro's /company endpoint. It never creates a lead, so nothing lands in your account.
3. Green checkmark: the token is live and authorized on your account.

Verify tells you three different things apart:

• Token valid (200): LeadRails connected and reads your company. Good to go.
• Token rejected (401): the token is wrong, expired, or revoked. Generate a new one and update the destination.
• Token valid but under-permissioned (403): the token is real, but the user who created it lacks the permission LeadRails needs. This is the case that looks fine at a glance but drops leads at delivery. Regenerate the token from an admin user with the "Create Customer" permission.

Verify never asks for more than delivery does. If Verify passes, delivery has the access it needs.

Send a test lead

1. Sources, then your source, then Settings. Make sure a route exists from this source to your Housecall Pro destination.
2. Click "Send test event".
3. A test lead appears in Housecall Pro within seconds.
4. The Deliveries view shows the result, including the created lead's id.
5. Delete the test lead in Housecall Pro once you've confirmed it arrived.

What LeadRails sends

• Default mapping: lead name becomes the customer first_name and last_name (split on the first space), email becomes the customer email, and phone becomes the customer mobile_number.
• Address fields (street, city, state, zip) are included when the lead has them, and skipped entirely when it doesn't.
• The form message becomes a note on the lead (trimmed to 2000 characters).
• Your Lead Source, Assigned Employee ID, and Default Tags are attached when set.
• Need a different shape? Set up a per-route mapping in Routes, then the Mapping editor. Your mapping replaces the default entirely.

Common issues

401 "Invalid API token"

The token was revoked, or the user who made it lost API access. Generate a fresh one and update the destination.

403 "Permission denied"

The token's user lacks the "Create Customer" permission. Regenerate the token from an admin user. Verify catches this before it costs you a lead.

422 "Duplicate customer"

A customer with that email already exists in Housecall Pro, which enforces email uniqueness. LeadRails marks this a permanent failure and does not retry. Decide whether you want those merged in Housecall Pro.

Phone format errors

Housecall Pro expects US-formatted phone numbers. International leads may need format cleanup through a per-route mapping.

Lead Source not showing in reports

Check that the Lead Source label matches an existing value in Housecall Pro, or is a new label Housecall Pro adds to its list on first use.

Rate limits

• Housecall Pro caps API traffic per account. Free accounts are capped tighter. If you're routing more than about 1000 leads a day, ask Housecall Pro about a higher tier.
• When you hit the cap, Housecall Pro returns a 429 with a RateLimit-Reset header telling us when the window resets. LeadRails reads that header and waits until then before retrying. It does not use a Retry-After header, because Housecall Pro doesn't send one.
• Rate-limited deliveries are retried automatically. You don't lose the lead.

Authentication and token lifecycle

LeadRails connects with a static Housecall Pro API token. There's nothing to refresh. The token keeps working until you revoke or regenerate it in Housecall Pro. When you do, delivery starts failing with a 401. Paste the new token into the destination and you're back.

Housecall Pro also offers OAuth 2.0 for verified Integration Partners. LeadRails does not use it today. Everything here runs on the API token you generate yourself, which is the right path for a single business connecting its own account.