Certified Partner API

Create tamper-proof digital certificates for documents, photos, and videos. Each certificate gets a unique verification URL accessible by anyone.

Documents

Certify contracts, invoices, diplomas, official records.

Photos

Authenticate images with verified issuer identity.

Videos

Certify video content with frame-level verification.

Quick Start

1 Create your issuer account on the portal
2 Wait for account verification by our team
3 Generate a test API key from the portal
4 Make your first API call (see below)
5 Switch to a live API key for production

Authentication

All API requests require an API key sent via the X-API-Key header.

Header

X-API-Key: tc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

TEST

Test Keys

Prefix: tc_test_

No credits consumed
Certificates expire in 7 days max
Limited to 50 certificates/day
Certificates marked as "test"

LIVE

Live Keys

Prefix: tc_live_

1 credit per certificate
Expiration up to 10 years
Certificates publicly verifiable
Full production use

Create Certificate

POST /api/issuer/certificates

Create a new authenticated certificate. Accepts JSON or multipart/form-data for file uploads.

Option 1: JSON (hash only)

Send a file hash without uploading the file. Useful when you store the file yourself.

Request

curl -X POST https://truth-check.com/api/issuer/certificates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tc_live_xxxxx" \
  -d '{
    "certificateType": "issued_document",
    "fileHash": "sha256:e3b0c44298fc...",
    "holderName": "Jean Dupont",
    "issuerReferenceId": "DOC-2026-001",
    "expirationDays": 365,
    "visibility": "public",
    "tags": ["formation", "2026", "paris"]
  }'

Option 2: File Upload (multipart)

Upload a PDF, image, or other file. The hash is computed automatically.

Request

curl -X POST https://truth-check.com/api/issuer/certificates \
  -H "X-API-Key: tc_live_xxxxx" \
  -F "certificateType=issued_document" \
  -F "holderName=Jean Dupont" \
  -F "issuerReferenceId=DOC-2026-001" \
  -F "expirationDays=365" \
  -F "visibility=public" \
  -F 'tags=["formation","2026","paris"]' \
  -F "file=@/path/to/document.pdf"

Parameters

Parameter	Type	Required	Description
certificateType	string	required	`issued_document`, `issued_photo`, or `issued_video`
fileHash	string	optional*	SHA-256 hash of the file. Auto-computed when uploading a file.
holderName	string	optional	Name of the person or entity the certificate is issued for.
issuerReferenceId	string	optional	Your internal reference ID for cross-referencing.
expirationDays	integer	optional	Certificate validity in days. Default: `90`. Max: `3650`.
visibility	string	optional	`public` (default) or `password_protected`
password	string	conditional	Required when `visibility` is `password_protected`.
metadata	object	optional	Custom key-value metadata attached to the certificate.
tags	string[]	optional	Array of tags for searchable categorisation. Max `10` tags, max `30` chars each. Tags are automatically normalised: lowercase, accents removed, alphanumeric only (e.g. `"Île-de-France"` → `"iledefrance"`). Supports progressive prefix search — typing `"for"` finds certificates tagged `"formation"`. In multipart mode, pass as JSON string: `-F 'tags=["tag1","tag2"]'`.
file	File	optional	File to upload (multipart only). Max 20 MB. Accepted: JPEG, PNG, GIF, WebP, PDF.

Response

201 Created

{
  "id": "C7zTvInjv7Tnh88aeCxp",
  "certifId": "BV56P5MSB6",
  "url": "https://truth-check.com/BV56P5MSB6",
  "certificateType": "issued_document",
  "fileHash": "sha256:e3b0c44298fc1c149...",
  "holderName": "Jean Dupont",
  "issuerReferenceId": "DOC-2026-001",
  "imageUrls": ["https://storage.googleapis.com/..."],
  "tags": ["formation", "2026", "paris"],
  "creditsUsed": 1,
  "remainingCredits": 9,
  "status": "active",
  "expirationDate": "2027-03-16T21:12:33.846Z",
  "createdAt": "2026-03-16T21:12:33.846Z"
}

