Tidvis Sign Public API

Snabbstart

Base URL: https://tidvis.se/api/public/v1. Alla anrop använder JSON. Public API är en del av Enterprise-planen.

1. 1. Skapa en API-klient under Sign → Inställningar → API och spara client_id och client_secret.
2. 2. Hämta en access_token via OAuth2 client credentials.
3. 3. Skapa ett avtal, ladda upp en PDF, lägg till deltagare och skicka.

curl -X POST https://tidvis.se/api/public/v1/oauth/access-token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"tvc_...","client_secret":"tvs_..."}'

En enda modell — API och plattform är samma avtal

Avtal skapade via API:t ligger i samma tabell och delar hela infrastrukturen med avtal skapade i webb-UI:t. Konkret betyder det:

• Syns direkt i plattformen under fliken Via integration i /app/sign/dokument.
• Går att öppna, patcha, påminna och avbryta både via API och i UI:t.
• Ingår i samma auto-reminder-cron, arkiv och 18-månaders retention som native-avtal.
• Deltagarnas signeringslänk är alltid https://tidvis.se/sign/<token> — samma flöde som avtal skapade i plattformen.
• UI:t visar en Via {external_source}-badge (klickbar när external_url är satt) så administratören kan hoppa tillbaka till CRM-posten.
• Skickar du med sender i requesten autosigneras avsändaren vid send — samma beteende som när en användare skickar från plattformen.

Autentisering

OAuth2 client credentials. Du byter client_id+client_secret mot en JWT som är giltig i 1 timme. Skicka Authorization: Bearer <access_token> på alla efterföljande anrop.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-06-07T13:00:00.000Z"
}

Avtal

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Anställningsavtal Anna","expires_in_days":14,"bankid_required":true,"sender":{"name":"Anna Andersson","email":"anna@tidvis.se"}}'

Polla signeringsstatus

Tidvis Sign har ingen separat /status-resurs — GET /agreements/:id är pollingendpointen. Svaret innehåller avtalets status samt participants[].status och signed_at per part, så ni kan visa t.ex. "1 av 2 har signerat" i ert eget UI utan att vänta på webhook.

Rekommendation: använd webhooks (agreement.viewed, agreement.signed, agreement.completed) som primär kanal och fall tillbaka på polling med 30 s intervall när webhook inte är ett alternativ. Avtals-status kan vara draft, sent, partially_signed, completed, declined eller cancelled.

# Polla status och räkna signerade
curl -s https://tidvis.se/api/public/v1/agreements/$ID \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{
      status,
      signed: ([.participants[] | select(.status == "signed")] | length),
      total: (.participants | length),
      participants: [.participants[] | {name, email, status, signed_at}]
    }'

{
  "status": "partially_signed",
  "signed": 1,
  "total": 2,
  "participants": [
    { "name": "Anna Andersson", "email": "anna@example.com", "status": "signed",  "signed_at": "2026-06-17T09:14:22Z" },
    { "name": "Erik Eriksson",  "email": "erik@example.com",  "status": "viewed",  "signed_at": null }
  ]
}

CRM-länkning (external_id)

Länka varje avtal till motsvarande objekt i ert CRM (deal, opportunity, ärende) genom att skicka external_id, external_source och external_url när avtalet skapas. Fälten returneras på GET /agreements/:id och bifogas i alla webhook-payloads (agreement.sent, agreement.signed, ...) så ni kan koppla tillbaka eventet till rätt CRM-post utan att slå upp via metadata.

Detta är grunden för att integrera Tidvis Sign med vilket CRM som helst – HubSpot, Upsales, Pipedrive, Salesforce, Lime, SuperOffice – via Zapier, Make, n8n eller egen kod.

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Anställningsavtal Anna",
    "external_id": "deal_98231",
    "external_source": "hubspot",
    "external_url": "https://app.hubspot.com/contacts/123/deal/98231"
  }'

{
  "event": "agreement.signed",
  "delivery_id": "whd_...",
  "created_at": "2026-06-20T12:00:00Z",
  "agreement_id": "agr_...",
  "external_id": "deal_98231",
  "external_source": "hubspot",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "data": {
    "agreement_id": "agr_...",
    "external_id": "deal_98231",
    "external_source": "hubspot",
    "participant": { "id": "p_...", "email": "anna@example.com" }
  }
}

