# TrueScreen Public API

Documentation for the TrueScreen Public API for external integrations. Here you will find the main entity definitions and usage guides.

## Authentication

Authentication is via **API key**. Every request to Public API endpoints must include your API key in the **`Authorization: Bearer <api_key>`** header.

The API key is obtained from the TrueScreen portal (*TBD*) and is associated with a workspace. Requests without a valid API key receive **401 Unauthorized**. The API key determines the workspace (and thus the flow templates and resources) you can access.

## Definitions

### True Flow

A **True Flow** is an instance of a data collection flow. It is used to generate **data entry and collection forms** that the end user fills out via the TrueScreen web or mobile interface. The interface is reached via a unique link (trueLink). Data is then processed by the TrueScreen app and you can eventually obtain a **certification**.

- It is **created** with `POST /true-flows` from a **Flow Template** (identified by `template_token`).
- It can include pre-filled data (`flow_data`), signers (`sign_data`), and attachments (tokens from `POST /true-flows-attachments`).
- The response contains the **trueLink** (deeplink) to send to the user to fill out the form.


### Flow Template

A **Flow Template** is the **model** that defines how data is collected. It describes the structure of the form the end user sees in the TrueScreen app (steps, fields, input types, attachments, signature, etc.).

- It is created and managed by TrueScreen.
- It is identified by a **template_token** that is unique and stable over time (even if the template evolves).
- The Flow Templates available for your API key form a **catalog**: you can get the list and field schema with **GET /templates**.
- To create a True Flow you use the `template_token` in the body of **POST /true-flows**, without having to call GET /templates for each creation.


### Flow Data

An object that describes via [JSON Schema](https://json-schema.org/) the True Flow fields that can be pre-filled. These fields will be included in the report and in the certification’s jsonData file. They may be visible and editable by the user who certifies depending on configuration:

- if the field has the `readOnly` attribute set to `true` it cannot be edited
- if the field has the `format` attribute set to `hidden` it will not be visible to the user


### Sign Data

An array of objects that describes via [JSON Schema](https://json-schema.org/) the True Flow fields that indicate the signers of the case. Depending on the True Flow configuration, these fields can be used to send the signing request email. They may be visible and editable by the user who certifies depending on configuration:

- if the field has the `readOnly` attribute set to `true` it cannot be edited
- if the field has the `format` attribute set to `hidden` it will not be visible to the user


### Certification

A **certification** is the process by which one or more digital files are cryptographically certified to attest their existence, integrity, and provenance at a given time. The result is a set of digitally signed artifacts (jsonData, optional PDF report, signed XML with timestamp). The Public API offers two modes:

- **Hash certification** (`POST /v1/hash-certifications`) — the client sends file names and SHA-256 hashes. No file upload. Cost: 1 credit per hash sent.
- **File certification** (`POST /v1/file-certifications-attachments` + upload + `POST /v1/file-certifications`) — the client uploads the original files. Cost: 1 credit per file.


Generation is **asynchronous**: you can receive the result via **webhook** or by calling `GET /v1/certifications/{reportId}`. Webhook callbacks follow the **[Standard Webhooks](https://www.standardwebhooks.com)** specification: the payload uses a standard envelope (`type`, `timestamp`, `data`) and every callback is signed with HMAC-SHA256 headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) for authenticity verification. For details, see the guides below.

## Guides

### True Flow

- [True Flow call flow](/true-flow-workflow) — Simple creation, with pre-filled data, attachments, and signers.


### Certification

- [Certification — Overview](/certification-overview) — Concepts, modes (hash vs file), produced artifacts, asynchronous process, credits, and metadata.
- [Certification call flow](/certification-workflow) — Operational guide with API call sequences for hash and file certification.


### General references

- [API errors](/errors) — RFC 9457 format, code list, and detail pages for each error type.


For endpoint and schema reference, use the [OpenAPI spec](/openapi) and interactive documentation.

Version 1.6