# Building Playbooks

A Playbook defines how Footprint onboards a user or business: what data to collect, which verification checks to run, and how to decide the final outcome. You build a Playbook visually in the [Playbook builder](https://dashboard.onefootprint.com/playbooks) by connecting **nodes** into a flow.

This guide is a light walkthrough of creating a Playbook and the nodes available to you. For a deep dive on the rules language used by Rules nodes, see [Playbook Rules](/articles/guides/playbooks-playbook-rules).

## Key concepts

A few concepts make the rest of this guide easier to follow:

* **Directed acyclic graph (DAG)** — a Playbook is a DAG with a single start node. Control flows from one node to the next and never loops back. Branching nodes split the flow into multiple paths, which merge back together so the flow can continue to a shared decision.
* **Collection nodes vs. decisioning nodes** — collection nodes (identity data, business data, custom data, documents) are user-facing: they pause the flow to gather input from the person being onboarded. Decisioning nodes (verification checks, rules, branches, external API, expression, agent, and action nodes) run on Footprint's backend and don't show anything to the user.
* **Vault data (`vault.*`)** — durable, encrypted attributes stored in the user's or business's [vault](/articles/vault/fields) (e.g. `vault.id.first_name`).
* **Onboarding data (`data.*`)** — ephemeral values computed during a single onboarding run (by expression, rules, external API, and agent nodes) and made available to later nodes under the `data.*` prefix. Onboarding data is scoped to that onboarding and is not written to the vault unless you explicitly copy it there with a [Data assignment](#data-assignment) node.

## Creating a Playbook

From the [Playbooks](https://dashboard.onefootprint.com/playbooks) page in the dashboard, click **Create** and choose a starting point:

* **A template** — a ready-to-use flow (e.g. KYC, KYB) that comes pre-wired with sensible data collection, verification checks, and rules. This is the fastest way to start.
* **Onboard People** — a blank person (KYC) Playbook.
* **Onboard Businesses** — a blank business (KYB) Playbook.

Give the Playbook a name and click **Create playbook** to open it in the builder. When you're happy with the flow, publish it to start onboarding against it.

## The Playbook graph

A Playbook is a directed acyclic graph (DAG). It has a single starting node and flows sequentially from top to bottom, ending at **Onboarding Complete**. Each node runs in order, passing the user along to the next node, and some nodes execute logic to control branching.

To add a node, click the **+** between any two nodes to open the **Add node** dialog. Nodes are grouped into tabs — **Recipes**, **Data**, **Documents**, **Decision**, **Advanced**, and **AI Nodes** — so you can browse by purpose. Branching nodes fan the flow out into multiple paths; those paths merge back together so the flow can continue to a shared decision.

In [sandbox mode](/articles/guides/sandbox-mode), verification checks don't contact real vendors. By default a mock outcome (Pass, Fail, Manual review, etc.) is chosen and branching is short-circuited to match it. Select **Evaluate rules** to run your Playbook's rules engine normally against the mocked risk signals you choose.

## Collecting data and documents

Most Playbooks begin by collecting data and documents from the user. These are user-facing nodes that pause the onboarding flow to gather input:

* **Identity data** — collect identity data (name, date of birth, SSN, address, etc.) from the user.
* **Business data** — collect business data from the user, for KYB Playbooks.
* **Custom data** — configure a page of custom prompts to collect arbitrary data from the user.
* **Identity document** — collect and verify a government-issued identity document from the user, like a driver's license or passport.
* **Custom document** — configure a custom document to be collected from the user.

Additional collection nodes are available for investor profiles, card data, bank account linking, and proof-of-address or proof-of-SSN documents.

## Branching

Branching nodes split the onboarding into different paths so you can tailor the flow per user. There are two ways to branch:

* **Rules** — express decisioning logic as CEL expressions over risk signals, vaulted data, and onboarding data. Rules are grouped, each group produces an outcome value, groups are evaluated in order, and the first match wins (falling back to a required default value). This is the most flexible option and is covered in detail in [Playbook Rules](/articles/guides/playbooks-playbook-rules).
* **Branch** — a simpler match on a single piece of collected data. You pick a variable (e.g. `id.country`), then define cases with operators like `=`, `!=`, `>`, `in`, and `not in`, plus a **default branch** for anything that doesn't match.

A common use case is splitting U.S. and international users into different document or verification requirements, or sending higher-risk users down a path that has nodes configured to satisfy Enhanced Due Diligence (EDD) requirements.

## Verification checks

A **Verification checks** node runs one or more checks against the data collected so far and produces risk signals that downstream Rules nodes can act on. Available checks include:

* **Know Your Customer (KYC)** — verifies collected identity data against government databases, credit bureaus, and other official sources.
* **Know Your Business (KYB)** — verifies a business via Middesk or Baselayer, either as a full KYB check or TIN (EIN) verification only.
* **Anti-Money Laundering (AML)** — screens against OFAC, PEP, and adverse media lists, with configurable fuzzy/exact matching and optional ongoing monthly screening.
* **Fraud** — synthetic fraud detection with SentiLink.

Some checks require specific data to be collected first (e.g. TIN for KYB, phone + SSN for certain KYC checks), so place verification checks after the relevant data collection nodes.

## External API nodes

An **External API** node calls an external service during onboarding to verify or enrich user data. You can configure it two ways:

* **Vault proxy** — call your own API through a [vault proxy](/articles/guides/vault-proxy) configuration, so request and response bodies can reference vaulted data securely.
* **Managed integration** — dispatch to a Footprint-managed vendor integration.

You define the request (method, base URL, headers, query params) and map fields from the response back into onboarding data using JSONPath (or capture the entire body). You can require a successful `2xx` status code and supply a mock response for sandbox testing. The captured values become available to later nodes as `data.*` variables.

## Data assignment

A **Data assignment** node stores or assigns data into a user's vault at runtime. Each assignment maps a **source** to a **destination** vault field. The source is a templated string, so you can combine literal text with `{{ }}` variables — for example, copying `{{ data.computed_value }}` into `vault.id.ssn9`, or building a note from multiple fields.

Use this to persist computed values, normalize data, or backfill vault fields based on what happened earlier in the flow.

## Expression nodes

An **Expression node** runs one or more [CEL (Common Expression Language)](https://github.com/google/cel-spec) expressions and stores each result in an onboarding data key for later nodes to use. Each expression has an **Assign to** key and an expression body. For example:

```js filename="Expression"
data.risk_score > 20 && vault.id.country != "US" ? "block" : "accept"
```

assigned to `txn_decision` lets a downstream Rules or Branch node act on `data.txn_decision`. CEL supports comparisons, ternaries, string operations, list membership, and JSON parsing — useful for computing intermediate values that don't come directly from a verification check. Press `CTRL + SPACE` in the editor to see available variables.

## Action nodes

An **Action** node applies one or more side effects to the user or business — it doesn't collect data. Place action nodes after your rules to carry out the decision. Available actions:

* **Set decision** — set the onboarding outcome to **Pass**, **Fail**, or **None**.
* **Manual Review** — flag the onboarding for a reviewer, with a reason (e.g. rule triggered, document needs review).
* **Set status** — apply a [custom status](/articles/guides/custom-statuses) defined in your org settings.
* **Tag** — add one or more tags to the user's profile (separate multiple tags with `;`).
* **Note** — add a note to the profile, with support for `{{ }}` dynamic fields.

A single Action node can carry multiple actions, so you can, for example, set a decision and add a tag at the same time.

## Agent nodes

Agent nodes run a Percy AI agent as a step in your Playbook — for example, to review watchlist hits, screen adverse media, or research a business, and return a structured decision the rest of the flow can use.

To add one, open the **Add node** dialog, go to the **AI Nodes** tab, and choose **AI Agent**. Select the new node to open its sidebar, then pick the agent and the agent version it should run. (An agent must have a released version to be selectable, and its latest release is chosen by default.)

Configure the node by providing **Input data** — key/value pairs that feed the agent, using template variables like `{{ vault.id.first_name }}` to pass in vaulted data. When the agent runs, its structured output is written back to onboarding data so downstream Rules, Branch, or Action nodes can act on the agent's conclusion.

Agent nodes pin to a specific released version of an agent, so a Playbook's behavior won't change unexpectedly when you iterate on an agent. Update the node to a newer version when you're ready to roll out changes.