Forms

Create a form

POST/v1/forms

Requires an API key with the forms:write scope. About keys and scopes

Creates a hosted signup form, in draft. Submissions create or update contacts and record consent, so the consent configuration here is what makes later sends lawful.

Request body

namestringrequired

1–255 characters

headingstring | nulloptional

What visitors see above the fields; null clears it.

1–200 characters

introstring | nulloptional

A line or two under the heading; null clears it.

1–1000 characters

sourcestringoptional

Recorded on each contact the form creates. Defaults to form.

1–80 characters · default "form"

groupIdstringrequired

The group every submitter is added to.

uuid

fieldsFormFieldInput[]required

The fields, top to bottom. One must be a required email field.

at least 1 item · at most 20 items

6 child attributes

keystringrequired

Where the answer goes: email, firstName, lastName, phone, attributes.<name>, dates.<name> (a named date that date-triggered journeys read), groups or topics. Each type accepts only some keys.

up to 80 characters

typestringrequired

The input the visitor sees.

one of email, text, textarea, select, checkbox, date, phone

labelstringrequired

The text shown beside the field.

1–120 characters

placeholderstringoptional

Hint text shown inside the empty field.

up to 160 characters

requiredbooleanoptional

Whether the visitor must fill it in.

default false

optionsobject[]optional

Required for select and checkbox, refused for other types. For the groups key each value is a group id, for topics a topic id; the label is what the visitor sees beside its box.

at least 1 item · at most 50 items

2 child attributes

valuestringrequired

What is stored when chosen.

1–100 characters

labelstringrequired

What the visitor sees.

1–120 characters

hiddenFieldsobjectoptional

Fixed values saved on each submitter with no field shown, such as a campaign tag. Each becomes a contact attribute.

default {}

allowedOriginsstring[]optional

Site origins (scheme and host, no path) the embed may load from, such as https://example.com.

at most 20 items · default []

doubleOptInbooleanoptional

Ask submitters to confirm by email before they are subscribed.

themeFormThemeInputoptional

4 child attributes

accentColorstringoptional

Colour of the button and focus outlines, as #RRGGBB.

fontFamilystringoptional

The font style of the form.

one of system, sans, serif, mono

borderRadiusintegeroptional

Corner rounding of inputs and the button, in px.

min 0 · max 24

buttonLabelstringoptional

Text on the submit button.

1–40 characters

displayobjectoptional

One of 2 shapes

Inline

1 child attribute

mode"inline"required

Popup

7 child attributes

mode"popup"required

delaySecondsintegeroptional

Seconds after the page loads before it opens. Defaults to 5.

min 0 · max 600

scrollPercentintegeroptional

Opens once the visitor has scrolled this far down the page.

min 1 · max 100

exitIntentbooleanoptional

Opens when the visitor moves to leave the page (desktop only).

urlMatchobjectoptional

Limits which pages the popup opens on.

2 child attributes

containsstring[]optional

Show only on pages whose URL contains one of these.

at most 20 items

excludesstring[]optional

Never show on pages whose URL contains one of these.

at most 20 items

hideForDaysintegeroptional

Days it stays away once closed. Defaults to 7.

min 0 · max 365

hideAfterSubmitbooleanoptional

Whether it stays away after a signup. Defaults to true.

captchaobject | nulloptional

CAPTCHA for submissions: { mode: "kirora" } (the default on a new form), { mode: "own", siteKey, secretKey } for your Cloudflare Turnstile widget, or null for none.

One of 2 shapes

KiroraCaptchaInput

1 child attribute

mode"kirora"required

OwnCaptchaInput

3 child attributes

mode"own"required

siteKeystringrequired

The widget's public site key.

1–200 characters

secretKeystringoptional

The widget's secret key. Write-only: omit it to keep the stored one.

1–200 characters

consentobjectrequired

The consent box every submitter must tick.

2 child attributes

requiredtruerequired

Always true: the visitor must tick the consent box.

labelstringrequired

The consent text shown beside the box.

1–500 characters

successobjectoptional

What happens after a submission. Defaults to a thank-you message.

default {"type":"message","message":"Thanks for signing up."}

One of 2 shapes

Show a message

2 child attributes

type"message"required

messagestringrequired

Shown in place of the form.

1–1000 characters

Redirect

2 child attributes

type"redirect"required

redirectUrlstringrequired

An http(s) address the visitor is sent to.

uri · up to 2048 characters

Returns

Returns 201 Created with a Form in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

publicIdstringrequired

The id the public embed and hosted page use.

namestringrequired

headingstring | nullrequired

What visitors see above the fields; null shows none.

introstring | nullrequired

A line or two under the heading; null shows none.

sourcestringrequired

Recorded on each contact the form creates.

statusstringrequired

Whether the form accepts submissions.

one of draft, published

groupIdstring | nullrequired

The group every submitter is added to.

uuid

fieldsobject[]required

The fields, top to bottom.

6 child attributes

keystringrequired

Where the answer goes, such as email or attributes.plan.

