Custom statuses

Custom statuses model long-lived, domain-specific state for users and businesses in Footprint. They give you an auditable way to represent concepts such as verification levels, compliance states, or your own classifications, without inferring state from playbook runs or decisions.

Custom statuses are enumerations you define, attached to an entity (user or business). Each custom status:

• Has a kind (for example, id_verification_status).
• Holds one value at a time (such as verified, pending, or rejected), or is unset.
• Is fully auditable: Footprint keeps an append-only log of all changes.
• Is independent of playbooks, decisions, and signals.

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. They suit tracking verification levels, eligibility, or compliance posture.

Strongly typed and predefined. You define statuses in the dashboard before use, and each status has a fixed set of allowed values. This prevents typos and enforces consistency across systems.

Append-only semantics. Statuses can be set, updated, or cleared. Every change is recorded with a timestamp and actor, and previous values are never overwritten in the audit log.

Verification layers. Model verification state that aggregates multiple checks, where the status represents the result of several underlying signals or playbooks:

• identity_verification_status: pending, verified, rejected
• tax_verification_status: pending, verified, rejected

Compliance states. Track regulatory or risk-related classifications:

• kyc_status: pending, verified, rejected
• aml_status: clear, flagged, reviewed

Application-specific concepts. Represent concepts specific to your app:

• account_tier: basic, premium, enterprise
• risk_level: low, medium, high

You define custom statuses once, in the dashboard, and reuse them across playbooks and manual reviews. A status must exist before a playbook can use it. When creating a status, you define:

• The status kind (e.g. id_verification_status).
• The entity type it applies to (user or business).
• The set of allowed values for the status.

Playbooks are the primary way to set custom statuses automatically. To set 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 runs during an onboarding, Footprint updates the entity's status.

You can also set or clear a custom status from the Users or Businesses pages in the dashboard, or from the manual review view, which lets you override automated outcomes.

Entity detail endpoints return custom statuses. See the User or Business API reference.