Skip to content
Last updated

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 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 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}. If processing fails after creation, expect an HTTP error status and application/problem+json; the webhook uses the same error payload as that GET. For details, see the guides below.

Guides

True Flow

Certification

General references

  • API errors — RFC 9457 format, code list, and detail pages for each error type.

For endpoint and schema reference, use the OpenAPI spec and interactive documentation.

Version 1.4

 
Next page