typestringrequired

The input the visitor sees.

one of email, text, textarea, select, checkbox, date, phone

labelstringrequired

The text shown beside the field.

placeholderstringoptional

Hint text shown inside the empty field.

requiredbooleanrequired

Whether the visitor must fill it in.

optionsobject[]optional

The choices of a select or checkbox field.

2 child attributes

valuestringrequired
labelstringrequired

hiddenFieldsobjectrequired

Fixed values saved on each submitter with no field shown.

allowedOriginsstring[]required

Site origins the embed may load from.

refusedOriginsobject[]required

Origins an embed was refused from lately, newest first, not counting any since added to allowedOrigins; add one there to approve it.

2 child attributes

originstringrequired

The origin that was refused.

lastRefusedAtstringrequired

When it was last refused.

date-time

doubleOptInbooleanrequired

Whether submitters must confirm by email before they are subscribed.

themeFormThemerequired

4 child attributes

accentColorstringoptional

Colour of the button and focus outlines, as #RRGGBB.

fontFamilystringoptional

The font style of the form.

one of system, sans, serif, mono

borderRadiusintegeroptional

Corner rounding of inputs and the button, in px.

min 0 · max 24

buttonLabelstringoptional

Text on the submit button.

1–40 characters

displayobjectrequired

One of 2 shapes

Inline

1 child attribute

mode"inline"required

Popup

7 child attributes

mode"popup"required

delaySecondsintegeroptional

Seconds after the page loads before it opens. Defaults to 5.

min 0 · max 600

scrollPercentintegeroptional

Opens once the visitor has scrolled this far down the page.

min 1 · max 100

exitIntentbooleanoptional

Opens when the visitor moves to leave the page (desktop only).

urlMatchobjectoptional

Limits which pages the popup opens on.

2 child attributes

containsstring[]optional

Show only on pages whose URL contains one of these.

at most 20 items

excludesstring[]optional

Never show on pages whose URL contains one of these.

at most 20 items

hideForDaysintegeroptional

Days it stays away once closed. Defaults to 7.

min 0 · max 365

hideAfterSubmitbooleanoptional

Whether it stays away after a signup. Defaults to true.

captchaobject | nullrequired

Where the CAPTCHA comes from; null while it is off. Secrets never show.

One of 2 shapes

KiroraCaptchaSetting

1 child attribute

mode"kirora"required

OwnCaptchaSetting

2 child attributes

mode"own"required
siteKeystringrequired

consentobjectrequired

2 child attributes

requiredtruerequired: Always true: the visitor must tick the consent box.
labelstringrequired: The consent text shown beside the box.

successobjectrequired

One of 2 shapes

Show a message

2 child attributes

type"message"required
messagestringrequired: Shown in place of the form.

Redirect

2 child attributes

type"redirect"required

redirectUrlstringrequired

An http(s) address the visitor is sent to.

uri

archivedAtstring | nullrequired

When it was archived; an archived form is left out of the list and stops serving.

date-time

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

curl -X POST https://api.kirora.io/v1/forms \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend specials",
    "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
    "fields": [
      {
        "key": "key_example",
        "type": "email",
        "label": "label_example"
      }
    ],
    "consent": {
      "required": true,
      "label": "label_example"
    }
  }'

const response = await fetch('https://api.kirora.io/v1/forms', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Weekend specials",
    "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
    "fields": [
      {
        "key": "key_example",
        "type": "email",
        "label": "label_example"
      }
    ],
    "consent": {
      "required": true,
      "label": "label_example"
    }
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/forms",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "name": "Weekend specials",
        "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
        "fields": [
            {
                "key": "key_example",
                "type": "email",
                "label": "label_example",
            },
        ],
        "consent": {
            "required": True,
            "label": "label_example",
        },
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "name": "Weekend specials",
	  "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
	  "fields": [
	    {
	      "key": "key_example",
	      "type": "email",
	      "label": "label_example"
	    }
	  ],
	  "consent": {
	    "required": true,
	    "label": "label_example"
	  }
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/forms", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 201

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "publicId": "publicId_example",
    "name": "Weekend specials",
    "heading": "heading_example",
    "intro": "intro_example",
    "source": "source_example",
    "status": "draft",
    "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
    "fields": [
      {
        "key": "key_example",
        "type": "email",
        "label": "label_example",
        "required": true
      }
    ],
    "hiddenFields": {},
    "allowedOrigins": [
      "https://example.com"
    ],
    "refusedOrigins": [
      {
        "origin": "origin_example",
        "lastRefusedAt": "2030-03-14T09:30:00Z"
      }
    ],
    "doubleOptIn": true,
    "theme": {},
    "display": {
      "mode": "inline"
    },
    "captcha": {
      "mode": "kirora"
    },
    "consent": {
      "required": true,
      "label": "label_example"
    },
    "success": {
      "type": "message",
      "message": "message_example"
    },
    "archivedAt": "2030-03-14T09:30:00Z",
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}

Example values are generated from the schema.