Docs
kirora.ioGet started
Forms overviewMenu
On this page

API reference

Forms

A form is a hosted sign-up, contact or waitlist form that creates or updates contacts and records the consent they give. Forms share a public link and can be embedded in your site; a submission returns 409 FORM_CLOSED once the form is closed by hand, by date or by its limit.

Endpoints

EndpointRequest
List formsGET /v1/forms
Create a formPOST /v1/forms
Retrieve a formGET /v1/forms/{id}
Update a formPATCH /v1/forms/{id}
Delete a formDELETE /v1/forms/{id}
List a form's submissionsGET /v1/forms/{id}/submissions
Submit a formPOST /v1/forms/{id}/submissions
Publish a formPOST /v1/forms/{id}/publish
Unpublish a formPOST /v1/forms/{id}/unpublish
Archive a formPOST /v1/forms/{id}/archive
Unarchive a formPOST /v1/forms/{id}/unarchive
Retrieve a form's metricsGET /v1/forms/{id}/metrics

The Form object

Form example
{
  "id": "0192f3e1-2b3c-7d4e-9f50-6b7c8d9e0f1a",
  "publicId": "frm7k2m9q4x1c8v3b6n5t0za",
  "slug": "acme-newsletter",
  "name": "Newsletter signup",
  "heading": "Join the Acme Shop newsletter",
  "intro": "New arrivals and offers, once a week.",
  "location": "website-footer",
  "url": "https://forms.kirora.io/f/acme-newsletter",
  "status": "published",
  "listId": "0192f3a2-1b3c-7e5d-8a21-4f6a7b8c9d0e",
  "fields": [
    {
      "key": "email",
      "type": "email",
      "label": "Email address",
      "placeholder": "[email protected]",
      "required": true
    },
    {
      "key": "firstName",
      "type": "text",
      "label": "First name",
      "required": false
    }
  ],
  "hiddenFields": {
    "signup_campaign": {
      "source": "link",
      "param": "utm_campaign"
    }
  },
  "share": {
    "title": "Get the Acme Shop newsletter"
  },
  "acceptingSubmissions": true,
  "closesAt": null,
  "maxSubmissions": null,
  "closedMessage": null,
  "submissionCount": 1240,
  "allowedOrigins": [
    "https://acme-shop.com"
  ],
  "refusedOrigins": [],
  "doubleOptIn": true,
  "notifyUserIds": [],
  "theme": {
    "accentColor": "#b4461f",
    "fontFamily": "sans",
    "buttonLabel": "Subscribe"
  },
  "display": {
    "mode": "inline"
  },
  "captcha": null,
  "consent": {
    "required": true,
    "label": "I agree to receive emails from Acme Shop and can unsubscribe at any time."
  },
  "success": {
    "type": "message",
    "message": "Thanks. Check your inbox to confirm."
  },
  "archivedAt": null,
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-02T14:05:00.000Z"
}
idstringrequired

uuid

publicIdstringrequired

The id the public embed and hosted page use.

pattern ^[a-z0-9]{24}$

slugstring | nullrequired

The readable part of the form's link; null uses publicId alone.

namestringrequired
headingstring | nullrequired

What visitors see above the fields; null shows none.

introstring | nullrequired

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

locationstringrequired

Where the form sits on your site, a label you choose (website-footer, checkout-page). Recorded on each submission, as properties.location on its contact.form_submitted event and on the form.submitted webhook, which is how a segment or journey uses it.

urlstringrequired

The hosted form's link, by its slug when it has one, else its publicId. It serves once the form is published.

uri

statusstringrequired

Whether the form accepts submissions: published once POST /v1/forms/{id}/publish puts it live, draft until then or after unpublishing.

one of draft, published

listIdstring | nullrequired

The list every submitter is added to.

uuid

fieldsobject[]required

The fields, top to bottom.

6 child attributes
keystringrequired

Where the response 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
hiddenFieldsmap<string, object>required

Values saved on each submitter with no field shown: fixed, or taken from the link.

at most 50 keys · keys: pattern ^[\p{L}\p{N}\p{M}_.-]{1,64}$

One of 2 shapes
With value
2 child attributes
source"fixed"required
valuestringrequired

