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

# SLA and escalation

> Search SLAs, automatic reassignment, terminal workflow conditions, and human escalation policy.

# SLA and escalation

<p>
  <a href="/assets/downloads/guides/sla-and-escalation.pdf" download="sla-and-escalation.pdf">Download this guide</a>
</p>

Searches run asynchronously. When automation cannot finish, or when time limits are exceeded, SNH AI escalates with `verification.action_required` (typically `HUMAN_ESCALATION`). Organization-level policy controls SLA windows and which escalation sources are enabled.

Related: [Errors](/api-reference/errors) · [Webhook events](/webhooks/events) · [Third-party ban](/guides/third-party-ban)

## Workflow terminal conditions

### Research phase

* **No contacts found**: `verification.action_required` with `HUMAN_ESCALATION`
* **Third-party record detected**: `verification.action_required` with `THIRD_PARTY_RECORD` (structured contact details)
* **Banned third-party vendor**: When `searchConfig.thirdPartyBan` contains the detected vendor code, the `THIRD_PARTY_RECORD` webhook is suppressed, an audit notation is recorded, and the search continues with manual/outbound handling. Inbound redirects to a banned vendor emit `HUMAN_ESCALATION` with `metadata.escalationSubtype: "THIRD_PARTY_BAN"`. See [Third-party ban](/guides/third-party-ban).

### Outbound phase

* **Transient retry cap reached**: After 3 transient retries per channel (voice/email/fax), the search is reassigned with `HUMAN_ESCALATION`
* **Workflow failure**: After max retries, the workflow terminalizes with `SYSTEM_FAILURE`, `UPSTREAM_ISSUE`, or `SLA_REACHED`. `SLA_REACHED` corresponds to the `workflow_failure_sla_timeout` source in the per-source table below.

## SLA and automatic reassignment

* **Frequency**: Checks run every 4 hours (system-level, not configurable)
* **Search SLA**: Default 24 hours (organization-configurable via `policy.global.searchSlaMinutes`)
* **Reassignment window**: Default 48 hours (organization-configurable via `policy.global.reassignmentWindowMinutes`)
* **Weekend adjustment**: Deadlines that fall on Saturday/Sunday move to the next Monday (system behavior)
* **Trigger**: Whichever of SLA or reassignment window is reached first
* **Reason code**: `HUMAN_ESCALATION` with metadata
* **Contact plan**: Optionally included when `policy.global.includeContactPlanInEscalation` is `true` (default `false`)

**Example weekend adjustment:** search created Friday 5 PM with a 24-hour SLA → Saturday 5 PM is extended to Monday 5 PM.

### Configuring SLA settings

These settings are configured at the organization level via unified policy (not per API request unless you use `searchConfig.timing`):

```json theme={null}
{
  "policy": {
    "global": {
      "searchSlaMinutes": 1440,
      "reassignmentWindowMinutes": 2880,
      "includeContactPlanInEscalation": false
    }
  }
}
```

| Parameter                        | Type    | Default | Description                                                       |
| -------------------------------- | ------- | ------- | ----------------------------------------------------------------- |
| `searchSlaMinutes`               | number  | `1440`  | Search SLA timeout in minutes (default: 24 hours)                 |
| `reassignmentWindowMinutes`      | number  | `2880`  | Reassignment window in minutes (default: 48 hours)                |
| `includeContactPlanInEscalation` | boolean | `false` | Include contact plan research data in `HUMAN_ESCALATION` webhooks |

Per-search overrides: see [Search-level configuration](/guides/search-config-reference) (`timing.searchSlaMinutes`).

### Per-source human escalation (optional)

Disable escalation for specific reasons via `policy.global.humanEscalation.enabledForSource`. Set a source to `false` to prevent reassignment for that reason. Omitted sources remain enabled.

`searchConfig.escalation.disableAutoEscalation=true` on a search always suppresses escalation for that search, regardless of this tenant-level setting.

| Source                                | When it triggers                                                                                                                           |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `no_actionable_contacts`              | All contacts for the search have already been attempted (outbound).                                                                        |
| `no_actionable_outbound_methods`      | This run created no new attempts and no follow-ups, and the search has no prior successful/scheduled/suppressed attempts.                  |
| `inbound_all_contacts_suppressed`     | All next contacts received through inbound are unactionable.                                                                               |
| `tenant_reassignment_window_exceeded` | Scheduling a second outbound would exceed the reassignment window.                                                                         |
| `retry_cap_reached`                   | Transient retry cap reached for a channel (voice/email/fax).                                                                               |
| `automatic_reassignment`              | Scheduler reassignment (SLA or reassignment window exceeded).                                                                              |
| `sla_timeout`                         | SLA exceeded when explicitly checking.                                                                                                     |
| `workflow_failure_sla_timeout`        | SLA exceeded during workflow failure handling.                                                                                             |
| `workflow_failure_action_required`    | Workflow failed and SLA not exceeded; would emit `action_required`. Disabling skips the webhook and completes the search without emitting. |

```json theme={null}
{
  "policy": {
    "global": {
      "humanEscalation": {
        "enabledForSource": {
          "no_actionable_outbound_methods": false,
          "sla_timeout": false
        }
      }
    }
  }
}
```

**Important:** Disabling a source means the system will **not** escalate for that reason. Some searches may remain `IN_PROGRESS` until another condition is met. Use only when you accept that behavior. Existing organizations are unchanged if they do not set this config.

## Important notes

* When a workflow is terminalized, **no further outbound attempts** are made
* Terminal conditions and automatic reassignment are **idempotent** (no duplicate escalation webhooks)
* Contact plan data in escalation webhooks is opt-in per organization (`includeContactPlanInEscalation`)