# Custom Statuses

Custom statuses let you model **long-lived, domain-specific state** for users and businesses in Footprint.
They provide a clean, auditable way to represent concepts like verification levels, compliance states, or business-specific classifications—without having to infer state from playbook runs or decisions.

## How Custom Statuses Work

Custom statuses are **customer-defined enumerations** attached to an entity (user or business).

Each custom status:

* Has a **kind** (for example, `id_verification_status`)
* Can hold **one value at a time** (such as `verified`, `pending`, or `rejected`), or be unset
* Is **fully auditable** — Footprint maintains an append-only log of all changes
* Is independent of playbooks, decisions, and signals

### Key Characteristics

**State, Not Events**

* Custom statuses represent the **current state** of an entity
* Unlike playbook outcomes or decisions (which are event-based), statuses persist over time
* Ideal for tracking verification levels, eligibility, or compliance posture

**Strongly Typed & Predefined**

* Statuses must be defined before use (via dashboard)
* Each status has a fixed set of allowed values
* Prevents typos and enforces consistency across systems

**Append-Only Semantics**

* Statuses can be set, updated, or cleared
* Every status change is recorded with a timestamp and actor
* Previous values are never overwritten in the audit log

## Example Use Cases

### Verification Layers

Model verification state that aggregates multiple checks:

* `identity_verification_status`: `pending`, `verified`, `rejected`
* `tax_verification_status`: `pending`, `verified`, `rejected`

These statuses represent the *result* of multiple underlying signals or playbooks.

### Compliance States

Track regulatory or risk-related classifications:

* `kyc_status`: `pending`, `verified`, `rejected`
* `aml_status`: `clear`, `flagged`, `reviewed`

### Business-Specific Logic

Represent application-specific concepts:

* `account_tier`: `basic`, `premium`, `enterprise`
* `risk_level`: `low`, `medium`, `high`

## Creating Custom Statuses

Custom statuses are defined once and reused across playbooks and manual reviews.

When creating a status, you define:

* The **status kind** (e.g. `id_verification_status`)
* The **entity type** it's applicable to (`user` or `business`)
* The set of **allowed values** for the status

Statuses must be created before they can be used in playbooks.

You can create custom statuses in the [dashboard](https://dashboard.onefootprint.com/settings/configurations).

## Setting Statuses

### Setting a Status in a Playbook

Playbooks are the primary way to set custom statuses automatically.

To update a status from a playbook:

1. Add an **Action** node in the playbook builder
2. Select **Set Status**
3. Choose the status kind and value

When the node executes during an onboarding, the entity's status will be updated.

### Updating a Status Manually

Custom statuses can also be set or cleared on the Users/Businesses dashboard or Manual Review dashboard.

This allows reviewers to override automated outcomes.

## API Access

Custom statuses are returned on entity detail endpoints.

View [User](/api-reference#get-users-fp-id) or [Business](/api-reference#get-businesses-fp-bid) API documentation to learn more.