Forms

List forms

GET/v1/forms

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

Returns forms in this organization, leaving archived ones out unless archived=true. Pass status to list only forms in that state. Results are cursor-paginated: pass meta.pagination.nextCursor back as cursor until it comes back null. The cursor is opaque — do not construct or parse one.

Query parameters

limitintegeroptional

min > 0 · max 100 · default 20

cursorstringoptional

1–2048 characters

qstringoptional

1–200 characters

statusstringoptional

Only forms in this status.

one of draft, published

archivedstringoptional

true lists archived forms only; unset or false leaves them out.

one of true, false · default "false"

Returns

Returns 200 OK with a list of FormListItem objects in data, and the next page's cursor in meta (see pagination). 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

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

allowedOriginsstring[]required

Site origins the embed may load from.

doubleOptInbooleanrequired

Whether submitters must confirm by email before they are subscribed.

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

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 \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/forms', {
  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",
    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", 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",
      "source": "source_example",
      "status": "draft",
      "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
      "fields": [
        {
          "key": "key_example",
          "type": "email",
          "label": "label_example",
          "required": true
        }
      ],
      "allowedOrigins": [
        "https://example.com"
      ],
      "doubleOptIn": true,
      "captcha": {
        "mode": "kirora"
      },
      "archivedAt": "2030-03-14T09:30:00Z",
      "createdAt": "2030-03-14T09:30:00Z",
      "updatedAt": "2030-03-14T09:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}

Example values are generated from the schema.