Quickstart

This guide takes you from an empty account to a signed PDF. You create a case with one participant, upload the document, wait for the signature and download the result. Everything runs against the sandbox, TrustInk’s environment for testing.

You need curl and jq, a PDF of 1 KB to 25 MB, and an email address you can read for the participant.

1. Get API credentials

   Sign in to the tenant portal and open API credentials. Create a client for your integration and copy its client ID, client secret and token URL. The secret is shown once; keep it in your secret store, never in the browser or a mobile app.

   export API=https://api-sandbox.trustink.io
   export TOKEN_URL=...        # shown next to your credentials
   export CLIENT_ID=...
   export CLIENT_SECRET=...

2. Get an access token

   Exchange the credentials for a token with the OAuth 2.0 client credentials grant. The client authenticates with HTTP Basic.

   export TOKEN=$(curl -s -X POST "$TOKEN_URL" \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d grant_type=client_credentials | jq -r .access_token)

   Send it as Authorization: Bearer <token> on every tenant request. Cache it until shortly before expires_in runs out instead of fetching one per request.

3. Create a case

   A case is one document and the people who sign it. title, validUntil and participants are required; callback tells TrustInk where to send webhooks.

   curl

   curl -s -X POST "$API/cases" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{
       "title": "Service contract 2026/0142",
       "validUntil": "2026-10-31T23:59:59Z",
       "participants": [
         {"firstName": "Jana", "lastName": "Nováková", "email": "jana.novakova@example.com", "language": "sk"}
       ],
       "callback": {
         "url": "https://example.com/trustink/webhook",
         "authType": "NONE",
         "signingSecret": "replace-with-32-to-128-random-characters",
         "data": {"orderId": 4711}
       }
     }' > case.json

   Node.js

   const response = await fetch(`${process.env.API}/cases`, {
     method: 'POST',
     headers: {authorization: `Bearer ${token}`, 'content-type': 'application/json'},
     body: JSON.stringify({
       title: 'Service contract 2026/0142',
       validUntil: '2026-10-31T23:59:59Z',
       participants: [{firstName: 'Jana', lastName: 'Nováková', email: 'jana.novakova@example.com', language: 'sk'}],
       callback: {
         url: 'https://example.com/trustink/webhook',
         authType: 'NONE',
         signingSecret: process.env.TRUSTINK_WEBHOOK_SECRET,
         data: {orderId: 4711},
       },
     }),
   });
   const {case: created, upload} = await response.json();

   The answer holds the case in status NEW and where to put the document:

   {
     "case": {
       "id": "49d4ae62-…",
       "title": "Service contract 2026/0142",
       "status": "NEW",
       "validUntil": "2026-10-31T23:59:59.000Z",
       "participants": [
         {"id": "7a1c…", "firstName": "Jana", "lastName": "Nováková", "status": "UNSIGNED",
          "signerUrl": "https://…", "signatureFields": []}
       ]
     },
     "upload": {"type": "PUT", "url": "https://…"}
   }

   Each participant’s signerUrl is their personal signing link. TrustInk emails it to them; you can also show it in your own system.

4. Upload the PDF

   PUT the document to upload.url within an hour. It must be a PDF of 1 KB to 25 MB.

   export CASE_ID=$(jq -r .case.id case.json)
   curl -s -X PUT -H 'Content-Type: application/pdf' \
     --upload-file contract.pdf "$(jq -r .upload.url case.json)"

   The case moves to IN_PROGRESS and the participants are invited by email. Open the link in Jana’s mailbox and sign. A file that is not a PDF of the right size moves the case to UPLOAD_REJECTED with a rejectReason.

5. Wait for the signatures

   Webhook

   TrustInk POSTs participant-signed after each signature and case-completed once the signed PDF is ready. Verify the Trustink-Signature header before you trust the body; the webhooks guide has samples in Node.js, Java and C#.

   {
     "id": "7b1e4c2a-…",
     "type": "case-completed",
     "occurredAt": "2026-09-23T15:40:00Z",
     "caseId": "49d4ae62-…",
     "status": "DONE",
     "data": {"orderId": 4711},
     "signedDocument": {"url": "https://…"},
     "evidenceDocument": {"url": "https://…"}
   }

   Polling

   Without a public endpoint, read the case until it leaves IN_PROGRESS. Poll gently, for example every 30 seconds.

   until [ "$(curl -s "$API/cases/$CASE_ID" -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "IN_PROGRESS" ]; do
     sleep 30
   done

   DONE means everyone signed. EXPIRED, CANCELLED and FAILED end the case without a signed document.

6. Download the signed PDF and the evidence

   Once the case is DONE, GET /cases/{caseId} links both documents with short-lived presigned URLs:

   curl -s "$API/cases/$CASE_ID" -H "Authorization: Bearer $TOKEN" > done.json
   curl -s -o signed.pdf "$(jq -r .signedDocument.url done.json)"
   curl -s -o evidence.pdf "$(jq -r .evidenceDocument.url done.json)"

   • signed.pdf carries one signature per participant, each with a certificate that names them, closed with the TrustInk seal and extended to PAdES B-LTA (signedDocument.level).
   • evidence.pdf is the sealed evidence summary: every participant’s steps, the document’s SHA-256 and the certificates.

   Links in webhooks work for an hour. Fetch a fresh one with GET /cases/{caseId} whenever you need it.

Check the result

Upload signed.pdf to trustink.io/verify or call POST /verify to see every signature validated with the EU DSS library.

Next steps

• Place the signature exactly where it belongs with signature fields.
• Ask each signer for a one-time code by email.
• Let people sign in person on a kiosk.
• Browse every route in the API reference.