HousecallPro Integration for BookSmart Form Builder

Contents

Housecall Pro Integration for BookSmart Form Builder

The Housecall Pro integration lets a BookSmart form validate a customer’s service area, look up existing customers, display appointment times based on technician availability, and create a scheduled Housecall Pro job.

What the integration supports

Create or locate a Housecall Pro customer
Create a service address and job
Validate a ZIP or postal code against Housecall Pro service zones
Display live two-hour booking windows
Limit availability to employees enabled for Housecall Pro Online Booking
Respect jobs, events, meetings, PTO, and other blocks reflected by Housecall Pro’s Booking Windows API
Convert appointment times using the timezone saved in the Launch365 company profile
Assign an available online-bookable technician
Create the job as unassigned when every eligible technician is unavailable
Look up returning customers by phone number

Housecall Pro service IDs, employee tags, and skills-based routing are not currently used. Availability is based on all employees whose Housecall Pro permission can_be_booked_online is enabled.

Prerequisites

Before configuring a form, make sure:

The company has an active Housecall Pro account with API access.
Housecall Pro is connected under Integrations → Housecall Pro in Launch365.
The Launch365 company profile has the correct timezone.
The intended technicians are enabled for Online Booking in Housecall Pro.
Housecall Pro service zones are configured if the form will use ZIP Code Lookup.

Connect Housecall Pro

In Launch365, go to Integrations → Housecall Pro.
Enter the Housecall Pro API key.
Save the integration.
Confirm the connection is active.

API credentials are stored server-side and are not exposed in the public BookSmart form.

Enable Housecall Pro on a BookSmart form

Create or edit the BookSmart form.
Open Integration Settings.
Enable Send Submissions to Housecall Pro.
Map the form fields using each field’s Housecall Pro Key setting.
Configure the optional ZIP, customer, and availability lookups described below.
Save the form and test it on the published website.

Field mappings

For each form field, open its settings and select the appropriate value from Housecall Pro Key.

Customer and address fields

Customer information	Housecall Pro Key
First name	`customer_fname`
Last name	`customer_lname`
Phone	`customer_phone`
Email	`customer_email`
Street address	`street`
City	`city`
State	`state`
ZIP or postal code	`zip`
Country	`country`

The customer name, phone number, and complete service address should be collected whenever a new Housecall Pro customer may need to be created. US phone numbers are normalized to the 10-digit format expected by Housecall Pro.

Job and scheduling fields

Job information	Housecall Pro Key
Service description or reason	`booking_reason`
Booking or job name	`booking_type`
Appointment date	`booking_date`
Appointment time	`booking_time`
First-time customer selection	`isFirstTimeClient`
Residential or commercial selection	`customerType`

Both booking_date and booking_time must have values for the job to be scheduled. If either value is missing, the job is created without a schedule.

Service-area ZIP lookup

ZIP Code Lookup checks Housecall Pro service zones before allowing the customer to continue.

Configure the ZIP field

Add or edit a Text Field for the ZIP or postal code.
Set its Housecall Pro Key to zip.
Enable Enable ZIP Code Lookup.
Save the form.

When the customer enters a ZIP or postal code, BookSmart requests matching zones from Housecall Pro’s /service_zones endpoint.

If a matching service zone is found, the customer can continue.
If no matching service zone is found, the form reports that service is unavailable in that area.
If the lookup cannot be completed, the form displays an error and does not treat the location as covered.

The provider is selected from the form’s integration settings. A Housecall Pro form sends the lookup to Housecall Pro rather than ServiceTitan.

Returning-customer lookup

Customer Lookup searches Housecall Pro by phone number and can return the customer’s saved name, email address, and service locations.

Configure the phone field

Add or edit the customer phone field.
Set its Housecall Pro Key to customer_phone.
Enable Enable Customer Lookup.
Save the form.

If a matching customer is selected, BookSmart can use the returned information to populate the related customer and address fields.

Live technician availability

BookSmart can display time choices based on the schedules of technicians who are enabled for Housecall Pro Online Booking.

Configure the appointment date

