Tidvis Sign Public API

Copies of signed agreements (completed_copy_emails)

Pass completed_copy_emails (up to 5 addresses) when creating an agreement via POST /agreements or quick-send. Each address receives the confirmation email with the signed PDF attached once the agreement completes. If omitted (null), the account-level setting under Settings is inherited. The field is returned on GET /agreements/:id — see the field tables above.

How it works

• The recipient receives a personal link to their email (the address in participants[].email).
• A 6-digit one-time code is sent on document open, valid for 15 minutes, max 5 attempts.
• Identity is verified before the signature is recorded; IP, user agent, timestamp and code verification are stored in the audit trail.
• Included on every plan – no add-on or per-signature fee.

Create an OTP agreement (default)

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

Webhook payload for OTP signatures

{
  "event": "agreement.signed",
  "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 ..."
  }
}

Lock BankID to a specific personal number

Set signer_personal_number on a recipient to require that exactly that person identifies and/or signs with BankID. Anyone else is rejected inside the BankID app. Requires the agreement to have bankid_required: true and/or bankid_identify_required: true. The field is write-only — it is never returned in responses; use personal_id_masked (e.g. 19800101-XXXX) for display.

{
  "title": "Employment contract Anna",
  "bankid_required": true,
  "participants": [
    {
      "name": "Anna Andersson",
      "email": "anna@example.com",
      "signer_personal_number": "198001011234"
    }
  ]
}

Accepted format: 10 or 12 digits with an optional dash (e.g. 198001011234, 800101-1234). Luhn-validated. Sending a personal number without BankID enabled on the agreement, or a number that fails Luhn, returns 400 invalid_request.

Requirements

• The account must have the Sign Pro plan and the BankID add-on enabled.
• Pricing: 100 BankID signatures included per month, then 5 SEK/signature.
• Without the add-on, POST /agreements/:id/lifecycle with action: "send" returns 402 bankid_disabled.

Create a BankID agreement

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

Response (abbreviated):

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

Webhook payload when BankID is used

For agreements with bankid_required: true, the agreement.signed event is enriched with a signature block. For privacy reasons, neither personal identity numbers, certificates nor OCSP responses are exposed via the API or webhooks.

{
  "event": "agreement.signed",
  "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"
  }
}

The signature.method field is always one of "otp_email" or "bankid". Agreements with mixed participants log the method per signer.

Enable on creation

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
  }'

Response (abbreviated):

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

Recipient behavior

• When the recipient opens the link, a BankID gate is shown instead of the PDF.
• They must start BankID on mobile or via QR code and confirm the identification.
• Only then is the PDF rendered and the chosen signature method enabled.
• The "viewed" event is logged after identification, not on the first click.

Requirements and pricing

• Account must have Sign Pro with the BankID add-on — same prerequisites as bankid_required.
• Identifications do not count against the 100 BankID signatures/month quota. Only actual BankID signatures (bankid_required: true) are billed at 5 SEK each beyond the included amount.
• Without the add-on, POST /agreements/:id/lifecycle with action: "send" returns 402 bankid_disabled.

Webhook payload

A dedicated agreement.identified event is delivered when a recipient identifies. Personal identity numbers, certificates and OCSP responses are never exposed via the API.

{
  "event": "agreement.identified",
  "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"
  }
}

Requirements & pricing

• The agreement module must be active (99 SEK/user/month). Otherwise the endpoint returns 402 plan_required.
• MCP/agent calls add 3 SEK per generation on top of the module fee.
• Source files max 20 MB each, 2–10 files per template (PDF or DOCX).

Scopes

• templates:read — list and fetch templates
• templates:manage — create and delete templates
• generations:create — generate new agreements from a template
• generations:read — list, fetch and download generated agreements
• If signature_method: "bankid" is used in generate, agreements:send is also required.