How to Set Up AI Booking in Workiz

📝 Let your AI offer real appointment times and book scheduled Workiz jobs automatically once a lead picks an open slot.

Table of contents

• What Workiz AI booking does
• How availability works
• API v2 and required custom fields
• Before you start
• Step 1: Connect Workiz to LeadTruffle
• Step 2: Turn on AI booking
• Step 3: Set your job defaults
• Step 4: Set up employee assignment (optional)
• Step 5: Choose required customer fields
• Step 6: Configure your booking windows
• Step 7: Turn on Workiz AI booking for your AI
• Test your setup
• Troubleshooting

What Workiz AI booking does

Workiz AI booking lets your LeadTruffle AI offer appointment times to a lead and create a scheduled job in Workiz as soon as the lead picks an open slot.

When a booking succeeds, LeadTruffle creates a Workiz job with:

• The booked start and end time
• Customer name, phone, email, and address when available
• Your selected job type
• A matching Workiz source, including any custom source mapping you enabled; unmatched attribution stays in the job details
• Job notes containing the appointment window, the lead's notes/issue, the source channel, and the LeadTruffle lead and conversation IDs
• An assigned employee, only if you've configured employee assignment

How availability works

By default, you set your booking windows inside LeadTruffle, and LeadTruffle checks Workiz for conflicts. You can also enable Respect Workiz availability and holidays in Scheduling. API v2 uses your main key for this option; a v1 connection may use a separately saved availability key. Native availability remains optional and does not replace your LeadTruffle booking windows.

For each availability lookup, LeadTruffle:

1. Reads the booking windows you configured in LeadTruffle
2. Applies your timezone, slot duration, minimum notice, and days-ahead settings
3. Pulls your scheduled Workiz jobs for the date range
4. Treats scheduled, non-cancelled Workiz jobs as conflicts
5. Removes any slots that overlap an existing job
6. Offers the AI only the remaining open slots

When a lead chooses a slot, LeadTruffle re-checks availability before creating the job. If the slot is no longer open, the booking isn't created and the AI offers the latest available alternatives.

API v2 and required custom fields

API v2 needs only an API key, with no API secret. LeadTruffle detects and saves the API version when you enter the key. Existing v1 connections keep using their API Token and API Secret until you choose to replace them.

Workiz v2 can enforce required job custom fields even when earlier v1 jobs were accepted without them. A successful connection check is not proof that a job can be created. Requirements come from your Workiz account and may apply only to certain job types.

To configure v2 job defaults:

1. Allow Read access to Custom Fields on your Workiz key, as well as the permissions for the other features you use. Jobs and Leads need Read & Write access for those actions; Users, Job Types, Ad groups, Search and Availability need Read access for the corresponding features.
2. Open Workiz Settings → Basic Settings, load the Workiz options and select the job type for bookings.
3. Open Custom fields. LeadTruffle loads the account's job fields and dropdown choices using the entered key, even before the connection is saved. Set a fixed default for each Required to create field that applies to the selected job type.
4. Save the key and settings together. You do not need to turn AI booking off or save the connection first. Validation errors keep the panel open so you can correct the defaults; a successful save closes it.

Required to close means the team must complete that field later in Workiz; a closing requirement alone does not block creating a job. A field can have both requirements. Fields required only for another job type do not block the selected type.

Supported defaults are text, long text, numbers, dates, dropdown choices and yes/no fields. Explicit zero and No values are kept. Leave an optional field blank to omit it. File uploads and unsupported field types cannot be supplied as defaults; review a required unsupported field in Workiz before enabling AI booking.

These are fixed defaults for new AI-booked Jobs only. They do not fill ordinary Leads or Client custom fields, edit existing jobs, or collect a different answer from every customer. Use values that make sense for all bookings of the selected type.

Entering a different API key clears the previous account's defaults from the draft. Choose defaults for the new connection before saving; the saved connection stays intact until a save succeeds. If a Workiz administrator changes fields, choices or requirements, reload Custom fields, review the values and save again. A later Workiz rejection leaves the appointment unconfirmed; check Recent Logs and arrange manual follow-up.

API v2 also loads the full configured job-type and lead-source lists, including options absent from recent jobs. Its main key supports optional Respect Workiz availability and holidays in Scheduling; no second key is needed. If Workiz availability cannot be checked, LeadTruffle keeps its existing fallback to your windows and job conflicts. A successful check with no available times is treated as no availability.

