{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Certification call flow","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"certification-call-flow","__idx":0},"children":["Certification call flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide describes how to create a certification via the Public API. You have ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["three modes"]}," available:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hash certification"]}," — A single call: you send file names and pre-computed SHA-256 hashes. TrueScreen certifies the hashes without receiving the original files."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data certification"]}," — A single call: you send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," and required ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," (key-value strings). No file upload or hash list."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For basic concepts (produced artifacts, asynchronous process, credits, metadata), see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/certification-overview"},"children":["certification overview"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-reference","__idx":1},"children":["Quick Reference"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Calls"},"children":["Calls"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#1-hash-certification"},"children":["Hash certification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/hash-certifications"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#2-data-certification"},"children":["Data certification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/data-certifications"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#3-file-certification"},"children":["File certification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications-attachments"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT upload_url"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#4-checking-certification-status"},"children":["Check status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/certifications/{reportId}"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all cases requests must include ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/#authentication"},"children":["authentication"]}," with an API key."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"certification-through-mcp","__idx":2},"children":["Certification through MCP"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same certification flows are available through MCP with curated tools instead of raw HTTP calls."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On both MCP servers you can use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_create_hash_certification"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_create_data_certification"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_get_certification"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_wait_for_certification"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["File certification is available only on the local MCP server, which also exposes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_create_file_certification_attachments"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_upload_file"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["truescreen_create_file_certification"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp-integration"},"children":["MCP integration"]}," for installation and channel selection."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-cases","__idx":3},"children":["Use cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-hash-certification","__idx":4},"children":["1. Hash certification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/hash-certifications"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"title\": \"Project Alpha documents certification\",\n  \"files\": [\n    {\n      \"file_name\": \"contract.pdf\",\n      \"hash\": \"2661f88efc456652aa9f65f6340fe0213e5bde437e3c613b2a235de81581161e\"\n    },\n    {\n      \"file_name\": \"technical-attachment.pdf\",\n      \"hash\": \"5c5ec4792053e87788d0be3f6c31c77f7e48e02466407da5c16ac1962a00e368\"\n    }\n  ],\n  \"webhook_url\": \"https://example.com/webhook/certification\",\n  \"generate_pdf_report\": true,\n  \"metadata\": {\n    \"case_number\": \"2024/001\",\n    \"client_name\": \"John Doe\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification title"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of objects with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_name"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hash"]}," (SHA-256, 64 hex characters)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL for callback on completion"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate_pdf_report"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether to generate a PDF report (defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key-value object with custom data to include in jsonData and, when generated, in the PDF report"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (201 Created):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"report_id\": \"d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff\",\n  \"status\": \"pending\",\n  \"credits_amount\": 2,\n  \"title\": \"Project Alpha documents certification\",\n  \"created_at\": \"2026-03-06T14:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]}]}," — Unique identifier of the certification. Use it to check status with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/certifications/{reportId}"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]}," — Initial status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"pending\""]},": certification is being processed asynchronously."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credits_amount"]}]}," — Credits consumed: 1 per hash sent (in this example, 2 hashes = 2 credits)."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-data-certification","__idx":5},"children":["2. Data certification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You want to certify structured string data (references, contract fields, CRM identifiers) without uploading files or declaring hashes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/data-certifications"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"title\": \"Contract data attestation\",\n  \"data\": {\n    \"case_number\": \"2024/001\",\n    \"client_name\": \"Mario Rossi\",\n    \"contract_ref\": \"CTR-20240315\"\n  },\n  \"webhook_url\": \"https://example.com/webhook/certification\",\n  \"generate_pdf_report\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification title"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object with at least one key-value pair; keys and values must be strings"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL for callback on completion"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate_pdf_report"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether to generate a PDF report (defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (201 Created):"]}," same shape as hash certification (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credits_amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]},"). ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credits_amount"]}]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1"]}," per certification."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-file-certification","__idx":6},"children":["3. File certification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You want to upload the original files so that TrueScreen computes their hashes and certifies them. The process requires ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["three steps"]}," in sequence."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-1--register-files-and-get-upload-urls","__idx":7},"children":["Step 1 — Register files and get upload URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications-attachments"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"files\": [\n    { \"file_name\": \"contract.pdf\" },\n    {\n      \"file_name\": \"site-inspection-photo.jpg\",\n      \"creation_datetime\": \"2026-04-08T14:30:00.000Z\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Non-empty array."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files[].file_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["File name."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files[].creation_datetime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date-time"]}," (not in the future). Optional: when present and valid, used as creation date in jsonData for that attachment."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (201 Created):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"file_name\": \"contract.pdf\",\n    \"upload_session_token\": \"sess_abc123def456\",\n    \"upload_url\": \"https://s3.amazonaws.com/bucket/contract.pdf?X-Amz-Signature=...\"\n  },\n  {\n    \"file_name\": \"site-inspection-photo.jpg\",\n    \"upload_session_token\": \"sess_abc123def456\",\n    \"upload_url\": \"https://s3.amazonaws.com/bucket/site-inspection-photo.jpg?X-Amz-Signature=...\"\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_url"]}]}," — Temporaray presigned URL to upload each file. It has a time limit of 120 seconds."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-2--upload-the-files","__idx":8},"children":["Step 2 — Upload the files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each file, send an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP PUT"]}," to the received ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_url"]},", with the request body equal to the binary content of the file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT https://s3.amazonaws.com/bucket/contract.pdf?X-Amz-Signature=... HTTP/1.1\nContent-Type: application/pdf\n\n<binary file content>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The client must use exactly the received URL without adding TrueScreen authentication headers (the signature is in the URL). The only header needed is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}," with the file’s MIME type."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Repeat for each file. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["All files must be uploaded"]}," before proceeding to step 3; otherwise creation will fail with error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-013"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-3--create-the-certification","__idx":9},"children":["Step 3 — Create the certification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"title\": \"Site inspection certification\",\n  \"upload_session_token\": \"sess_abc123def456\",\n  \"webhook_url\": \"https://example.com/webhook/certification\",\n  \"generate_pdf_report\": true,\n  \"metadata\": {\n    \"site_id\": \"SITE-042\",\n    \"inspector\": \"Jane Smith\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification title"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_session_token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token received in step 1"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL for callback on completion"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate_pdf_report"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether to generate a PDF report (defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key-value object with custom data"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (201 Created):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"report_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"status\": \"pending\",\n  \"credits_amount\": 2,\n  \"title\": \"Site inspection certification\",\n  \"created_at\": \"2026-03-06T15:00:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credits_amount"]}]}," — Credits consumed: 1 per file uploaded (in this example, 2 files = 2 credits)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"file-certification-sequence-summary","__idx":10},"children":["File certification sequence summary"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications-attachments"]}," with file names (and optional per-file ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creation_datetime"]},") → get ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_session_token"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_url"]}," for each file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT upload_url"]}," for each file → upload binary content."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_session_token"]}," → start certification."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-checking-certification-status","__idx":11},"children":["4. Checking certification status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The process is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asynchronous"]},": after creation, the certification is in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"pending\""]}," status. You can know when it is complete in two ways."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"polling","__idx":12},"children":["Polling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/certifications/{reportId}"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll this endpoint periodically, passing the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]}," received in the creation response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (certification in progress):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"report_id\": \"d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff\",\n  \"status\": \"pending\",\n  \"created_at\": \"2026-03-06T14:30:00Z\",\n  \"title\": \"Project Alpha documents certification\",\n  \"files\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (certification completed):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"report_id\": \"d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff\",\n  \"status\": \"completed\",\n  \"created_at\": \"2026-03-06T14:30:00Z\",\n  \"title\": \"Project Alpha documents certification\",\n  \"files\": [\n    {\n      \"type\": \"data\",\n      \"url\": \"https://s3.example.com/d8c2aef3.json?X-Amz-Signature=...\"\n    },\n    {\n      \"type\": \"report\",\n      \"url\": \"https://s3.example.com/d8c2aef3.pdf?X-Amz-Signature=...\"\n    },\n    {\n      \"type\": \"xml\",\n      \"url\": \"https://s3.example.com/d8c2aef3.xml?X-Amz-Signature=...\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Files in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]}," array have a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," field that identifies the artifact:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"type"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Artifact"},"children":["Artifact"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["jsonData"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Machine-readable JSON document with hashes and metadata"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PDF report"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable PDF with key data (only if report generation is enabled in configuration)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["xml"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signed XML"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Digitally signed and timestamped XML envelope"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["media"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Original files"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The uploaded files (file certification only)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["URLs are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["signed"]}," (presigned) and expire after 60 seconds: download the files within the validity period."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (certification failed after async processing):"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the creation ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," succeeded but later processing fails, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/certifications/{reportId}"]}]}," returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/problem+json"]}]},", and this RFC 9457 problem body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"HTTP/1.1 500 Internal Server Error\nContent-Type: application/problem+json\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://truescreen.redocly.app/errors/server-error\",\n  \"title\": \"Certification processing error\",\n  \"status\": 500,\n  \"detail\": \"Digital sign error.\",\n  \"code\": \"TS-014\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"webhook","__idx":13},"children":["Webhook"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you passed a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_url"]}," in the creation request, TrueScreen sends an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP POST callback"]}," to that URL when processing ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["finishes — success or failure"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback payload uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standard Webhooks"]}," envelope format:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["certification.completed"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," matches the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["200"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," response (certification object with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["certification.error"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," contains the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]}]}," document the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," would return for that outcome."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every callback is signed with Standard Webhooks headers (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]},"). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/certification-overview#signature-verification"},"children":["Certification — Overview"]}," for verification details."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-errors","__idx":14},"children":["Common errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Situation"},"children":["Situation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-001"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed payload"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the request JSON structure"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-002"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing required field"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_session_token"]}," are present"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-008"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient credits"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check balance with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/credits"]}," and purchase credits from the TrueScreen portal"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-010"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reportId"]}," passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/certifications/{reportId}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-012"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upload session token already used"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload_session_token"]}," can create only one certification"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-013"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not all files uploaded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Complete upload of all files before calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TS-014"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification processing failed after creation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/server-error#certification-processing-failure"},"children":["Server errors"]},"; webhook sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["certification.error"]}," event"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the full error response format, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors"},"children":["API errors"]},"."]}]},"headings":[{"value":"Certification call flow","id":"certification-call-flow","depth":1},{"value":"Quick Reference","id":"quick-reference","depth":2},{"value":"Certification through MCP","id":"certification-through-mcp","depth":2},{"value":"Use cases","id":"use-cases","depth":2},{"value":"1. Hash certification","id":"1-hash-certification","depth":3},{"value":"2. Data certification","id":"2-data-certification","depth":3},{"value":"3. File certification","id":"3-file-certification","depth":3},{"value":"Step 1 — Register files and get upload URLs","id":"step-1--register-files-and-get-upload-urls","depth":4},{"value":"Step 2 — Upload the files","id":"step-2--upload-the-files","depth":4},{"value":"Step 3 — Create the certification","id":"step-3--create-the-certification","depth":4},{"value":"File certification sequence summary","id":"file-certification-sequence-summary","depth":4},{"value":"4. Checking certification status","id":"4-checking-certification-status","depth":3},{"value":"Polling","id":"polling","depth":4},{"value":"Webhook","id":"webhook","depth":4},{"value":"Common errors","id":"common-errors","depth":2}],"frontmatter":{"title":"Certification call flow","description":"Operational guide for creating a certification (hash or file) via the Public API","seo":{"title":"Certification call flow"}},"lastModified":"2026-06-25T15:58:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/certification-workflow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}