Forms

Retrieve a form

GET/v1/forms/{id}

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

Returns one form including its field and consent configuration.

Path parameters

idstringrequired: uuid

Returns

Returns 200 OK 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 https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
data = response.json()["data"]

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	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 · 200

{
  "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.