Add or edit a Date Field.
Set its Housecall Pro Key to booking_date.
Enable Enable Housecall Pro Availability Lookup.
Configure lead days and disabled weekend days if needed.

Configure the appointment time

Add or edit a Radio Group for appointment times.
Set its Housecall Pro Key to booking_time.
Enable Housecall Pro Time Slots.
Add normal radio options to the field as fallback choices.

Keep the date field and time radio group in the same form step. When a customer selects a date, BookSmart replaces the radio group’s normal options with the live Housecall Pro windows for that date.

How availability is calculated

For the selected date, BookSmart:

Retrieves all Housecall Pro employees.
Keeps only employees whose permissions.can_be_booked_online value is true.
Requests booking windows separately for each eligible employee.
Uses Housecall Pro’s required employee_ids[] query parameter so the result represents that specific technician.
Keeps only windows marked available: true.
Combines duplicate windows when more than one technician is available.
Displays the available times in the Launch365 company’s timezone.

The current BookSmart Housecall Pro appointment duration is fixed at 120 minutes. Each displayed choice represents a two-hour window.

The integration uses these Housecall Pro availability parameters:

GET /company/schedule_availability/booking_windows

show_for_days=1
start_date=<selected date>T00:00:00
service_duration=120
employee_ids[]=<Housecall Pro employee ID>

The square brackets in employee_ids[] are important. Sending employee_ids as a scalar may return company-wide availability instead of the selected technician’s availability.

Jobs, events, meetings, PTO, and blocked time

BookSmart relies on the availability returned by Housecall Pro’s Booking Windows API. If Housecall Pro marks a window unavailable because an eligible technician has a job, training, meeting, PTO entry, or another blocking event, that technician is excluded from that time.

For example, if a technician has a blocking event from 8:00 AM to 5:00 PM, their two-hour windows during that period should be returned as available: false and should not make those times appear available on the form.

If a blocked event does not affect the result:

Confirm the event is assigned to the correct Housecall Pro employee.
Confirm the employee ID used in the availability request matches that technician.
Confirm the request uses employee_ids[]=<employee ID>.
Check the direct Housecall Pro API response for the affected date and employee.
Verify the event is configured in Housecall Pro as a schedule-blocking event.

Technician assignment

When the form is submitted, BookSmart verifies availability again before creating the job.

Only employees with can_be_booked_online: true are considered.
The Housecall Pro Point of Contact setting is separate from Online Booking.
A user is not assigned merely because they are the company’s Point of Contact.
When multiple employees are available, BookSmart uses a consistent name-based order and assigns the first available employee.
The current integration does not load-balance jobs and does not route by service ID, employee tag, skill, or location.

This second availability check helps prevent assigning a technician whose schedule changed after the customer first loaded the available times.

What happens when no technician is available

The form remains bookable even when every eligible technician is busy.

If Housecall Pro returns no available technician windows:

BookSmart restores the fallback choices configured on the appointment-time radio field.
The customer sees:

All technicians are currently booked. Choose a preferred time and the office will confirm your appointment.
The customer can select a preferred time and submit the form.
The job is created with the requested schedule and an empty assigned_employee_ids value.
The job remains unassigned in Housecall Pro for office review and manual dispatch.

The same unassigned behavior is used when no Housecall Pro employee is enabled for Online Booking.

This fallback is only used when availability was checked successfully and no technician was available. If the Housecall Pro employee or availability API cannot be reached, BookSmart shows an error instead of creating a potentially incorrect assignment.

Timezone handling

The timezone saved in the Launch365 company profile controls Housecall Pro scheduling.

BookSmart:

Interprets the customer’s selected date and time in the company profile timezone.
Displays Housecall Pro booking windows in that timezone.
Converts the selected two-hour appointment to UTC before sending it to Housecall Pro.

For example, during daylight saving time:

Company timezone: America/New_York
Customer selection: 8:00 AM
Housecall Pro UTC start: 12:00 PM UTC

If an appointment appears several hours early or late in Housecall Pro, confirm the timezone under the Launch365 company profile before testing again.

Submission flow

