Forms

High-level description

Forms let a recipient answer structured questions in Kivra and sign the response with BankID. The complete flow is: create a reusable template, send content that references the template, then retrieve and archive the response.

Sub-types

Use letter.form for form content. The template’s question types are free_text, number, options, multi_options, and verified_account; these are not separate content sub-types.

Common payload

Use type: "letter.form" and include the template key as form.id. form.days_to_expiry is required and must be between 1 and 90 days.

{
  "ssn": "YYYYMMDDNNNN",
  "subject": "Confirm your contact preferences",
  "type": "letter.form",
  "parts": [
    {
      "name": "contact-preferences.pdf",
      "content_type": "application/pdf",
      "data": "BASE64_ENCODED_PDF"
    }
  ],
  "form": {
    "id": "FORM_TEMPLATE_KEY",
    "days_to_expiry": 30,
    "sender_reference": {
      "customer_reference": "customer-123"
    }
  }
}

Other information

1. Create a form template

Option	Purpose
title and description	Explain the form to the recipient
questions	Defines the ordered questions and answer types
type	Supports free_text, number, options, multi_options, and verified_account
id and next_question	Identify questions and control the question flow
min and max	Limit number and multi-option responses

{
  "title": "Contact preferences",
  "description": "Tell us how you prefer to be contacted.",
  "start_question": "contact_method",
  "questions": [
    {
      "id": "contact_method",
      "type": "options",
      "label": "Preferred contact method",
      "options": [
        {
          "id": "email",
          "label": "Email"
        },
        {
          "id": "phone",
          "label": "Phone"
        }
      ]
    }
  ]
}

Send this body to POST /v2/tenant/{tenantKey}/form to create the template. Save the key returned in the response: the client that creates the template owns the template and its responses. The tenantKey controls which tenant the template is associated with, but does not transfer response access to another client. The creating client may be acting on behalf of that tenant as a partner.

2. Send content with the form

Send the common payload to the Send content endpoint, using the template key returned in the previous step as form.id.

3. Retrieve and archive responses

The recipient opens the document and answers the configured questions in Kivra. Retrieve response keys, retrieve each response, archive the data your service needs, and delete it from Kivra when appropriate. Form responses can contain sensitive data.

See the create form template endpoint for template versioning and response operations.