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

# Settings over the API

> The configuration behind the pipeline: which statuses exist, how leads and customers get auto-tagged, where records come from, what counts as a duplicate,

The configuration behind the pipeline: which statuses exist, how leads and
customers get auto-tagged, where records come from, what counts as a duplicate,
and the SLA clocks. These are the highest-traffic admin pages, and until now an
agent could move a lead through a pipeline but never create the pipeline.
Reads take `settings:view`, writes `settings:configure`. Everything lives under
`/v1/settings/`.

| Area            | Calls                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Statuses        | `GET/POST /v1/settings/statuses/{object}`, `GET/PATCH/DELETE …/{id}` — `object` is `leads` (lead statuses) or `deals` (deal stages). |
| Tags            | `GET/POST /v1/settings/tags/{object}`, `GET/PATCH/DELETE …/{id}` — `object` is `leads` or `customers`.                               |
| Sources         | `GET/POST /v1/settings/sources`, `GET/PATCH/DELETE …/{id}` — one list, shared by leads and deals.                                    |
| Duplicate check | `GET /v1/settings/duplicate-check`, `PUT /v1/settings/duplicate-check/{object}` — `leads` or `deals`.                                |
| SLA policies    | `GET/POST /v1/settings/sla-policies`, `GET/PATCH/DELETE …/{id}` — reminders and escalations ride along.                              |

Every list is the whole configuration (these are small, bounded sets), every
name is unique within its list (case-insensitive, `409 ALREADY_EXISTS`), and
every write records an `auditlog` row naming the API key.

## Statuses

A status carries `name`, `description`, `order_position`, `is_active`, `color`
and the two pre-condition settings the GUI edits: `pre_condition_fields` (fields
that must be filled before a record may enter the status) and
`pre_condition_rules` (conditional rules, evaluated the same way
`POST /v1/deals/{id}/stage` enforces them). The shape is the one custom objects
use for their statuses, so a client learns it once.

On create, `order_position` defaults to the end of the pipeline and `color` to
grey. **Deleting a status that records still sit in is refused** (`409 CONFLICT`,
`details.reason: in_use`, `details.references`) — move them first. The GUI does
not have this guard; the API does, on purpose.

The AI assistant's `list_statuses` tool reads these same tables, so a status
created here is usable by `set_status` immediately.

## Tags

A **lead tag** *is* its conditions: `fields` holds at least one
`{ "field", "operator", "value" }` condition, and a lead matching them gets the
tag. A **customer tag** reads `fields` (field names), matches on `conditions`
joined by `condition_logic` (`AND`/`OR`). `priority` orders competing tags
(lower wins). Colours are `#RRGGBB`.

## Sources

`name`, `description`, `is_enabled`. Deleting a source that leads or deals still
reference is refused with counts; disable it instead.

## Duplicate check

```json theme={null}
PUT /v1/settings/duplicate-check/leads
{ "enabled": true, "fields": ["email", "phone"] }
```

A record is flagged as a duplicate when an existing one matches **every**
selected field that has a value. Field names are built-in or custom field names
of the object (see `GET /v1/objects/{object}/schema`). Enabling with an empty
list is refused. Customers have no duplicate check today.

## SLA policies

A policy names the `entity_type` (`lead`, `customer`, `deal`), a `priority`,
three clocks in minutes (`first_response_time`, `every_response_time`,
`resolution_time`), and whether they run `24/7` or in `business_hours`
(`business_hours_start`/`end` as `HH:MM`, `business_days` as weekday numbers).
`reminders` (`first_response` / `every_response` / `resolution`, minutes before
the deadline, recipient user ids) and `escalations` (level, minutes after,
recipients, message template) are saved with the policy; sending either array on
`PATCH` replaces that set wholesale, exactly as the GUI form does.

## Not in this wave

Lead-scoring weights and datasets, entity renaming and module toggles are wave 2.