# True Flow Call Flow

This guide describes how to create a True Flow via the Public API. In short you have **three options**:

1. **Simple creation** — A single call to `POST /true-flows` with `template_token` and `name`. The flow starts with the template’s default values; the end user receives the link and fills out the form from start to finish.
2. **Creation with pre-filled data and/or signers** — Still `POST /true-flows`, but with `flow_data` (form fields already filled) and/or `sign_data` (list of signers). Useful when integrating with your systems and you want to pre-fill contact details, case references, or signing invitations.
3. **Creation with attachments** — The template requires documents to be uploaded. First obtain a token and upload URL (`POST /true-flows-attachments`), upload the file with a `PUT`, then create the True Flow with `POST /true-flows` passing the attachment tokens in `flow_data`. The first two steps must be done in sequence for each file.


You can also **combine** options: for example pre-filled data, signers, and attachments in the same creation (uploads first, then a single `POST /true-flows` with everything). The following sections go into detail for each case.

## Quick Reference

| Scenario | Main calls |
|  --- | --- |
| [Simple](#1-simple-true-flow-creation) | POST /true-flows |
| [With pre-filled data](#2-true-flow-creation-with-pre-filled-data) | POST /true-flows with `flow_data` |
| [With attachments](#3-true-flow-creation-with-attachments) | POST /true-flows-attachments → PUT upload_url → POST /true-flows with tokens in `flow_data` |
| [With signers](#4-true-flow-creation-with-signers) | POST /true-flows with `sign_data` |


In all cases requests must include [authentication](#authentication) with an API key. For context on the tokens used in the calls, see [Flow template token](#flow-template-token); for combining multiple options in a single creation, see [Combining multiple options](#combining-multiple-options).

## True Flow through MCP

True Flow operations are also available through MCP.

- `truescreen_list_templates` and `truescreen_create_true_flow` are available on both the **remote** and **local** MCP server.
- Uploading attachments for a True Flow is available only on the **local** MCP server through `truescreen_create_true_flow_attachment`.


See [MCP integration](/mcp-integration) for installation and channel selection.

## Flow template token

The **flow template token** is the identifier of the flow model you want to instantiate. It is created and managed by TrueScreen: you do not generate it, you **use** it in True Flow creation calls.

The token is **unique for that flow type** and remains valid even if the template evolves over time: you do not need to call **GET /templates** for every creation. Flow templates are a **catalog** to choose from: once you know the `template_token`, you can reuse it for all instances you create.

### How to get the flow template token

1. **GET /templates** — Call this endpoint when you need to consult the catalog: it returns the list of flow templates available for your API key.
2. The response includes, for each template, the **template_token**.
3. The response includes, when applicable, the **schema or list of fields** you can fill in `flow_data` and `sign_data` (pre-fillable form fields and signer structure). The exact shape is defined in the OpenAPI spec for `GET /templates`.


In short: use **GET /templates** when you need to discover or update the catalog and fillable fields; to create a True Flow you always use **POST /true-flows** with the **template_token** you already have.

## Use cases

### 1. Simple True Flow creation

Create a True Flow by passing only the flow template token. The flow is created with the default values defined in the template; the end user will fill out the form from the returned link.

**Endpoint:** `POST /true-flows`

**Minimum body:**

```json
{
  "template_token": "<token_from_GET_templates>",
  "name": "Flow name"
}
```

**Response:** contains the True Flow **token** and the **trueLink** (deeplink) URL to send to the user.

### 2. True Flow creation with pre-filled data

You want to pre-fill some form fields (e.g. name, email, case reference). The fillable fields are those returned in the flow template schema (GET /templates).

**Endpoint:** `POST /true-flows`

**Body:**

```json
{
  "template_token": "<template_token>",
  "name": "Flow with pre-filled data",
  "flow_data": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }
}
```

- **flow_data** is a key-value object: keys are the field names defined in the template; values must match the schema type and constraints.
- Values in `flow_data` become the **default values** of the form.


### 3. True Flow creation with attachments

To attach files to the flow, **three calls** in sequence are required.

#### Step 1 — Get token and upload URL

**Endpoint:** `POST /true-flows-attachments`

**Body:**

```json
{
  "file_name": "document.pdf"
}
```

**Response:**

```json
{
  "token": "<attachment_token>",
  "file_name": "document.pdf",
  "upload_url": "https://..."
}
```

- **token:** identifier of the attachment; you will use it in `flow_data`.
- **upload_url:** Temporary presigned URL for uploading the file. It has a time limit of 120 seconds.


#### Step 2 — Upload the file

Send a **PUT** request to the returned **upload_url**, with the request body equal to the binary content of the file (e.g. `Content-Type: application/pdf` for a PDF).

The HTTP client must use exactly the returned URL; do not add extra headers not required by the signed URL (usually only `Content-Type` and the body).

#### Step 3 — Create the True Flow including attachments

**Endpoint:** `POST /true-flows`

In **flow_data**, put the attachment tokens in the fields the flow template reserves for attachments (e.g. a field like `documents` that accepts an array of tokens).

**Example body:**

```json
{
  "template_token": "<template_token>",
  "name": "Flow with attachment",
  "flow_data": {
    "documents": ["<attachment_token_1>", "<attachment_token_2>"]
  }
}
```

- The field names for attachments (e.g. `documents`) depend on the flow template; you can get them from the schema returned by **GET /templates** (fields with `format: "attachment"`).
- Each array element is the **token** returned by **POST /true-flows-attachments** after completing the upload with PUT.


**Sequence summary:**

1. For each file: `POST /true-flows-attachments` → get `token` and `upload_url`.
2. For each file: `PUT upload_url` with body = file content.
3. `POST /true-flows` with `flow_data` containing, in the template’s attachment fields, the token arrays.


### 4. True Flow creation with signers

If the flow template has a signers section (`signData`), you can pass signer data in the **sign_data** array.

**Endpoint:** `POST /true-flows`

**Example body:**

```json
{
  "template_token": "<template_token>",
  "name": "Flow with signers",
  "sign_data": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    },
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com"
    }
  ]
}
```

- **sign_data** is an array of objects; each object corresponds to one signer.
- The allowed fields (e.g. `first_name`, `last_name`, `email`) depend on the flow template’s **signData** schema; you can get it from **GET /templates**.
- Values are used in the flow’s signers section and for the signing invitation.


## Combining multiple options

You can combine **flow_data**, **sign_data**, and attachments in the same **POST /true-flows** call:

```json
{
  "template_token": "<template_token>",
  "name": "Complete flow",
  "flow_data": {
    "reference": "CASE-2024-001",
    "documents": ["<attachment_token>"]
  },
  "sign_data": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  ]
}
```

The required order remains: first any **POST /true-flows-attachments** and **PUT** uploads, then **POST /true-flows** with all tokens and data.