Saved as it is on every submitter.

up to 1,000 characters

With param
2 child attributes
source"link"required
paramstringrequired

The link parameter it takes its value from, such as utm_campaign; left unset when the link has none.

pattern ^[A-Za-z0-9_.-]{1,64}$

shareobject | nullrequired

How the form's link previews, as set; null falls back entirely.

3 child attributes
titlestringoptional
descriptionstringoptional
imageUrlstringoptional

uri

acceptingSubmissionsbooleanrequired

false: closed by hand, whatever its closing time and limit.

closesAtstring | nullrequired

When the form closes, if ever.

date-time

maxSubmissionsinteger | nullrequired

The submissions it closes at, if any.

closedMessagestring | nullrequired

What a closed form shows; null shows the default wording.

submissionCountintegerrequired

Submissions taken so far (honeypot catches aside), counted for the limit.

min 0

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.

notifyUserIdsstring[]required

Users of this workspace told about each submission.

themeFormThemerequired
12 child attributes
modestringoptional

Light or dark defaults for every colour left unset; light when unset.

one of light, dark

accentColorstringoptional

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

pattern ^#[0-9a-fA-F]{6}$

backgroundColorstring | nulloptional

The page and form background, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

textColorstring | nulloptional

Headings, labels and text, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

buttonColorstring | nulloptional

The button's fill; unset, the accent colour, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

buttonTextColorstring | nulloptional

The button's text, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

fontFamilystringoptional

The font's id: a generic style (system, sans, serif, mono) or a named font the forms host serves itself. A font emails also offer has the same id there (EmailFont).

one of system, sans, serif, mono, inter, roboto, open-sans, lato, montserrat, poppins, source-sans-3, nunito, raleway, work-sans, dm-sans, manrope, ibm-plex-sans, noto-sans, rubik, karla, merriweather, lora, playfair-display, libre-baskerville, source-serif-4, eb-garamond, ibm-plex-mono, jetbrains-mono

borderRadiusintegeroptional

Corner rounding of inputs and the button, in px, where inputs.borderRadius or button.borderRadius does not set its own.

min 0 · max 24

buttonLabelstringoptional

Text on the submit button.

1–40 characters

inputsobjectoptional

How fields look; each part optional.

9 child attributes
widthstringoptional

fit (unset): a short answer's field is 320px and a long one fills the form; full: every field fills the form; fixed: every field widthPx wide at most.

one of fit, full, fixed

widthPxintegeroptional

With width fixed: the width, in px.

min 200 · max 720

heightintegeroptional

In px.

min 28 · max 64

backgroundColorstring | nulloptional

The field background, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

placeholderColorstring | nulloptional

Placeholder text, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

borderColorstring | nulloptional

The field border, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

borderWidthintegeroptional

In px.

min 0 · max 4

borderRadiusintegeroptional

In px; unset, the top-level borderRadius.

min 0 · max 32

spacingintegeroptional

The gap below each field, in px.

min 0 · max 48

buttonobjectoptional

How the submit button looks; each part optional.

5 child attributes
widthstringoptional

Fit its label, or the form width.

one of auto, full

heightintegeroptional

In px.

min 28 · max 64

alignstringoptional

one of start, center, end

fontSizeintegeroptional

In px.

min 12 · max 24

borderRadiusintegeroptional

In px; unset, the top-level borderRadius.

min 0 · max 32

layoutobjectoptional
2 child attributes
pageWidthintegeroptional

The form's widest, in px.

min 360 · max 960

baseFontSizeintegeroptional

Body text size, in px.

min 12 · max 20

displayobjectrequired
One of 2 shapes
Inline
1 child attribute
mode"inline"required
Popup
7 child attributes
mode"popup"required
delayDurationOrZerooptional

How long after the page loads it opens, at most 10 minutes. Defaults to 5 seconds.

2 child attributes
valueintegerrequired

min 0

unitstringrequired

one of seconds, minutes, hours, days

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

hideForDurationOrZerooptional

How long it stays away once closed, at most 365 days. Defaults to 7 days.

2 child attributes
valueintegerrequired

min 0

unitstringrequired

one of seconds, minutes, hours, days

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