Forms API

These are the Forms endpoints of the Keila API. For Keila Cloud, the base URL is https://app.keila.io.

All endpoints, unless stated differently, require Bearer authentication.

get /api/v1/forms

Index forms

Retrieve all forms from your project.

Responses

200 Form response

dataobject[]
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- idstring
  Form ID
  Example: "frm_12345"
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"
metaobject
- pageinteger
  Current page of items (zero-indexed)
  Example: 0
- page_countinteger
  Number of total pages
  Example: 5
- page_sizeinteger
  Number of items per page
  Example: 50

post /api/v1/forms

Create Form

Request body

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- namestring required
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

Responses

200 Form response

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- idstring
  Form ID
  Example: "frm_12345"
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

get /api/v1/forms/{id}

Show Form

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Form ID

Responses

200 Form response

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- idstring
  Form ID
  Example: "frm_12345"
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

put /api/v1/forms/{id}

Update Form

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Form ID

Request body

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

Responses

200 Form response

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- idstring
  Form ID
  Example: "frm_12345"
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

patch /api/v1/forms/{id}

Update Form

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Form ID

Request body

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

Responses

200 Form response

dataobject
- fieldsobject[]
  - allowed_valuesobject[]
    labelstring
    valuestring
  - castboolean
  - descriptionstring
  - field"email" | "first_name" | "last_name" | "data"
  - keystring
  - labelstring
  - placeholderstring
  - requiredboolean
  - typestring
- idstring
  Form ID
  Example: "frm_12345"
- namestring
  Example: "My Form"
- sender_idstring
  Example: "ms_12345"
- settingsobject
  - body_bg_colorstring
  - captcha_requiredboolean
  - csrf_disabledboolean
  - double_opt_in_markdown_bodystring
  - double_opt_in_messagestring
  - double_opt_in_requiredboolean
  - double_opt_in_subjectstring
  - double_opt_in_urlstring
    URL to redirect after a form was submitted and double opt-in is required.
  - failure_textstring
  - failure_urlstring
  - fine_printstring
  - form_bg_colorstring
  - input_bg_colorstring
  - input_border_colorstring
  - input_text_colorstring
  - intro_textstring
  - submit_bg_colorstring
  - submit_labelstring
  - submit_text_colorstring
  - success_textstring
  - success_urlstring
    URL to redirect after contact was successfully created - either after double opt-in or after form submission without double opt-in. Supports Liquid with the `contact` assign present.
    Example: "https://example.com/thank-you/{{ contact.id }}"
  - text_colorstring
- template_idstring
  Example: "tpl_12345"

delete /api/v1/forms/{id}

Delete Form

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Form ID

Responses

204 Form was deleted successfully or didn’t exist.

post /api/v1/forms/{id}/actions/submit

Submit Form

Submits a form. This is particularly useful if you want to start the Double-Opt-In process from the API or want to take advantage of the validation of custom fields provided by forms. **Note:** Even if `captcha_required` is set to `true`, submitting a Form from the API never requires a CAPTCHA.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Campaign ID

Request body

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring required
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"

202 Double-Opt-In response

dataobject
- double_opt_in_requiredtrue