Versionering & ersättning

När ni skickar POST /agreements med samma external_source + external_id som ett tidigare avtal skapar vi automatiskt en ny version i kedjan. Den föregående versionen markeras som superseded_at och auto-cancelleras om den fortfarande var öppen. Signeringslänkar från den gamla versionen slutar fungera.

• Ärver send-läget: om föregående version var sent kopieras signatärer + avsändare, och den nya versionen skickas automatiskt så fort PDF:en laddats upp (eller när första participant lagts till om PDF redan finns).
• Listning: GET /agreements returnerar per default bara aktuella versioner. Använd ?group=all för att inkludera superseded.
• Historik: GET /agreements/:id/versions ger hela kedjan sorterad ASC. GET /agreements/:id inkluderar versions[] när avtalet ingår i en kedja.
• Fält: version (1..N), replaces_document_id, superseded_at.

# Skicka en uppdaterad version av samma HubSpot-deal
curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Anställningsavtal Anna (v2 – uppdaterad lön)",
    "external_id": "deal_98231",
    "external_source": "hubspot"
  }'

# Hämta hela kedjan
curl https://tidvis.se/api/public/v1/agreements/$NEW_ID/versions -H "Authorization: Bearer $TOKEN"

Idempotency

Skicka headern Idempotency-Key: <unikt-värde> på POST /agreements för att säkert kunna retry:a vid timeout/nätfel utan att skapa dubletter. Vi cachar svaret i 24 timmar; identiska anrop returnerar samma resultat med headern Idempotent-Replayed: true. Anrop med samma key men annan body returnerar 409 conflict.

Rekommendation: använd ert CRM:s deal-id + ett datum, eller en UUID per logiskt avtal.

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: deal_98231-2026-06-12" \
  -H "Content-Type: application/json" \
  -d '{"title":"Anställningsavtal Anna","external_id":"deal_98231","external_source":"hubspot"}'

Deltagare

{
  "name": "Anna Andersson",
  "email": "anna@example.com",
  "role": "signer",
  "job_title": "VD",
  "phone": "+46701234567",
  "personal_id_masked": "19800101-XXXX",
  "notifications_enabled": true
}

{ "reason": "Felaktiga villkor" }

{
  "name": "Erik Eriksson",
  "email": "erik@example.com",
  "job_title": "CFO",
  "phone": "+46707654321",
  "message": "Hänvisar till Erik som ansvarar för signering."
}

{ "enabled": false }

{
  "body": "Hej, kan ni granska bilaga 2?",
  "sender_label": "Tidvis Sign Agent",
  "participant_id": "8a3..."
}

PDF-dokument

# JSON / base64
curl -X PUT https://tidvis.se/api/public/v1/agreements/$ID/documents/main \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"avtal.pdf","content_base64":"JVBERi0..."}'

# Eller binärt
curl -X PUT https://tidvis.se/api/public/v1/agreements/$ID/documents/main \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @avtal.pdf

Livscykel

{"action": "send"}   // eller "cancel"

OTP via e-post (standardmetod)

Alla avtal signeras som standard med e-post + engångskod (OTP). Ingen extra konfiguration krävs – när bankid_required är false eller utelämnas använder varje deltagare denna metod. Räknas som enkel elektronisk signatur (SES) enligt eIDAS.

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Konsultavtal Anna",
    "expires_in_days": 14
  }'

{
  "event": "agreement.signed",
  "delivery_id": "whd_...",
  "created_at": "2026-06-11T08:42:11.000Z",
  "agreement_id": "agr_...",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "signature": {
    "method": "otp_email",
    "signer_name": "Anna Andersson",
    "email": "anna@example.com",
    "code_verified_at": "2026-06-11T08:41:53.000Z",
    "signed_at": "2026-06-11T08:42:11.000Z",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ..."
  }
}

BankID

