openapi: 3.0.2
info:
title: Klaviyo Accounts Forms API
version: '2026-04-15'
description: The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.
contact:
name: Klaviyo Developer Experience Team
email: developers@klaviyo.com
url: https://developers.klaviyo.com
termsOfService: https://www.klaviyo.com/legal/api-terms
license:
name: License
url: https://www.klaviyo.com/legal
servers:
- url: https://a.klaviyo.com
description: Production
security:
- Klaviyo-API-Key: []
tags:
- name: Forms
description: forms
paths:
/api/forms:
get:
operationId: get_forms
summary: Get Forms
description: 'Get all forms in an account.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: fields[form]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
required: false
schema:
type: array
items:
type: string
enum:
- ab_test
- created_at
- name
- status
- updated_at
explode: false
- name: filter
in: query
description: 'For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#filtering<br>Allowed field(s)/operator(s):<br>`id`: `any`, `equals`<br>`name`: `any`, `contains`, `equals`<br>`ab_test`: `equals`<br>`updated_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`<br>`created_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`<br>`status`: `equals`'
schema:
type: string
example: equals(id,'Y6nRLr')
- name: page[cursor]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#pagination
required: false
schema:
type: string
- name: page[size]
in: query
description: 'Default: 20. Min: 1. Max: 100.'
required: false
schema:
type: integer
default: 20
maximum: 100
minimum: 1
- name: sort
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sorting
schema:
type: string
enum:
- created_at
- -created_at
- updated_at
- -updated_at
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetFormResponseCollection'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
post:
operationId: create_form
summary: Create Form
description: 'Create a new form.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:write`'
parameters:
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
requestBody:
description: Creates a Form from parameters
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/FormCreateQuery'
responses:
'201':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PostEncodedFormResponse'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:write
/api/forms/{id}:
get:
operationId: get_form
summary: Get Form
description: 'Get the form with the given ID.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: id
in: path
description: The ID of the form
required: true
schema:
description: The ID of the form
type: string
example: Y6nRLr
- name: fields[form]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
required: false
schema:
type: array
items:
type: string
enum:
- ab_test
- created_at
- definition
- definition.versions
- name
- status
- updated_at
explode: false
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetEncodedFormResponse'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
delete:
operationId: delete_form
summary: Delete Form
description: 'Delete a given form.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:write`'
parameters:
- name: id
in: path
description: The ID of the form
required: true
schema:
description: The ID of the form
type: string
example: Y6nRLr
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:write
/api/form-versions/{id}:
get:
operationId: get_form_version
summary: Get Form Version
description: 'Get the form version with the given ID.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: id
in: path
description: The ID of the form version
required: true
schema:
description: The ID of the form version
type: string
example: '1234567'
- name: fields[form-version]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
required: false
schema:
type: array
items:
type: string
enum:
- ab_test
- ab_test.variation_name
- created_at
- form_type
- status
- updated_at
- variation_name
explode: false
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetFormVersionResponse'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
/api/forms/{id}/form-versions:
get:
operationId: get_versions_for_form
summary: Get Versions for Form
description: 'Get the form versions for the given form.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: id
in: path
description: The ID of the form
required: true
schema:
description: The ID of the form
type: string
example: Y6nRLr
nullable: true
- name: fields[form-version]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
required: false
schema:
type: array
items:
type: string
enum:
- ab_test
- ab_test.variation_name
- created_at
- form_type
- status
- updated_at
- variation_name
explode: false
- name: filter
in: query
description: 'For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#filtering<br>Allowed field(s)/operator(s):<br>`form_type`: `any`, `equals`<br>`status`: `equals`<br>`updated_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`<br>`created_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`'
schema:
type: string
example: equals(form_type,'popup')
- name: page[cursor]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#pagination
required: false
schema:
type: string
- name: page[size]
in: query
description: 'Default: 20. Min: 1. Max: 100.'
required: false
schema:
type: integer
default: 20
maximum: 100
minimum: 1
- name: sort
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sorting
schema:
type: string
enum:
- created_at
- -created_at
- updated_at
- -updated_at
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetFormVersionResponseCollection'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-operation-aliases:
- get_form_form_versions
- get_form_versions
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
/api/forms/{id}/relationships/form-versions:
get:
operationId: get_version_ids_for_form
summary: Get Version IDs for Form
description: 'Get the IDs of the form versions for the given form.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: id
in: path
description: The ID of the form
required: true
schema:
description: The ID of the form
type: string
example: Y6nRLr
nullable: true
- name: filter
in: query
description: 'For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#filtering<br>Allowed field(s)/operator(s):<br>`form_type`: `any`, `equals`<br>`status`: `equals`<br>`updated_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`<br>`created_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`'
schema:
type: string
example: equals(form_type,'popup')
- name: page[cursor]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#pagination
required: false
schema:
type: string
- name: page[size]
in: query
description: 'Default: 20. Min: 1. Max: 100.'
required: false
schema:
type: integer
default: 20
maximum: 100
minimum: 1
- name: sort
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sorting
schema:
type: string
enum:
- created_at
- -created_at
- updated_at
- -updated_at
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetFormVersionsRelationshipsResponseCollection'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-operation-aliases:
- get_form_relationships_form_versions
- get_form_relationships_versions
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
/api/form-versions/{id}/form:
get:
operationId: get_form_for_form_version
summary: Get Form for Form Version
description: 'Get the form associated with the given form version.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: id
in: path
description: The ID of the form version
required: true
schema:
description: The ID of the form version
type: string
example: '1234567'
- name: fields[form]
in: query
description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
required: false
schema:
type: array
items:
type: string
enum:
- ab_test
- created_at
- name
- status
- updated_at
explode: false
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetFormResponse'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-operation-aliases:
- get_form_version_form
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
/api/form-versions/{id}/relationships/form:
get:
operationId: get_form_id_for_form_version
summary: Get Form ID for Form Version
description: 'Get the ID of the form associated with the given form version.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`
**Scopes:**
`forms:read`'
parameters:
- name: id
in: path
description: The ID of the form version
required: true
schema:
description: The ID of the form version
type: string
example: '1234567'
- name: revision
in: header
description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
required: true
schema:
type: string
default: '2026-04-15'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/GetFormVersionFormRelationshipResponse'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Forms
x-klaviyo-operation-aliases:
- get_form_version_relationships_form
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 3/s
steady: 60/m
x-klaviyo-scopes:
- forms:read
components:
schemas:
SideImageSettings:
type: object
properties:
size:
description: Side image size enumeration.
type: string
example: medium
default: medium
enum:
- large
- medium
- small
alignment:
description: Side image alignment enumeration.
type: string
example: left
default: left
enum:
- left
- right
device_type:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
BackInStock:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
type:
type: string
enum:
- back_in_stock
properties:
$ref: '#/components/schemas/BackInStockProperties'
required:
- type
SubmitBackInStock:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
type:
type: string
enum:
- submit_back_in_stock
properties:
$ref: '#/components/schemas/SubmitBackInStockProperties'
nullable: true
submit:
type: boolean
example: true
default: true
enum:
- true
required:
- type
ImageProperties:
type: object
properties:
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
classname:
type: string
nullable: true
image:
$ref: '#/components/schemas/ImageAssetProperties'
nullable: true
additional_fields:
type: array
items:
$ref: '#/components/schemas/AdditionalField'
nullable: true
required:
- image
Channel:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
type:
type: string
enum:
- channel
properties:
$ref: '#/components/schemas/ChannelProperties'
required:
- type
- properties
Redirect:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
submit:
type: boolean
type:
type: string
enum:
- redirect
properties:
$ref: '#/components/schemas/RedirectProperties'
required:
- submit
- type
- properties
SubscribeViaWhatsApp:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
submit:
type: boolean
example: true
default: true
enum:
- true
type:
type: string
enum:
- subscribe_via_whatsapp
properties:
$ref: '#/components/schemas/SubscribeViaWhatsAppProperties'
required:
- type
- properties
CloseProperties:
type: object
properties:
list_id:
type: string
nullable: true
SubscribeViaWhatsAppProperties:
type: object
properties:
opt_in_keyword:
type: string
nullable: true
opt_in_message:
type: string
sending_number:
type: string
nullable: true
required:
- opt_in_keyword
- opt_in_message
- sending_number
UniqueCouponConfig:
type: object
properties:
type:
type: string
enum:
- unique
id:
type: integer
nullable: true
code:
type: string
nullable: true
fallback_coupon_code:
type: string
nullable: true
integration:
description: Coupon integration types for unique coupon blocks.
type: string
example: shopify
default: shopify
enum:
- api
- magento_two
- prestashop
- shopify
- uploaded
- woocommerce
required:
- type
HTMLTextProperties:
type: object
properties:
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
classname:
type: string
nullable: true
content:
default: ''
type: string
BackInStockEmailConsentCheckboxProperties:
type: object
properties:
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
classname:
type: string
nullable: true
label:
type: string
nullable: true
show_label:
type: boolean
default: false
error_messages:
$ref: '#/components/schemas/ErrorMessages'
nullable: true
required:
type: boolean
default: false
enum:
- false
property_name:
type: string
example: opt_in_promotional_email
default: opt_in_promotional_email
enum:
- opt_in_promotional_email
checkbox_text:
type: string
placeholder:
enum:
- null
required:
- checkbox_text
RatingStyle:
type: object
properties:
color:
type: string
example: '#F8BE00'
default: '#F8BE00'
empty_color:
type: string
example: '#EBEEEF'
default: '#EBEEEF'
font_size:
type: integer
example: 16
default: 16
shape:
description: Enumeration for review shapes.
type: string
example: star
default: star
enum:
- circle
- heart
- star
alignment:
description: Horizontal alignment enumeration.
type: string
example: center
default: center
enum:
- center
- left
- right
character_spacing:
type: number
default: 0
RedirectProperties:
type: object
properties:
list_id:
type: string
nullable: true
url:
type: string
new_window:
type: boolean
default: false
required:
- url
TextProperties:
type: object
properties:
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
classname:
type: string
nullable: true
property_name:
type: string
label:
type: string
nullable: true
show_label:
type: boolean
default: false
placeholder:
type: string
nullable: true
required:
type: boolean
default: false
nullable: true
error_messages:
$ref: '#/components/schemas/ErrorMessages'
nullable: true
required:
- property_name
DelayProperties:
type: object
properties:
seconds:
type: integer
example: 5
default: 5
OptInCodeStyles:
type: object
properties:
padding:
$ref: '#/components/schemas/Padding'
background_color:
type: string
nullable: true
FormVersionEnum:
type: string
enum:
- form-version
CouponProperties:
type: object
properties:
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
classname:
type: string
nullable: true
coupon:
oneOf:
- $ref: '#/components/schemas/UniqueCouponConfig'
- $ref: '#/components/schemas/StaticCouponConfig'
success_message:
type: string
nullable: true
required:
- coupon
QuoteStyle:
type: object
properties:
font_family:
type: string
example: Arial, 'Helvetica Neue', Helvetica, sans-serif
default: Arial, 'Helvetica Neue', Helvetica, sans-serif
font_size:
type: integer
example: 16
default: 16
text_color:
type: string
example: '#000000'
default: '#000000'
character_spacing:
type: integer
default: 0
font_weight:
type: integer
example: 400
default: 400
alignment:
description: Horizontal alignment enumeration.
type: string
example: center
default: center
enum:
- center
- left
- right
line_height:
type: number
example: 1.5
default: 1.5
LinkStyles:
type: object
properties:
color:
type: string
example: '#0066cc'
default: '#0066cc'
decoration:
type: string
example: underline
default: underline
enum:
- underline
ReviewStyles:
type: object
properties:
padding:
$ref: '#/components/schemas/Padding'
background_color:
type: string
nullable: true
rating_style:
$ref: '#/components/schemas/RatingStyle'
quote_style:
$ref: '#/components/schemas/QuoteStyle'
reviewer_name_style:
$ref: '#/components/schemas/ReviewerNameStyle'
block_background_color:
type: string
example: rgba(255, 255, 255, 0)
default: rgba(255, 255, 255, 0)
ListsAndSegmentsProperties:
type: object
properties:
allow_list:
type: array
items:
type: string
nullable: true
deny_list:
type: array
items:
type: string
nullable: true
OptInCode:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
type:
type: string
enum:
- opt_in_code
styles:
$ref: '#/components/schemas/OptInCodeStyles'
properties:
$ref: '#/components/schemas/OptInCodeProperties'
required:
- type
- properties
SpinToWinSliceStyle:
type: object
properties:
background_color:
type: string
example: rgba(0,0,0,1)
default: rgba(0,0,0,1)
text_color:
type: string
example: rgba(255,255,255,1)
default: rgba(255,255,255,1)
BackInStockEmailConsentCheckboxStyles:
type: object
properties:
padding:
$ref: '#/components/schemas/Padding'
background_color:
type: string
nullable: true
horizontal_alignment:
description: Horizontal alignment enumeration.
type: string
example: left
default: left
enum:
- center
- left
- right
PhoneNumberStyles:
type: object
properties:
padding:
$ref: '#/components/schemas/Padding'
background_color:
type: string
nullable: true
Padding:
type: object
properties:
left:
type: integer
default: 0
right:
type: integer
default: 0
top:
type: integer
default: 0
bottom:
type: integer
default: 0
AgeGate:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
type:
type: string
enum:
- age_gate
styles:
$ref: '#/components/schemas/AgeGateStyles'
properties:
$ref: '#/components/schemas/AgeGateProperties'
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
required:
- type
- properties
SubmitOptInCode:
type: object
properties:
id:
description: Not allowed on create.
type: string
nullable: true
submit:
type: boolean
example: true
default: true
enum:
- true
type:
type: string
enum:
- submit_opt_in_code
properties:
enum:
- null
required:
- type
SMSDisclosureProperties:
type: object
properties:
display_device:
type: array
items:
type: string
enum:
- both
- desktop
- mobile
description: Enumeration for mobile and desktop.
classname:
type: string
nullable: true
content:
oneOf:
- $ref: '#/components/schemas/SMSDisclosureCustom'
- $ref: '#/components/schemas/SMSDisclosureAccountDefault'
SMSDisclosureStyles:
type: object
properties:
padding:
$ref: '#/components/schemas/Padding'
background_color:
type: string
nullable: true
link_styles:
$ref: '#/components/schemas/SMSDisclosureTextStyle'
text_styles:
$ref: '#/components/schemas/SMSDisclosureTextStyle'
# --- truncated at 32 KB (145 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klaviyo/refs/heads/main/openapi/klaviyo-forms-api-openapi.yml