post
https://api.omnisend.com/api/forms
Create a form with its full content and styling. New forms start in draft status and are not shown to
visitors until enabled via POST /forms/{formID}/enable.
Choosing a display type:
popup— modal centered over the page that dims the background. Highest visibility; best for launch offers,
discounts, and exit-intent capture where interrupting the visitor is acceptable.flyout— compact panel anchored to a page corner that leaves the page usable. Less intrusive; suited to
always-on signup while the visitor keeps browsing.embedded— rendered inline within the host page's content. Use for a permanent signup block placed in a
section, sidebar, or footer rather than an overlay.landingPage— full standalone page hosted by Omnisend. Use for campaigns driven by ads, emails, or shared
links where there is no host site to embed into.fullscreen— overlay that covers the entire viewport. Maximum attention; best for high-value offers where
taking over the screen is justified.
Content structure: content is a tree of steps → sections → rows → columns → blocks. A step is
one screen of the form (up to four steps are allowed); each block (text, image, button, input field, wheel of
fortune, etc.) carries its own configuration and an optional style preset. Server-generated IDs on sections,
rows, columns, and blocks are assigned on create and may be omitted from the request.
Games: a mysteryBox or scratchCard block adds an interactive game to the form. A form may contain
at most one game, it cannot be combined with a wheel of fortune, and the game's step must be placed before or
at the first step containing a required email or phone field. The game reward is revealed to the visitor
through a discount block of type game on the success step.
Scopes:
forms.write
Rate Limiting:
This endpoint is rate limited to 40 requests per minute.
Examples: forms with games
A form may contain one mysteryBox or scratchCard block. The game's step must be placed before or at the first step containing a required email or phone field, and the reward is revealed through a discount block of type game on the success step.
Create a form with a mystery box:
curl --request POST \
--url https://api.omnisend.com/api/forms \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-03-15' \
--header 'content-type: application/json' \
--data '{
"name": "Mystery box signup",
"displayType": "popup",
"content": {
"generalSettings": {
"content": { "width": "600px", "color": "#000000" },
"body": {
"backgroundColor": "#ffffff",
"borderRadius": "8px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "#cccccc"
},
"link": { "color": "#0000ee" },
"buttonPresets": [
{
"id": "primary_button",
"name": "Primary",
"styles": {
"backgroundColor": "#000000",
"borderRadius": "8px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "#000000",
"fontWeight": "bold",
"fontStyle": "normal",
"textDecoration": "none",
"fontFamily": "Arial",
"fontSize": "16px",
"color": "#ffffff"
}
},
{
"id": "secondary_button",
"name": "Secondary",
"styles": {
"backgroundColor": "#ffffff",
"borderRadius": "8px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "#000000",
"fontWeight": "normal",
"fontStyle": "normal",
"textDecoration": "none",
"fontFamily": "Arial",
"fontSize": "16px",
"color": "#000000"
}
},
{
"id": "tertiary_button",
"name": "Tertiary",
"styles": {
"backgroundColor": "transparent",
"borderRadius": "0px",
"borderWidth": "0px",
"borderStyle": "solid",
"borderColor": "transparent",
"fontWeight": "normal",
"fontStyle": "normal",
"textDecoration": "underline",
"fontFamily": "Arial",
"fontSize": "16px",
"color": "#000000"
}
}
],
"textPresets": [
{ "id": "heading_large", "name": "Heading Large", "styles": { "fontFamily": "Arial", "fontSize": "32px", "color": "#000000", "lineHeight": "125%" } },
{ "id": "heading_medium", "name": "Heading Medium", "styles": { "fontFamily": "Arial", "fontSize": "24px", "color": "#000000", "lineHeight": "125%" } },
{ "id": "heading_small", "name": "Heading Small", "styles": { "fontFamily": "Arial", "fontSize": "20px", "color": "#000000", "lineHeight": "125%" } },
{ "id": "paragraph", "name": "Paragraph", "styles": { "fontFamily": "Arial", "fontSize": "16px", "color": "#000000", "lineHeight": "150%" } },
{ "id": "footnote", "name": "Footnote", "styles": { "fontFamily": "Arial", "fontSize": "12px", "color": "#757575", "lineHeight": "150%" } }
],
"fieldStyles": {
"fontFamily": "Arial",
"fontSize": "14px",
"errorColor": "#ff0000",
"label": { "color": "#000000" },
"placeholder": { "color": "#999999" },
"field": {
"color": "#000000",
"backgroundColor": "#ffffff",
"borderRadius": "4px",
"borderStyle": "solid",
"borderColor": "#cccccc",
"borderWidth": "1px"
}
}
},
"steps": [
{
"sections": [
{
"rows": [
{
"columns": [
{
"width": "100%",
"blocks": [
{
"type": "mysteryBox",
"mysteryBox": {
"rewards": [{ "name": "10% off", "discountCode": "SAVE10" }],
"boxes": [
{ "type": "text", "text": "?", "backgroundColor": "#FFD60A", "textColor": "#000000" },
{ "type": "text", "text": "?", "backgroundColor": "#FFD60A", "textColor": "#000000" },
{ "type": "text", "text": "?", "backgroundColor": "#FFD60A", "textColor": "#000000" }
],
"boxStyle": { "width": 80, "borderRadius": "8px", "fontSize": "32px" }
}
},
{ "type": "emailField", "emailField": { "isRequired": true } },
{ "type": "button", "button": { "type": "submit", "text": "Subscribe" } }
]
}
]
}
]
}
]
}
],
"successStep": {
"sections": [
{
"rows": [
{
"columns": [
{
"width": "100%",
"blocks": [
{ "type": "text", "text": "<p>You won!</p>" },
{ "type": "discount", "discount": { "type": "game" } }
]
}
]
}
]
}
]
}
}
}'Create a form with a scratch card:
curl --request POST \
--url https://api.omnisend.com/api/forms \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-03-15' \
--header 'content-type: application/json' \
--data '{
"name": "Scratch card signup",
"displayType": "popup",
"content": {
"generalSettings": {
"content": { "width": "600px", "color": "#000000" },
"body": {
"backgroundColor": "#ffffff",
"borderRadius": "8px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "#cccccc"
},
"link": { "color": "#0000ee" },
"buttonPresets": [
{
"id": "primary_button",
"name": "Primary",
"styles": {
"backgroundColor": "#000000",
"borderRadius": "8px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "#000000",
"fontWeight": "bold",
"fontStyle": "normal",
"textDecoration": "none",
"fontFamily": "Arial",
"fontSize": "16px",
"color": "#ffffff"
}
},
{
"id": "secondary_button",
"name": "Secondary",
"styles": {
"backgroundColor": "#ffffff",
"borderRadius": "8px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "#000000",
"fontWeight": "normal",
"fontStyle": "normal",
"textDecoration": "none",
"fontFamily": "Arial",
"fontSize": "16px",
"color": "#000000"
}
},
{
"id": "tertiary_button",
"name": "Tertiary",
"styles": {
"backgroundColor": "transparent",
"borderRadius": "0px",
"borderWidth": "0px",
"borderStyle": "solid",
"borderColor": "transparent",
"fontWeight": "normal",
"fontStyle": "normal",
"textDecoration": "underline",
"fontFamily": "Arial",
"fontSize": "16px",
"color": "#000000"
}
}
],
"textPresets": [
{ "id": "heading_large", "name": "Heading Large", "styles": { "fontFamily": "Arial", "fontSize": "32px", "color": "#000000", "lineHeight": "125%" } },
{ "id": "heading_medium", "name": "Heading Medium", "styles": { "fontFamily": "Arial", "fontSize": "24px", "color": "#000000", "lineHeight": "125%" } },
{ "id": "heading_small", "name": "Heading Small", "styles": { "fontFamily": "Arial", "fontSize": "20px", "color": "#000000", "lineHeight": "125%" } },
{ "id": "paragraph", "name": "Paragraph", "styles": { "fontFamily": "Arial", "fontSize": "16px", "color": "#000000", "lineHeight": "150%" } },
{ "id": "footnote", "name": "Footnote", "styles": { "fontFamily": "Arial", "fontSize": "12px", "color": "#757575", "lineHeight": "150%" } }
],
"fieldStyles": {
"fontFamily": "Arial",
"fontSize": "14px",
"errorColor": "#ff0000",
"label": { "color": "#000000" },
"placeholder": { "color": "#999999" },
"field": {
"color": "#000000",
"backgroundColor": "#ffffff",
"borderRadius": "4px",
"borderStyle": "solid",
"borderColor": "#cccccc",
"borderWidth": "1px"
}
}
},
"steps": [
{
"sections": [
{
"rows": [
{
"columns": [
{
"width": "100%",
"blocks": [
{
"type": "scratchCard",
"scratchCard": {
"rewards": [{ "name": "Free shipping", "discountCode": "SHIP" }],
"cover": { "imageUrl": "https://example.com/cover.png", "altText": "Scratch here" },
"revealThreshold": 50,
"brushSize": 30,
"prizeTextColor": "#000000",
"prizeBackgroundColor": "#FFFFFF",
"cardStyle": { "width": 90, "borderRadius": "12px" }
}
},
{ "type": "emailField", "emailField": { "isRequired": true } },
{ "type": "button", "button": { "type": "submit", "text": "Subscribe" } }
]
}
]
}
]
}
]
}
],
"successStep": {
"sections": [
{
"rows": [
{
"columns": [
{
"width": "100%",
"blocks": [
{ "type": "text", "text": "<p>You won!</p>" },
{ "type": "discount", "discount": { "type": "game" } }
]
}
]
}
]
}
]
}
}
}'