Certification call flow

This guide describes how to create a certification via the Public API. You have three modes available:

1. Hash certification — A single call: you send file names and pre-computed SHA-256 hashes. TrueScreen certifies the hashes without receiving the original files.
2. Data certification — A single call: you send title and required data (key-value strings). No file upload or hash list.
3. File certification — Three calls in sequence: register the files, upload them to temporary URLs, then start the certification. TrueScreen receives the original files and computes their hashes.

For basic concepts (produced artifacts, asynchronous process, credits, metadata), see the certification overview.

In all cases requests must include authentication with an API key.

The same certification flows are available through MCP with curated tools instead of raw HTTP calls.

• On both MCP servers you can use truescreen_create_hash_certification, truescreen_create_data_certification, truescreen_get_certification, and truescreen_wait_for_certification.
• File certification is available only on the local MCP server, which also exposes truescreen_create_file_certification_attachments, truescreen_upload_file, and truescreen_create_file_certification.

See MCP integration for installation and channel selection.

You already have the files and their SHA-256 hashes. You want to certify that those hashes existed at a given time, without uploading the original files.

Endpoint: POST /v1/hash-certifications

Body:

{
  "title": "Project Alpha documents certification",
  "files": [
    {
      "file_name": "contract.pdf",
      "hash": "2661f88efc456652aa9f65f6340fe0213e5bde437e3c613b2a235de81581161e"
    },
    {
      "file_name": "technical-attachment.pdf",
      "hash": "5c5ec4792053e87788d0be3f6c31c77f7e48e02466407da5c16ac1962a00e368"
    }
  ],
  "webhook_url": "https://example.com/webhook/certification",
  "generate_pdf_report": true,
  "metadata": {
    "case_number": "2024/001",
    "client_name": "John Doe"
  }
}

Response (201 Created):

{
  "report_id": "d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff",
  "status": "pending",
  "credits_amount": 2,
  "title": "Project Alpha documents certification",
  "created_at": "2026-03-06T14:30:00Z"
}

• report_id — Unique identifier of the certification. Use it to check status with GET /v1/certifications/{reportId}.
• status — Initial status "pending": certification is being processed asynchronously.
• credits_amount — Credits consumed: 1 per hash sent (in this example, 2 hashes = 2 credits).

You want to certify structured string data (references, contract fields, CRM identifiers) without uploading files or declaring hashes.

Endpoint: POST /v1/data-certifications

Body:

{
  "title": "Contract data attestation",
  "data": {
    "case_number": "2024/001",
    "client_name": "Mario Rossi",
    "contract_ref": "CTR-20240315"
  },
  "webhook_url": "https://example.com/webhook/certification",
  "generate_pdf_report": true
}

Response (201 Created): same shape as hash certification (report_id, status, credits_amount, title, created_at). credits_amount is 1 per certification.

You want to upload the original files so that TrueScreen computes their hashes and certifies them. The process requires three steps in sequence.

Endpoint: POST /v1/file-certifications-attachments

Body:

{
  "files": [
    { "file_name": "contract.pdf" },
    {
      "file_name": "site-inspection-photo.jpg",
      "creation_datetime": "2026-04-08T14:30:00.000Z"
    }
  ]
}

Response (201 Created):

[
  {
    "file_name": "contract.pdf",
    "upload_session_token": "sess_abc123def456",
    "upload_url": "https://s3.amazonaws.com/bucket/contract.pdf?X-Amz-Signature=..."
  },
  {
    "file_name": "site-inspection-photo.jpg",
    "upload_session_token": "sess_abc123def456",
    "upload_url": "https://s3.amazonaws.com/bucket/site-inspection-photo.jpg?X-Amz-Signature=..."
  }
]

• upload_session_token — Unique token for the upload session. It is the same for all files in the same request. You will use it in step 3.
• upload_url — Temporaray presigned URL to upload each file. It has a time limit of 120 seconds.

For each file, send an HTTP PUT to the received upload_url, with the request body equal to the binary content of the file.

PUT https://s3.amazonaws.com/bucket/contract.pdf?X-Amz-Signature=... HTTP/1.1
Content-Type: application/pdf

<binary file content>

The client must use exactly the received URL without adding TrueScreen authentication headers (the signature is in the URL). The only header needed is Content-Type with the file’s MIME type.

Repeat for each file. All files must be uploaded before proceeding to step 3; otherwise creation will fail with error TS-013.

Endpoint: POST /v1/file-certifications

Body:

{
  "title": "Site inspection certification",
  "upload_session_token": "sess_abc123def456",
  "webhook_url": "https://example.com/webhook/certification",
  "generate_pdf_report": true,
  "metadata": {
    "site_id": "SITE-042",
    "inspector": "Jane Smith"
  }
}

Response (201 Created):

{
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "credits_amount": 2,
  "title": "Site inspection certification",
  "created_at": "2026-03-06T15:00:00Z"
}

• credits_amount — Credits consumed: 1 per file uploaded (in this example, 2 files = 2 credits).

1. POST /v1/file-certifications-attachments with file names (and optional per-file creation_datetime) → get upload_session_token and upload_url for each file.
2. PUT upload_url for each file → upload binary content.
3. POST /v1/file-certifications with upload_session_token → start certification.

The process is asynchronous: after creation, the certification is in "pending" status. You can know when it is complete in two ways.

Endpoint: GET /v1/certifications/{reportId}

Poll this endpoint periodically, passing the report_id received in the creation response.

Response (certification in progress):

{
  "report_id": "d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff",
  "status": "pending",
  "created_at": "2026-03-06T14:30:00Z",
  "title": "Project Alpha documents certification",
  "files": []
}

Response (certification completed):

{
  "report_id": "d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff",
  "status": "completed",
  "created_at": "2026-03-06T14:30:00Z",
  "title": "Project Alpha documents certification",
  "files": [
    {
      "type": "data",
      "url": "https://s3.example.com/d8c2aef3.json?X-Amz-Signature=..."
    },
    {
      "type": "report",
      "url": "https://s3.example.com/d8c2aef3.pdf?X-Amz-Signature=..."
    },
    {
      "type": "xml",
      "url": "https://s3.example.com/d8c2aef3.xml?X-Amz-Signature=..."
    }
  ]
}

Files in the files array have a type field that identifies the artifact:

URLs are signed (presigned) and expire after 60 seconds: download the files within the validity period.

Response (certification failed after async processing):

If the creation POST succeeded but later processing fails, GET /v1/certifications/{reportId} returns 500, Content-Type: application/problem+json, and this RFC 9457 problem body:

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{
  "type": "https://truescreen.redocly.app/errors/server-error",
  "title": "Certification processing error",
  "status": 500,
  "detail": "Digital sign error.",
  "code": "TS-014"
}

If you passed a webhook_url in the creation request, TrueScreen sends an HTTP POST callback to that URL when processing finishes — success or failure.

The callback payload uses the Standard Webhooks envelope format:

• certification.completed — data matches the 200 GET response (certification object with files).
• certification.error — data contains the application/problem+json document the GET would return for that outcome.

Every callback is signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). See Certification — Overview for verification details.

For the full error response format, see API errors.