Before you start

You'll need:

• A Workiz account with API access: one API key for v2, or an API Token and API Secret for v1
• Admin access to your LeadTruffle account
• A clear idea of the days and hours you want the AI to be able to book

Step 1: Connect Workiz to LeadTruffle

1. Open the Workiz integration settings in LeadTruffle.
2. Enter your Workiz API key and confirm the detected version. Add your API Secret only if API v1 is shown.
3. Enable the integration.
4. Decide whether lead sync should also create Workiz leads, and turn it on if you want it.

Step 2: Turn on AI booking

In the Workiz integration settings, turn on Allow AI to book Workiz jobs.

This is what lets the AI create scheduled jobs. Without it, you'll only get lead sync (if enabled), not booked appointments.

Step 3: Set your job defaults

In Workiz settings, choose the job type for AI booking and review these defaults:

1. Job Type
2. Job Source
3. Fallback Postal Code

Use Load Workiz options to populate the job-type and source dropdowns. V2 loads the full configured catalogs. V1 keeps using suggestions from recent jobs, so its list may be incomplete.

• Job source — automatic matching uses the inquiry's original source. Use Source Mapping to choose an existing Workiz source for supported channels or individual LSA gateways. A preferred source is used only when it matches the inquiry; an unmatched source is kept in job details instead of creating a Workiz source.
• Postal code — Workiz may require a postal code to create a job. LeadTruffle sends the customer's ZIP when it has one. If the customer ZIP is missing, it uses your Fallback Postal Code; if that isn't set, it falls back to your company's saved postal code when available.

Step 4: Set up employee assignment (optional)

By default, AI-created Workiz jobs are unassigned.

To assign them automatically:

1. Click Load Employees in the Workiz integration settings.
2. Select one or more employees that LeadTruffle is allowed to assign jobs to.

How assignment works:

• One employee selected — LeadTruffle assigns every AI-created job to that employee.
• Multiple employees selected — LeadTruffle uses round robin and skips any employee who already has a conflicting Workiz job for that slot.
• All selected employees busy — LeadTruffle treats the slot as unavailable and won't offer it.

Step 5: Choose required customer fields

Workiz needs at least one contact method — phone or email — to create a job.

For the address, LeadTruffle treats it as present once it has street, city, and state. The postal code can come from the customer record or your fallback settings. Workiz v2 may still require a complete address to create the customer/property; a connection check does not verify this. The Custom fields defaults described above are separate from customer contact requirements.

You can also require the AI to collect specific fields before it books:

• Email
• Phone
• Address

Step 6: Configure your booking windows

1. Open the Scheduling tab.
2. Turn on Use LeadTruffle booking windows.
3. Configure your timezone, slot duration, minimum notice, days ahead, and weekly booking windows:

• Timezone - the timezone your booking windows and offered slots are calculated in. Set this to your local business timezone so appointment times line up with how you and your customers think about the day.
• Slot duration - how long each appointment slot is. This sets the length of the booked job (start to end time) and how slots are spaced across your booking windows.
• Minimum notice - the shortest lead time allowed before an appointment. Slots sooner than this won't be offered, so the AI can't book something an hour from now if you need more runway.
• Days ahead - how far into the future the AI can offer slots. This caps the booking window so leads aren't scheduling months out.
• Weekly booking windows - the days and hours each week the AI is allowed to book. LeadTruffle only offers slots inside these windows, then subtracts any existing Workiz jobs that overlap.

4. Click Show Availability to preview the exact slots LeadTruffle will offer after subtracting your existing Workiz jobs.
5. Save your settings.

Step 7: Turn on Workiz AI booking for your AI

In your lead qualifier or channel settings, select the Workiz AI booking mode for the relevant AI experience.

This connects everything you just set up to the AI that's actually talking to your leads.

Test your setup

The Workiz integration panel includes Test Sync / Booking:

• Test Lead Sync — tests the lead-only sync path.
• Test Booking — pick a recent lead, choose one of the currently available Workiz slots, and run a real booking test.
• Recent Logs — shows recent Workiz sync and booking activity, including Workiz validation messages like missing required fields.

Troubleshooting

If bookings aren't going through, check these common causes:

Need help? Contact us at support@leadtruffle.com or message the team via the chat on this article or in-app.

Updated on: 27/10/2026