Create form template

POST

/v2/tenant/{tenantKey}/form

const url = 'https://sender.api.kivra.com/v2/tenant/example/form';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"Customer KYC","description":"Your bank has some questions","start_question":"number_deposits","questions":[{"label":"How many times per month do you deposit into your account?","id":"number_deposits","type":"number","next_question":"largest_sum"},{"label":"What is the largest amount deposited?","id":"largest_sum","type":"options","options":[{"id":"small","label":"10000 - 20000"},{"id":"medium","label":"20000 - 30000"},{"id":"large","label":"30000 - 40000","next_question":"source"}],"next_question":"citizenship"},{"label":"Select your country of citizenship","id":"citizenship","type":"multi_options","options":[{"id":"swe","label":"Sweden"},{"id":"no","label":"Norway"},{"id":"dk","label":"Denmark"}],"min":1,"max":2,"next_question":"comments"},{"label":"What is the source of the deposit?","id":"source","type":"free_text","next_question":"account"},{"label":"Select your salary account","id":"account","type":"verified_account","next_question":"comments"},{"label":"Do you have any further comments?","id":"comments","type":"free_text","help_text":"This can be any type of feedback that you have."}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://sender.api.kivra.com/v2/tenant/example/form \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "Customer KYC", "description": "Your bank has some questions", "start_question": "number_deposits", "questions": [ { "label": "How many times per month do you deposit into your account?", "id": "number_deposits", "type": "number", "next_question": "largest_sum" }, { "label": "What is the largest amount deposited?", "id": "largest_sum", "type": "options", "options": [ { "id": "small", "label": "10000 - 20000" }, { "id": "medium", "label": "20000 - 30000" }, { "id": "large", "label": "30000 - 40000", "next_question": "source" } ], "next_question": "citizenship" }, { "label": "Select your country of citizenship", "id": "citizenship", "type": "multi_options", "options": [ { "id": "swe", "label": "Sweden" }, { "id": "no", "label": "Norway" }, { "id": "dk", "label": "Denmark" } ], "min": 1, "max": 2, "next_question": "comments" }, { "label": "What is the source of the deposit?", "id": "source", "type": "free_text", "next_question": "account" }, { "label": "Select your salary account", "id": "account", "type": "verified_account", "next_question": "comments" }, { "label": "Do you have any further comments?", "id": "comments", "type": "free_text", "help_text": "This can be any type of feedback that you have." } ] }'

A form template is a list of questions you would like to ask users. When sending content you can attach a form you would like a user to complete.

Form templates are owned by the client that created them. What this means is that only the client can call the response endpoints. However if the client has the tenant scope it can call form template endpoints and even include a form when sending content.

Authorizations

oAuth2Client
post:kivra.v1.tenant.{tenantKey}

Parameters

Path Parameters

tenantKey

required

string format: hexadecimal

The tenant key for the tenant who is creating the form template.

Request Body

application/json

FormTemplate

object

title

required

The title of the form.

string

Example

Customer KYC

description

required

The purpose of the form.

string

Example

Your bank has some questions

start_question

required

The id of the first question in questions that will be asked to the user.

string

Example

number_deposits

questions

required

The questions that you want to ask the user.

Array<object>

FormQuestion

object

type

required

The input type required to answer the question.

free_text is a string.

number is an integer.

options is a list of FormOption objects.

multi_options is a list of FormMultiOption objects.

verified_account is a string containing the IBAN of the account.

string

Allowed values: free_text number options multi_options verified_account

label

required

Human readable description of what the question is.

string

required

A key used to identify the question.

string

help_text

Provides the user with more information about the question.

string

next_question

The question id of the next question that the user will be asked.

If question is of type options then this value is overridden if next_question is present on the option that the user selects.

If next_question is not present on the question or option then this will be the last question that the user is asked.

string

options

When type is options then use this to specify the answers that the user can select.

Array<object>

FormOption

object

required

A key used to identify the answer.

string

label

required

A human readable description of the answer.

string

next_question

The question id of the next question that the user will be asked.

This value overrides any potential next_question value on the question level.

If next_question is not present on the question or option then this will be the last question that the user is asked.

string

multi_options

When type is multi_options then use this to specify the answers that the user can select.

Array<object>

FormMultiOption

object

required

A key used to identify the answer.

string

label

required

A human readable description of the answer.

string

min

When type is number then use this to specify the minimum (inclusive) value to accept in the response. When type is multi_option then use this to specify the minimum number of options that the user can select.

integer

max

When type is number then use this to specify the maximum (inclusive) value to accept in the response. When type is multi_option then use this to specify the maximum number of options that the user can select.

integer

Example

[
  {
    "label": "How many times per month do you deposit into your account?",
    "id": "number_deposits",
    "type": "number",
    "next_question": "largest_sum"
  },
  {
    "label": "What is the largest amount deposited?",
    "id": "largest_sum",
    "type": "options",
    "options": [
      {
        "id": "small",
        "label": "10000 - 20000"
      },
      {
        "id": "medium",
        "label": "20000 - 30000"
      },
      {
        "id": "large",
        "label": "30000 - 40000",
        "next_question": "source"
      }
    ],
    "next_question": "citizenship"
  },
  {
    "label": "Select your country of citizenship",
    "id": "citizenship",
    "type": "multi_options",
    "options": [
      {
        "id": "swe",
        "label": "Sweden"
      },
      {
        "id": "no",
        "label": "Norway"
      },
      {
        "id": "dk",
        "label": "Denmark"
      }
    ],
    "min": 1,
    "max": 2,
    "next_question": "comments"
  },
  {
    "label": "What is the source of the deposit?",
    "id": "source",
    "type": "free_text",
    "next_question": "account"
  },
  {
    "label": "Select your salary account",
    "id": "account",
    "type": "verified_account",
    "next_question": "comments"
  },
  {
    "label": "Do you have any further comments?",
    "id": "comments",
    "type": "free_text",
    "help_text": "This can be any type of feedback that you have."
  }
]

key

required

The key of the newly created form template.

string format: uuid

Example

2877d684-a340-4e4c-867f-d93283787b01

created_at

required

The date the form template was created.

string

Example

2022-11-23T14:51:23.874434Z

version

required

The form template version

integer

Example

Responses

200

Form template created

application/json

FormTemplate

object

title

required

The title of the form.

string

description

required

The purpose of the form.

string

start_question

required

The id of the first question in questions that will be asked to the user.

string

questions

required

The questions that you want to ask the user.

Array<object>

FormQuestion

object

type

required

The input type required to answer the question.

free_text is a string.

number is an integer.

options is a list of FormOption objects.

multi_options is a list of FormMultiOption objects.

verified_account is a string containing the IBAN of the account.

string

Allowed values: free_text number options multi_options verified_account

label

required

Human readable description of what the question is.

string

required

A key used to identify the question.

string

help_text

Provides the user with more information about the question.

string

next_question

The question id of the next question that the user will be asked.

If question is of type options then this value is overridden if next_question is present on the option that the user selects.

If next_question is not present on the question or option then this will be the last question that the user is asked.

string

options

When type is options then use this to specify the answers that the user can select.

Array<object>

FormOption

object

required

A key used to identify the answer.

string

label

required

A human readable description of the answer.

string

next_question

The question id of the next question that the user will be asked.

This value overrides any potential next_question value on the question level.

If next_question is not present on the question or option then this will be the last question that the user is asked.

string

multi_options

When type is multi_options then use this to specify the answers that the user can select.

Array<object>

FormMultiOption

object

required

A key used to identify the answer.

string

label

required

A human readable description of the answer.

string

min

integer

max

integer

key

required

The key of the newly created form template.

string format: uuid

created_at

required

The date the form template was created.

string

version

required

The form template version

integer

Example

{
  "title": "Customer KYC",
  "description": "Your bank has some questions",
  "start_question": "number_deposits",
  "questions": [
    {
      "label": "How many times per month do you deposit into your account?",
      "id": "number_deposits",
      "type": "number",
      "next_question": "largest_sum"
    },
    {
      "label": "What is the largest amount deposited?",
      "id": "largest_sum",
      "type": "options",
      "options": [
        {
          "id": "small",
          "label": "10000 - 20000"
        },
        {
          "id": "medium",
          "label": "20000 - 30000"
        },
        {
          "id": "large",
          "label": "30000 - 40000",
          "next_question": "source"
        }
      ],
      "next_question": "citizenship"
    },
    {
      "label": "Select your country of citizenship",
      "id": "citizenship",
      "type": "multi_options",
      "options": [
        {
          "id": "swe",
          "label": "Sweden"
        },
        {
          "id": "no",
          "label": "Norway"
        },
        {
          "id": "dk",
          "label": "Denmark"
        }
      ],
      "min": 1,
      "max": 2,
      "next_question": "comments"
    },
    {
      "label": "What is the source of the deposit?",
      "id": "source",
      "type": "free_text",
      "next_question": "account"
    },
    {
      "label": "Select your salary account",
      "id": "account",
      "type": "verified_account",
      "next_question": "comments"
    },
    {
      "label": "Do you have any further comments?",
      "id": "comments",
      "type": "free_text",
      "help_text": "This can be any type of feedback that you have."
    }
  ],
  "key": "2877d684-a340-4e4c-867f-d93283787b01",
  "created_at": "2022-11-23T14:51:23.874434Z",
  "version": 1
}

400

Can’t process the request. Likely due to a client error.

application/json

FormErrorResponse

object

code

required

An error code identifying the reason of the unsuccessful request.

integer

short_message

required

Short human-readable description.

string

long_message

required

Longer human-readable description getting into details.

string

Examples

invalid_json

{
  "code": 40000,
  "short_message": "Invalid JSON",
  "long_message": "Could not parse posted body as JSON"
}

401

Not authorized to make the request.