When a Housecall Pro-enabled form is submitted, BookSmart:

Validates the form.
Rechecks service-zone coverage when ZIP Code Lookup is enabled.
Finds the existing Launch365 and Housecall Pro customer when possible, or creates a new customer.
Creates or uses the customer’s service address.
Converts the selected schedule from the company timezone to UTC.
Retrieves online-bookable employees.
Rechecks the requested window for each eligible employee.
Assigns an available technician or leaves the job unassigned.
Creates the Housecall Pro job.

Housecall Pro API endpoints used

Purpose	Endpoint
Create or search customers	`/customers`
Retrieve an existing customer	`/customers/{customer_id}`
Create a job	`/jobs`
Retrieve employees and Online Booking permissions	`/employees`
Retrieve technician booking windows	`/company/schedule_availability/booking_windows`
Validate service-area coverage	`/service_zones`

Authentication uses the Housecall Pro API token saved in the Launch365 integration settings.

Troubleshooting

The form says “ServiceTitan integration not configured”

Confirm the form is saved with Send Submissions to Housecall Pro enabled and that its fields use Housecall Pro mappings. Older forms without a saved integration provider are detected from their field mappings, but resaving the form is recommended.

Also clear any website, WordPress, or CDN cache so the current BookSmart form script is loaded.

The ZIP lookup does not work

Confirm Enable ZIP Code Lookup is checked on the ZIP field.
Confirm the field’s Housecall Pro Key is zip.
Confirm Housecall Pro is connected for the company that owns the form.
Confirm the ZIP exists in an active Housecall Pro service zone.
Clear the website and optimization-plugin cache after updating the form.

Available times do not change after selecting a date

Confirm the date field has Enable Housecall Pro Availability Lookup enabled.
Confirm the time field is a Radio Group with Housecall Pro Time Slots enabled.
Keep the date and time fields in the same form step.
Confirm both fields use booking_date and booking_time.
Confirm at least one employee has Online Booking enabled in Housecall Pro.
Clear the website and optimization-plugin cache.

A Point of Contact or office user was assigned

The Point of Contact setting does not control BookSmart assignment. Check the employee in the Housecall Pro /employees response. If permissions.can_be_booked_online is true, the employee is eligible even if their role is Admin or Office Staff.

Disable that employee’s Online Booking permission in Housecall Pro if they should never receive BookSmart jobs.

A technician with a blocked event was assigned

Confirm the API call includes that technician as employee_ids[]=<employee ID>.
Confirm the exact requested two-hour window is returned as available: false.
Confirm the blocking event belongs to the same employee record.
Confirm the event is recognized by Housecall Pro as blocking availability.

All technicians are booked

This is expected to use the fallback choices saved on the time radio field. The resulting Housecall Pro job is scheduled but unassigned so the office can confirm or dispatch it manually.

If there are no fallback choices, the form can only report that no time slots are available.

Appointment times have the wrong offset

Check the timezone saved in the Launch365 company profile. Housecall Pro returns UTC timestamps, and BookSmart converts them using the company profile timezone.

The availability API returns an error

BookSmart does not create the scheduled job when technician availability cannot be verified safely. Check the Housecall Pro API key, permissions, account status, and API response, then retry.

Current limitations

Housecall Pro appointments created through this form use a fixed two-hour duration.
All employees enabled for Housecall Pro Online Booking are considered.
Service ID, job type, employee tag, skill, territory, and route-based technician filtering are not currently supported.
Assignment is deterministic; it is not round-robin or load-balanced.
BookSmart depends on Housecall Pro to determine whether jobs and events block a booking window.
The no-availability fallback requires normal radio options to be configured on the time field.

Recommended setup checklist

Getting help

When contacting Launch365 support, include:

The company ID
The BookSmart form name or UUID
The selected ZIP code, date, and time
The expected technician
The employee ID returned by Housecall Pro
A screenshot of the Housecall Pro schedule
The Housecall Pro booking-window response, with API credentials removed

Never include an active Housecall Pro API token in screenshots, tickets, or copied commands.

Updated on July 28, 2026

Was this article helpful?

Yes No