Skip to content
True Flow
/
Workflow
Last updated

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

ScenarioMain calls
SimplePOST /true-flows
With pre-filled dataPOST /true-flows with flow_data
With attachmentsPOST /true-flows-attachments → PUT upload_url → POST /true-flows with tokens in flow_data
With signersPOST /true-flows with sign_data

In all cases requests must include authentication with an API key. For context on the tokens used in the calls, see Flow template token; for combining multiple options in a single creation, see 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 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:

{
  "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:

{
  "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:

{
  "file_name": "document.pdf"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

Previous page
Next page