OpenAPI Spec
Machine-readable spec for the Forms API: stable/categories/forms.json
Before you begin
Check out our general API overview before getting started with specific endpoints.
Forms allow you to collect information from your site's visitors. You can create new profiles, subscribe them to marketing, assign coupons to shoppers, and more.
Data model
A form has the following:
-
id
The form ID. -
attributes-
statusThe current status of the form, e.g.,
draftorlive. -
ab_testWhether or not the form has an A/B test.
-
created_atThe timestamp of when the form was created.
-
updated_atThe timestamp of when the form was last updated.
-
definitionA definition of the form.
-
versionsDifferent versions of the same form ID. You may have more than one
livevariation, which means that you have an ongoing A/B test. You may also have a combination ofliveanddraftversions to represent the version that you are actively modifying in the sign-up form builder.-
nameThe variation's name.
-
typeThe type of form, i.e.,
flyout,popup,banner,full-page, orembed. -
triggersA set of conditions that would cause the form to be shown.
-
teaserA small widget that shoppers can click to open or re-open a form after it's been closed.
-
locationThe location where the form will show, e.g.,
bottom_left(available in select forms). -
statusThe current status of the variation, e.g.,
draftorlive. -
ab_testWhether or not the variation is part of an A/B test.
-
stepsAll of the steps of a given form variation (in order of how they appear).
-
columnsAll of the columns in a given step (in order of how they appear). Forms may only have multiple columns if they also have a side image.
-
rowsAll of the rows in a given column (in order of how they appear).
-
blocksAll of the blocks in a given row (in order of how they appear).
-
actionThe action associated with a given block.
-
-
-
-
-
-
-
Any one of these form entities will also have a variety of properties and styling options that allow you to customize in all ways that are supported by the sign-up form editor.
Here's an example of a very simple sign-up form:
{
"data": {
"type": "form",
"attributes": {
"definition": {
"versions": [
{
"steps": [
{
"columns": [
{
"rows": [
{
"blocks": [
{
"type": "html_text",
"properties": {
"content": "<div>Sign up for our newsletter</div>"
}
}
]
},
{
"blocks": [
{
"type": "email",
"properties": {
"label": "Email",
"placeholder": "Enter your email address",
"required": true
}
}
]
},
{
"blocks": [
{
"type": "button",
"properties": {
"label": "Email"
},
"action": {
"id": "01JSJ2D930BGX4SHPPNPEFKBY8",
"submit": true,
"type": "next_step",
"properties": {
"list_id": "<LIST_ID>"
}
}
}
]
}
]
}
],
"name": "email sign-up"
},
{
"columns": [
{
"rows": [
{
"blocks": [
{
"type": "html_text",
"properties": {
"content": "<div>Thank you for subscribing!</div>"
}
}
]
}
]
}
],
"name": "success step"
}
],
"name": "test",
"type": "popup",
"status": "draft"
}
]
},
"status": "draft",
"ab_test": false,
"name": "My first API form"
}
}
}
Get a form's definition
GET /api/form/{id}
We've added the ability to retrieve a form's definition.
The example response below returns the definition of the form shown above, augmented with some defaults:
{
"data": {
"type": "form",
"id": "Ser5Vq",
"attributes": {
"status": "draft",
"ab_test": false,
"name": "My first API form",
"definition": {
"versions": [
{
"id": 19258033,
"steps": [
{
"id": "01JTP6F3EERYR2T30C4ZDCS6JA",
"columns": [
{
"id": "01JTP6F3EQ9TQ6TEWQSV33JDQ7",
"rows": [
{
"id": "01JTP6F3EZRM5M0HM42NPC6QA5",
"blocks": [
{
"id": "01JTP6F3F52N3WXF6MNNSH1MQ4",
"type": "html_text",
"styles": {
"padding": {
"left": 6,
"right": 6,
"top": 10,
"bottom": 10
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": "<div>Sign up for our newsletter</div>"
}
}
]
},
{
"id": "01JTP6F3FFFGW8Z2VYHEHVVNGM",
"blocks": [
{
"id": "01JTP6F3FNN3VVA4A2V6HVE3Q7",
"type": "email",
"styles": {
"padding": {
"left": 6,
"right": 6,
"top": 10,
"bottom": 10
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "Email",
"show_label": false,
"placeholder": "Enter your email address",
"required": true,
"error_messages": null,
"property_name": "$email"
}
}
]
}
],
"styles": null
}
],
"name": "email sign-up",
"steps": null
},
{
"id": "01JTP6F3D8NC46E9Q9GZG3JX7F",
"columns": [
{
"id": "01JTP6F3DHTYSRWKMX0R8Z9743",
"rows": [
{
"id": "01JTP6F3DS83D2D117G5F4G6D5",
"blocks": [
{
"id": "01JTP6F3DZD3N849FQ15DYRHA7",
"type": "html_text",
"styles": {
"padding": {
"left": 6,
"right": 6,
"top": 10,
"bottom": 10
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": "<div>Thank you for subscribing!</div>"
}
}
]
}
],
"styles": null
}
],
"name": "success step",
"steps": null
}
],
"triggers": [
{
"id": "01JTP6F3H4AKS4V33E89R2EX74",
"properties": {},
"type": "unidentified_profiles"
},
{
"id": "01JTP6F3HH82JS5410DYQTB33H",
"type": "after_close_or_submit_timeout",
"properties": {
"timeout_days": 5
}
}
],
"teaser": null,
"name": "test",
"styles": {
"wrap_content": false,
"border_styles": {
"radius": 2,
"color": "#000000",
"style": null,
"thickness": 0
},
"close_button": {
"background_color": "rgba(180, 187, 195, 0.65)",
"outline_color": "#FFFFFF",
"color": "#FFFFFF",
"stroke": 2,
"size": 20,
"margin": {
"left": 8,
"right": 8,
"top": 8,
"bottom": 8
}
},
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"padding": {
"left": 20,
"right": 20,
"top": 20,
"bottom": 20
},
"minimum_height": 250,
"width": "medium",
"custom_width": null,
"background_image": null,
"background_color": "#FFFFFF",
"input_styles": {
"text_styles": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 16,
"font_weight": 400,
"text_color": "#000000",
"character_spacing": 0
},
"label_color": "#303B43",
"text_color": "#000000",
"placeholder_color": "#949596",
"background_color": "#FFFFFF",
"border_color": "#949596",
"border_focus_color": "#000000",
"focus_outline_color": "#1C65AD",
"corner_radius": 2,
"field_height": 38
},
"drop_shadow": {
"enabled": false,
"blur": 30,
"color": "rgba(0,0,0,0.15)"
},
"overlay_color": "rgba(20,20,20,0.6)",
"rich_text_styles": {
"body": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 16,
"font_weight": 400,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"link": {
"color": "#0066cc",
"decoration": "underline"
},
"h1": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 48,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h2": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 36,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h3": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 28,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h4": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 20,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h5": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 13,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h6": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 11,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
}
},
"mobile_overlay": {
"color": "rgba(20, 20, 20, 0.5)",
"enabled": false
},
"banner_styles": null
},
"properties": {
"side_image_settings": null,
"click_outside_to_close": ["mobile", "desktop"],
"rule_based_trigger_evaluation": "any",
"record_utm_params_on_submit": false,
"show_close_button": true
},
"type": "popup",
"location": null,
"status": "draft",
"ab_test": false
}
]
},
"created_at": "2025-05-07T20:19:50+00:00",
"updated_at": "2025-05-07T20:19:50+00:00"
},
"links": {
"self": "https://a.klaviyo.com/api/forms/Ser5Vq/"
}
},
"links": {
"self": "https://a.klaviyo.com/api/forms/Ser5Vq"
}
}
Create a form
Create a new form using an encoded form definition. POST /api/forms/
Below we have outlined the recommended workflow for creating a new form via Forms API:
- Create a form with your desired settings in the Klaviyo UI and copy its form ID from the URL (https://www.klaviyo.com/forms/<FORM_ID>). It can be helpful to first perform a GET to retrieve an existing form to define the structure for a step, and use that when creating your form.
- Retrieve that form using the
GET /api/forms/{id}; this will return the encoded form's definition. - Modify the definition in the following way:
- Delete all instances of
idreturned in the GET response. - Remove
created_atandupdated_atfrom theattributesobject. - Modify your form's definition as needed.
- Delete all instances of
- Use the modified response body as the request body for your Create Form call.
Your payload should end up looking like this:
{
"data": {
"type": "form",
"attributes": {
"status": "draft",
"ab_test": false,
"name": "New Class Discount - Gym",
"definition": {
"versions": [
{
"steps": [
{
"columns": [
{
"rows": [
{
"blocks": [
{
"type": "image",
"styles": {
"horizontal_alignment": "left",
"width": 185,
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 32
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"image": {
"id": 213397732,
"alt_text": "logo placeholder"
},
"additional_fields": null
},
"action": null
}
]
},
{
"blocks": [
{
"type": "html_text",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": "<h1 style=\"font-size: 14px; font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 400; text-align: left; line-height: 400%;\"><span style=\"font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 80px; color: rgb(71, 95, 71);\">YOU’VE </span><br><span style=\"font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 80px; color: rgb(71, 95, 71);\">GOT 20% </span><br><span style=\"font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 80px; color: rgb(71, 95, 71);\"><span style=\"font-style: italic;\">OFF NEW CLASSES</span> </span></h1>"
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 24,
"bottom": 16
},
"background_color": null,
"width": "fit",
"height": 58,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 0,
"color": "rgba(71,95,71)",
"style": "solid",
"thickness": 2
},
"text_styles": {
"font_family": "'Poppins', Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 32,
"font_weight": 400,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(135,11,33,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "GET ACTIVE",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": true,
"type": "next_step",
"properties": {
"list_id": "{SOME_LIST_ID}"
}
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null,
"width": "fit",
"height": 24,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 2,
"color": null,
"style": null,
"thickness": null
},
"text_styles": {
"font_family": "'Poppins', Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 20,
"font_weight": 400,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(135,11,33,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "NO THANKS",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": false,
"type": "close",
"properties": null
}
}
]
}
],
"styles": null
},
{
"rows": [],
"styles": {
"background_image": {
"styles": {
"horizontal_alignment": "center",
"width": 500,
"position": "cover",
"vertical_alignment": "center",
"custom_width": null
},
"properties": {
"id": 213397207,
"alt_text": null
}
},
"background_color": null
}
}
],
"name": "Micro yes",
"steps": null
},
{
"columns": [
{
"rows": [
{
"blocks": [
{
"type": "image",
"styles": {
"horizontal_alignment": "left",
"width": 185,
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 32
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"image": {
"id": 213397732,
"alt_text": "logo placeholder"
},
"additional_fields": null
},
"action": null
}
]
},
{
"blocks": [
{
"type": "html_text",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": "<h1 style=\"font-size: 14px; font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 400; text-align: left; line-height: 400%;\"><span style=\"font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 80px; color: rgb(71, 95, 71);\">YOU’VE </span><br><span style=\"font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 80px; color: rgb(71, 95, 71);\">GOT 20% </span><br><span style=\"font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 80px; color: rgb(71, 95, 71);\"><span style=\"font-style: italic;\">OFF NEW CLASSES</span> </span></h1>"
}
}
]
},
{
"blocks": [
{
"type": "email",
"styles": {
"padding": {
"left": 0,
"right": 104,
"top": 0,
"bottom": 0
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "email",
"show_label": false,
"placeholder": "EMAIL",
"required": true,
"error_messages": null,
"property_name": "$email"
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 8,
"bottom": 16
},
"background_color": null,
"width": "fit",
"height": 58,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 0,
"color": "rgba(71,95,71)",
"style": "solid",
"thickness": 2
},
"text_styles": {
"font_family": "'Poppins', Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 32,
"font_weight": 400,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(135,11,33,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "GET 20% OFF",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": true,
"type": "next_step",
"properties": {
"list_id": "{SOME_LIST_ID}"
}
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null,
"width": "fit",
"height": 24,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 2,
"color": null,
"style": null,
"thickness": null
},
"text_styles": {
"font_family": "'Poppins', Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 20,
"font_weight": 400,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(135,11,33,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "NO THANKS",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": false,
"type": "close",
"properties": null
}
}
]
}
],
"styles": null
},
{
"rows": [],
"styles": {
"background_image": {
"styles": {
"horizontal_alignment": "center",
"width": 500,
"position": "cover",
"vertical_alignment": "center",
"custom_width": null
},
"properties": {
"id": 213397207,
"alt_text": null
}
},
"background_color": null
}
}
],
"name": "Email opt in",
"steps": null
},
{
"columns": [
{
"rows": [
{
"blocks": [
{
"type": "image",
"styles": {
"horizontal_alignment": "left",
"width": 185,
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 32
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"image": {
"id": 213397732,
"alt_text": "logo placeholder"
},
"additional_fields": null
},
"action": null
}
]
},
{
"blocks": [
{
"type": "html_text",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": "<h1 style=\"font-size: 14px; font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 400; text-align: left; line-height: 400%; letter-spacing: 1px;\"><span style=\"color: rgb(71, 95, 71); font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 800; font-style: normal; font-size: 72px;\">ONE MORE STEP</span></h1>"
}
}
]
},
{
"blocks": [
{
"type": "sms_disclosure",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 8,
"bottom": 8
},
"background_color": null,
"link_styles": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 12,
"font_weight": 400,
"text_color": "#000000",
"character_spacing": 0
},
"text_styles": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 12,
"font_weight": 400,
"text_color": "#000000",
"character_spacing": 0
}
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": {
"type": "custom",
"compliance_company_name": "Test Account",
"privacy_policy_url": "http://google.com",
"terms_of_service_url": "http://haha.com",
"html": "<p>By submitting this form and signing up for texts, you consent to receive marketing text messages (e.g. promos, cart reminders) from Test Account at the number provided, including messages sent by autodialer. Consent is not a condition of purchase. Msg & data rates may apply. Msg frequency varies. Unsubscribe at any time by replying STOP or clicking the unsubscribe link (where available). <a href=\"http://google.com\">Privacy Policy</a> & <a href=\"http://haha.com\">Terms</a>.</p>"
}
}
}
]
},
{
"blocks": [
{
"type": "phone_number",
"styles": {
"padding": {
"left": 0,
"right": 104,
"top": 0,
"bottom": 0
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "",
"show_label": false,
"placeholder": "Phone Number",
"required": false,
"error_messages": null,
"property_name": "$phone_number",
"sms_consent_type": ["phone_number_only"]
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 8,
"bottom": 16
},
"background_color": null,
"width": "fit",
"height": 58,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 0,
"color": "rgba(71,95,71)",
"style": "solid",
"thickness": 2
},
"text_styles": {
"font_family": "'Poppins', Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 32,
"font_weight": 400,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(135,11,33,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "GET 20% OFF",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": true,
"type": "next_step",
"properties": {
"list_id": "{SOME_LIST_ID}"
}
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null,
"width": "fit",
"height": 24,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 2,
"color": null,
"style": null,
"thickness": null
},
"text_styles": {
"font_family": "'Poppins', Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 20,
"font_weight": 400,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(135,11,33,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "NO THANKS",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": false,
"type": "close",
"properties": null
}
}
]
}
],
"styles": null
},
{
"rows": [],
"styles": {
"background_image": {
"styles": {
"horizontal_alignment": "center",
"width": 500,
"position": "cover",
"vertical_alignment": "center",
"custom_width": null
},
"properties": {
"id": 213397207,
"alt_text": null
}
},
"background_color": null
}
}
],
"name": "SMS opt-in",
"steps": null
},
{
"columns": [
{
"rows": [
{
"blocks": [
{
"type": "image",
"styles": {
"horizontal_alignment": "left",
"width": 185,
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 32
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"image": {
"id": 213397732,
"alt_text": "logo placeholder"
},
"additional_fields": null
},
"action": null
}
]
},
{
"blocks": [
{
"type": "html_text",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"background_color": null
},
"properties": {
"display_device": ["desktop", "mobile"],
"content": "<h1 style=\"font-size: 14px; line-height: 400%; font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; text-align: left;\"><span style=\"font-weight: 800; font-size: 80px; font-family: Poppins, Arial, 'Helvetica Neue', Helvetica, sans-serif; color: rgb(71, 95, 71);\">THANKS FOR <span style=\"font-style: italic;\">SIGNING UP</span></span></h1>"
}
}
]
},
{
"blocks": [
{
"type": "button",
"styles": {
"padding": {
"left": 0,
"right": 0,
"top": 24,
"bottom": 24
},
"background_color": null,
"width": "fit",
"height": 24,
"hover_background_color": null,
"hover_text_color": null,
"border_styles": {
"radius": 2,
"color": null,
"style": null,
"thickness": null
},
"text_styles": {
"font_family": "'Century Gothic', CenturyGothic, AppleGothic, sans-serif",
"font_size": 20,
"font_weight": 700,
"text_color": "rgba(71,95,71)",
"character_spacing": 0
},
"color": "rgba(48,59,67,0)"
},
"properties": {
"display_device": ["desktop", "mobile"],
"label": "BROWSE MORE CLASSES",
"additional_fields": [
{
"name": "$source",
"value": "New Class Discount - Gym"
}
]
},
"action": {
"submit": true,
"type": "go_to_inbox",
"properties": null
}
}
]
}
],
"styles": null
},
{
"rows": [],
"styles": {
"background_image": {
"styles": {
"horizontal_alignment": "center",
"width": 500,
"position": "cover",
"vertical_alignment": "center",
"custom_width": null
},
"properties": {
"id": 213397207,
"alt_text": null
}
},
"background_color": null
}
}
],
"name": "success step",
"steps": null
}
],
"triggers": [
{
"properties": {},
"type": "unidentified_profiles"
},
{
"properties": {},
"type": "previously_submitted"
},
{
"type": "delay",
"properties": {
"seconds": 5
}
},
{
"type": "scroll_percentage",
"properties": {
"percentage": 30
}
},
{
"properties": {},
"type": "exit_intent"
},
{
"type": "after_close_or_submit_timeout",
"properties": {
"timeout_days": 1
}
}
],
"teaser": {
"content": "<p style=\"text-align: center; font-size: 14px; font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; font-weight: 400;\"><span style=\"font-size: 18px; color: rgb(215, 223, 216); font-family: 'Century Gothic', CenturyGothic, AppleGothic, sans-serif; font-weight: bold; font-style: normal;\">20% OFF </span><span style=\"font-size: 18px; color: rgb(215, 223, 216); font-family: 'Century Gothic', CenturyGothic, AppleGothic, sans-serif; font-weight: bold; font-style: normal;\">NEW CLASSES</span></p>",
"display_order": "after",
"teaser_type": "rectangle",
"location": "center_left",
"size": "custom",
"custom_size": 240,
"styles": {
"background_color": "rgba(71,95,71)",
"drop_shadow": {
"enabled": true,
"blur": 30,
"color": "rgba(0,0,0,0.15)"
},
"corner_radius": 4,
"background_image": null,
"close_button": {
"background_color": "#000000",
"outline_color": "#FFFFFF",
"color": "#FFFFFF",
"stroke": 2,
"size": 20,
"margin": {
"left": 16,
"right": 16,
"top": 16,
"bottom": 16
}
},
"margin": {
"left": 20,
"right": 0,
"top": 0,
"bottom": 0
}
},
"close_button": false
},
"name": "Default Flyout",
"styles": {
"wrap_content": false,
"border_styles": {
"radius": 0,
"color": "#000000",
"style": null,
"thickness": 0
},
"close_button": {
"background_color": "rgba(255,255,255,0)",
"outline_color": "rgba(255,255,255,0)",
"color": "rgba(55,63,71,0)",
"stroke": 1,
"size": 35,
"margin": {
"left": 8,
"right": 8,
"top": 8,
"bottom": 8
}
},
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
},
"padding": {
"left": 56,
"right": 56,
"top": 0,
"bottom": 0
},
"minimum_height": 640,
"width": "custom",
"custom_width": 1000,
"background_image": null,
"background_color": "#D7DFD8",
"input_styles": {
"text_styles": {
"font_family": "\"Century Gothic\", CenturyGothic, AppleGothic, sans-serif",
"font_size": 20,
"font_weight": 400,
"text_color": "#000000",
"character_spacing": 0
},
"label_color": "#475F47",
"text_color": "#475F47",
"placeholder_color": "#475F47",
"background_color": "rgba(255,255,255,0)",
"border_color": "#475F47",
"border_focus_color": "#475F47",
"focus_outline_color": "#0064CD",
"corner_radius": 0,
"field_height": 58
},
"drop_shadow": {
"enabled": true,
"blur": 30,
"color": "rgba(0,0,0,0.15)"
},
"overlay_color": "rgba(20,20,20,0.6)",
"rich_text_styles": {
"body": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 16,
"font_weight": 400,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"link": {
"color": "#0066cc",
"decoration": "underline"
},
"h1": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 48,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h2": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 36,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h3": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 28,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h4": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 20,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h5": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 13,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
},
"h6": {
"font_family": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"font_size": 11,
"font_weight": 700,
"text_color": "#000000",
"line_spacing": 1.0,
"character_spacing": 0,
"alignment": "left",
"margin": {
"left": 0,
"right": 0,
"top": 0,
"bottom": 0
}
}
},
"mobile_overlay": {
"color": "rgba(20, 20, 20, 0.5)",
"enabled": false
},
"banner_styles": null
},
"properties": {
"side_image_settings": {
"size": "medium",
"alignment": "right",
"device_type": ["desktop", "mobile"]
},
"click_outside_to_close": ["mobile", "desktop"],
"rule_based_trigger_evaluation": "any",
"record_utm_params_on_submit": false,
"show_close_button": true
},
"type": "popup",
"location": null,
"status": "draft",
"ab_test": false
}
]
}
},
"links": {
"self": "https://a.klaviyo.com/api/forms/VcgwuS/"
}
},
"links": {
"self": "https://a.klaviyo.com/api/forms/VcgwuS"
}
}
All forms must be created in a draft status. A successful request will return a 201 and the form's definition augmented with IDs.
Update a form
Edit a form's draft with the Update Form endpoint. PATCH /api/forms/{id}
You can update a form's name and definition. Attributes you omit keep their current values. Update Form supports web forms only.
When you send a definition, it replaces the stored definition entirely, so use the same workflow as creating a form:
- Retrieve the form with
GET /api/forms/{id}. - Modify the draft versions in the returned definition. Keep every version and its
id. - Send the full definition in your Update Form request.
The following rules apply to updates:
- You can only edit draft versions. Return each live version exactly as you received it.
- You can't add or remove versions.
statusandab_testare read-only, both on the form and on each version. A version'schannelandspecialtiesare also read-only. Changing a read-only field returns a400error that points to the field.- If the form changes while your request is processing, the request returns a
409error. Retrieve the form again and retry.
Your changes stay in draft until you publish the form.
Publish and unpublish a form
Publish a form's draft version with the Publish Form endpoint, and take a live form down with the Unpublish Form endpoint. Both endpoints create a job that references the form:
curl --request POST \
--url https://a.klaviyo.com/api/form-publish-jobs \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/vnd.api+json' \
--header 'content-type: application/vnd.api+json' \
--header 'revision: 2026-10-15' \
--data '
{
"data": {
"type": "form-publish-job",
"relationships": {
"form": {
"data": {
"type": "form",
"id": "VcgwuS"
}
}
}
}
}
'
To unpublish, send the same request body to POST /api/form-unpublish-jobs with the type form-unpublish-job.
Both endpoints return a 202 with a job resource, but the work finishes before the response returns. The form is already live, or already unpublished, when you receive the response, and you can't retrieve the job afterwards. To confirm the result, call Get Form and check the form's status.
Keep the following in mind:
- Publishing replaces the live version with the draft version. If the form has no draft version, the request returns a
400error. - If the draft has an issue that blocks publishing, the request returns a
400error that explains what to fix. - Unpublishing a form that isn't live succeeds without making changes, so you can safely retry it.
- These endpoints don't support A/B tests. Publishing a form with a draft A/B test, or unpublishing a form with a live A/B test, returns a
409error. Manage A/B tests from the form editor in Klaviyo.
Next steps
- Create a form with the Create Form endpoint.
- Make a call to Get Form to retrieve the newly-created form.
- Edit the draft with Update Form.
- Make the form live with Publish Form, or take it down with Unpublish Form.