Alternativ till standardmetoden OTP via e-post när ni behöver avancerad elektronisk signatur (AES). Sätt bankid_required: true när du skapar avtalet (eller via PATCH innan det skickas). När avtalet skickas signerar varje deltagare med BankID på mobilen eller datorn istället för engångskod.

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Anställningsavtal Anna",
    "bankid_required": true
  }'

{
  "id": "agr_...",
  "status": "draft",
  "bankid_required": true,
  "document": { "uploaded": false, "sha256": null },
  "participants": []
}

{
  "event": "agreement.signed",
  "delivery_id": "whd_...",
  "created_at": "2026-06-11T08:42:11.000Z",
  "agreement_id": "agr_...",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "signature": {
    "method": "bankid",
    "signer_name": "Anna Andersson",
    "signed_at": "2026-06-11T08:42:11.000Z"
  }
}

BankID-identifiering innan öppning

Separat tillval som tvingar mottagaren att legitimera sig med BankID innan dokumentet visas. Detta är en gate framför själva PDF:en och är oberoende av vald signaturmetod — du kan alltså kräva BankID-legitimering och sedan låta signering ske med OTP via e-post, klick-signatur eller penn-signatur. Kombineras gärna med bankid_required: true när du vill ha både identifiering före öppning och BankID-signering vid undertecknande.

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "NDA Anna",
    "bankid_identify_required": true
  }'

{
  "id": "agr_...",
  "status": "draft",
  "bankid_required": false,
  "bankid_identify_required": true,
  "participants": []
}

{
  "event": "agreement.identified",
  "delivery_id": "whd_...",
  "created_at": "2026-06-12T10:21:04.000Z",
  "agreement_id": "agr_...",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "identification": {
    "method": "bankid",
    "signer_name": "Anna Andersson",
    "identified_at": "2026-06-12T10:21:04.000Z"
  }
}

Avtalsgenerator

Bygg en AI-driven avtalsmall från 2–10 exempelavtal och generera sedan nya avtal med bara ett anrop. Genererade avtal kan laddas ner som DOCX ellerskickas direkt till signering via Sign — i så fall får du tillbaka ett sign_document_id.

curl -X POST https://tidvis.se/api/public/v1/agreement-templates \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Konsultavtal" \
  -F "files=@konsult1.pdf" \
  -F "files=@konsult2.pdf" \
  -F "files=@konsult3.docx"

{
  "values": {
    "kund_namn": "Acme AB",
    "belopp": 45000,
    "startdatum": "2026-08-01"
  },
  "send_for_signing": true,
  "signature_method": "bankid",
  "recipients": [
    { "name": "Anna Andersson", "email": "anna@acme.se" }
  ]
}

Fullständiga request/response-scheman finns i OpenAPI-referensen.

Underkonton (multi-tenant)

Hantera underkonton (dotterbolag, avdelningar, franchises) under huvudkontot. Kräver en aktiv årslicens (1 188 kr/år per underkonto, lookup-key sub_account_license_yearly) som aktiveras i Tidvis Sign → Underkonton. Alla endpoints kräver att din token tillhör huvudkontot, inte ett underkonto.

curl -X POST https://tidvis.se/api/public/v1/sub-accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stockholmskontoret",
    "org_number": "5560000000",
    "inherit_parent_admins": true
  }'

{ "inherit_parent_admins": false }

{ "email": "anna@example.com", "role": "admin" }

Webhooks

Tidvis levererar händelser till din URL via POST med JSON. Varje request är signerad med HMAC-SHA256 i headern X-Tidvis-Signature: sha256=<hex> baserat på din signing_secret och raw body. Eventnamnet finns både i X-Tidvis-Event och i JSON-bodyts event/event_type. Vi retryar misslyckade leveranser med exponentiell backoff i upp till 24h.

{
  "client_id": "<api_client uuid>",
  "url": "https://din-app.se/webhooks/tidvis",
  "events": ["agreement.sent","agreement.signed","agreement.completed"]
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const given = (header || "").replace(/^sha256=/, "");
  if (given.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(given));
}

Felkoder

Rate limits

Standardgräns: 60 requests/minut per klient och 600/timme för uppladdningar. Vid överskridning får du 429 rate_limited med Retry-After-header. Behöver du mer? Kontakta oss.