List Certificates

GET /api/issuer/certificates

Retrieve all certificates created by your issuer account. Supports pagination.

Request

curl https://truth-check.com/api/issuer/certificates?limit=20 \
  -H "X-API-Key: tc_live_xxxxx"

Query Parameters

Parameter	Type	Description
limit	integer	Max results per page. Default: `20`, max: `100`.
startAfter	string	Document ID to start after (for pagination). Use `nextStartAfter` from previous response.
status	string	Filter by status: `active`, `test`, `expired`.
search	string	Full-text search across `holderName`, `issuerReferenceId`, `certifId`, and tags (progressive prefix matching — `?search=for` matches tag `"formation"`).

200 OK

{
  "certificates": [
    {
      "id": "C7zTvInjv7Tnh88aeCxp",
      "certifId": "BV56P5MSB6",
      "url": "https://truth-check.com/BV56P5MSB6",
      "certificateType": "issued_document",
      "holderName": "Jean Dupont",
      "issuerReferenceId": "DOC-2026-001",
      "tags": ["formation", "2026", "paris"],
      "status": "active",
      "date": "2026-03-16T21:12:33.846Z",
      "expirationDate": "2027-03-16T21:12:33.846Z"
    }
  ],
  "hasMore": false
}

Get Certificate

GET /api/issuer/certificates/:id

Retrieve a specific certificate by document ID or certifId. Only returns certificates belonging to your issuer account.

Request

curl https://truth-check.com/api/issuer/certificates/BV56P5MSB6 \
  -H "X-API-Key: tc_live_xxxxx"

200 OK

{
  "id": "C7zTvInjv7Tnh88aeCxp",
  "certifId": "BV56P5MSB6",
  "url": "https://truth-check.com/BV56P5MSB6",
  "certificateType": "issued_document",
  "fileHash": "sha256:e3b0c44298fc1c149...",
  "holderName": "Jean Dupont",
  "issuerReferenceId": "DOC-2026-001",
  "issuerName": "SNCF Test",
  "imageUrls": ["https://storage.googleapis.com/..."],
  "tags": ["formation", "2026", "paris"],
  "status": "active",
  "isProtected": false,
  "createdAt": "2026-03-16T21:12:33.846Z",
  "expirationDate": "2027-03-16T21:12:33.846Z"
}

Check Credits

GET /api/issuer/credits

Check your current credit balance. Each certificate (live mode) costs 1 credit.

Request

curl https://truth-check.com/api/issuer/credits \
  -H "X-API-Key: tc_live_xxxxx"

200 OK

{
  "credits": {
    "current": 10,
    "total": 50
  },
  "issuer": {
    "publicName": "SNCF Test",
    "verificationStatus": "verified"
  }
}

Error Codes

All errors return a JSON object with an error field.

Status	Meaning	Example
400	Bad Request	Missing or invalid `certificateType`
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits (live mode only)
403	Forbidden	Partner account not verified or suspended
404	Not Found	Certificate not found or doesn't belong to your account
429	Too Many Requests	Daily test certificate limit reached (50/day)
500	Server Error	Internal error — please retry or contact support

Error response format

{
  "error": "Insufficient credits. Please top up your issuer account."
}

Test Mode

Use test API keys (tc_test_*) to experiment without consuming credits.

Test mode limitations

Certificates are marked with status: "test"
Expiration capped at 7 days regardless of expirationDays value
Maximum 50 certificates per day per issuer
Verification page shows a test certificate banner
Expired test certificates are automatically deleted

Verification page appearance

Test certificates display a prominent amber banner on the public verification page:

Test Certificate

This certificate was created with a test API key. It has no legal value and will be automatically deleted.

Need help? Contact us at [email protected]

Partner Portal · Truth-Check