> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehatchapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar: ServiceTitan Ad Cap

> Connect your Adaptive Capacity rules so your AI agent books appointments that follow them

If your business runs Adaptive Capacity in ServiceTitan, your Hatch AI agent can book against it directly. The agent asks ServiceTitan for availability, ServiceTitan applies the rules you've configured, and the agent only offers times that are bookable under those rules.

This article covers how to turn it on and how to confirm it's working. If you're on Adjustable Capacity, no action is needed — Adjustable is fully supported and nothing here applies to you.

## Before you start

You'll need:

* **Adaptive Capacity enabled in ServiceTitan**: This is a ServiceTitan feature. Hatch connects to it but can't enable it for you.
* **Capacity assigned in ServiceTitan**: Adaptive Capacity doesn't create availability on its own. Your technicians, business units, and job types still need capacity configured.
* **Access to ServiceTitan settings**: Some steps require the Settings area. If you don't have access, loop in whoever administers your ServiceTitan account.
* **Manager role in Hatch**: Required to edit your AI agent's commands.

## Step 1: Confirm you're on Adaptive Capacity

In ServiceTitan, open **Settings** (the gear icon) and search for `cap`.

* **If an Adaptive Capacity section appears**: You're on Adaptive. Continue to Step 2.
* **If it doesn't appear**: You're on Adjustable Capacity, and no changes are needed.

<Note>
  ServiceTitan recommends against running Adjustable and Adaptive at the same time. If you've recently moved to Adaptive, confirm that Adjustable has been turned off.
</Note>

## Step 2: Update your ServiceTitan API access

Adaptive Capacity uses a newer set of ServiceTitan API permissions. Until you approve them, Hatch can't read your Adaptive rules.

Follow the steps in [How to upgrade the ServiceTitan app](/integrations/crm-field-management-systems/servicetitan-integration#how-to-upgrade-the-servicetitan-app). In short: open **Settings** → **API Application Access** in ServiceTitan, and if the **Hatch (Official)** app shows an **Update to the New Version** option, select it and click **Allow Access**.

<Warning>
  This is the most common reason Adaptive Capacity doesn't work after setup. If Hatch reports that ServiceTitan denied the request, start here.
</Warning>

## Step 3: Set your capacity source in Hatch

In Hatch, open your AI agent's **Decision Tree** → **Agent Instructions**, then open your [Calendar command](/getting-started/hatch-assistant/commands-calendar). If you don't have one yet, create it with `/Calendar`.

1. Choose the **Advanced — Dispatch** calendar type.
2. Go to **Calendar** → **ServiceTitan Configuration**.
3. Scroll to **Capacity Source** and select **Adaptive**.

<Info>
  This setting has to match how your ServiceTitan account is actually configured. Hatch can't detect your capacity type automatically. If the two don't match, your agent will keep booking appointments successfully but won't apply your Adaptive rules.
</Info>

## Step 4: Test the connection

In your Calendar command, click **Test Configuration**, choose a business unit and job type you know are set up in ServiceTitan, then click **Fetch Availability**.

The test runs in three numbered steps — **Availability**, **Book**, then **Cancel** — and reports each capacity type separately.

### Reading your results

Two rows come back, one per capacity type:

* **Adaptive Capacity** *(Hatch Dispatch slots)* — the Adaptive connection
* **Legacy / Adjustable** *(ServiceTitan capacity)* — the older connection

Each row shows either a slot summary (for example `12 slots · Mar 3 – Mar 7`), **Empty**, or **Error**.

| What you see                                                            | What it means                                                                                                                                                                              |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Adaptive Capacity** with a slot count                                 | Working. Your agent will book against your Adaptive rules.                                                                                                                                 |
| **Adaptive Capacity: Empty**                                            | Connected, but ServiceTitan returned no availability for that business unit and job type. Check that a technician has capacity for it and that no Adaptive rule is removing that capacity. |
| **Adaptive Capacity: Error** — "ServiceTitan denied the request"        | Your API access hasn't been updated. Return to [Step 2](#step-2-update-your-servicetitan-api-access).                                                                                      |
| **Legacy / Adjustable** returns slots even though you only run Adaptive | Expected. The two connections report independently. What matters is that your Capacity Source setting matches your real setup.                                                             |
| Both rows show **Error**                                                | Start with [Step 2](#step-2-update-your-servicetitan-api-access). If it persists, contact Hatch support.                                                                                   |

### Booking a test appointment

After fetching availability you can optionally click **Book test appointment**. This places a real appointment on your ServiceTitan dispatch board using a default Hatch test customer, which confirms the full path works rather than just the availability lookup. Hatch shows the customer, business unit, job type, appointment ID, and status so you can match it against ServiceTitan.

If the button is disabled, the message reads *"Disabled — the configured capacity source returned no slots"* — there's nothing available to book, so resolve the Empty result first.

To remove the test appointment, pick a **cancel reason**, then click **Cancel appointment**. The status changes to *Canceled*. You don't need to leave Hatch.

## What your agent follows

With Capacity Source set to Adaptive, Hatch asks ServiceTitan to apply your account's own Adaptive Capacity configuration — your **Basic Settings**, **Advanced Settings**, and **Strategic Rules**. That covers rules targeting specific technicians, job types, skills, tags, and business unit groups, whether they run continuously or only on certain days, times, or date ranges, along with one-off overrides.

One thing to know about how times reach your customers:

* **Your agent offers arrival windows, not exact start times**: If you use arrival windows in ServiceTitan, callers hear the window — "someone will arrive between 8am and 12pm."

<Note>
  Hatch draws from the same capacity pool your team does. When your agent books an appointment, that slot is consumed exactly as if a CSR had booked it. Hatch doesn't rearrange your dispatch board or change your capacity rules.
</Note>

## Troubleshooting

### My agent isn't offering any times

Run **Test Configuration** for the business unit and job type in question. If it returns Empty or 0 slots, the issue is capacity in ServiceTitan rather than the Hatch connection. Confirm a technician has capacity for that combination and that no Adaptive rule is removing it.

### I switched to Adaptive but nothing changed

Check two things, in order: that you completed [Step 2](#step-2-update-your-servicetitan-api-access) in ServiceTitan, and that **Capacity Source** in your Calendar command is set to Adaptive. Both are required.

### The times my agent offers don't match what I see in ServiceTitan

Your agent may offer fewer options than a manual ServiceTitan lookup shows. Times are grouped into arrival windows, and your workspace may have additional rules restricting which windows the agent can offer. This is expected.

### We changed our capacity setup in ServiceTitan

Tell your Hatch account team. The Capacity Source setting doesn't update on its own, and if it no longer matches ServiceTitan your agent will keep booking successfully without applying your current rules.

## Related articles

* [Calendar command](/getting-started/hatch-assistant/commands-calendar)
* [ServiceTitan integration](/integrations/crm-field-management-systems/servicetitan-integration)
* [How to switch to the Hatch application of ServiceTitan](/integrations/crm-field-management-systems/how-to-switch-to-the-hatch-application-of-servicetitan)
* [Prepare for Adaptive Capacity](https://help.servicetitan.com/how-to/set-up-adaptive-capacity) (ServiceTitan)