Forms
Create form
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" } }
]
}
]
}
]
}
]
}
}
}'
post/forms
Request
- Base URLhttps://api.omnisend.com/api
- URLhttps://api.omnisend.com/api/forms
- Auth
- OAuth 2Client credentialsToken URL: https://app.omnisend.com/oauth2/token scopes: forms.write
- or API key in header Authorization
Headers
Omnisend-Versionstring required
API version that specifies the response format and behaviour
Request body
Response
Created form
Changes
No recorded changes to this operation across all 1 revision of this API.