Pop-ups
Pop-ups endpoints of the Zanfia Workspace API, with schemas and code samples.
Pop-ups on your hosted pages: each one holds a standalone signup form (a new form is created when you do not pass content.formId). A pop-up is created as a draft and goes live with the status route once it has a title, a button text and a form; at most 20 are active at once. Triggers are set per device (desktop and phone), plus where it shows, how often and an optional schedule. Live sites pick changes up within a few minutes. Requires the pop-ups feature on the plan (403 otherwise). All routes require a Authorization: Bearer header — see Authentication.
List pop-ups
/popupsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Response Body
application/json
application/json
curl -X GET "https://example.com/popups"{ "count": 0, "popups": [ { "id": "string", "name": "string", "status": "draft", "priority": 0, "language": "pl", "copy": { "title": "string", "text": "string", "buttonText": "string", "imageUrl": "string", "imageWidth": 0, "imageHeight": 0 }, "content": { "kind": "form", "formId": "string", "successTitle": "string", "successText": "string", "redirectPageId": "string" }, "design": { "layout": "modal", "imagePosition": "top", "accentColor": "string" }, "trigger": { "desktop": { "kind": "entry", "delaySeconds": 0 }, "mobile": { "kind": "entry", "delaySeconds": 0 } }, "targeting": { "surfaces": [ "pages" ], "pages": { "mode": "all", "pageIds": [ "string" ] }, "device": "all", "audience": "all", "hideForSubscribers": true }, "frequency": { "kind": "once", "days": 0 }, "schedule": { "startsAt": "string", "endsAt": "string" }, "createdAt": "string", "updatedAt": "string" } ]}{ "error": "string", "message": "string"}Create a pop-up
/popupsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /popups: always created as a draft.
Response Body
application/json
application/json
curl -X POST "https://example.com/popups" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "id": "string", "name": "string", "status": "draft", "priority": 0, "language": "pl", "copy": { "title": "string", "text": "string", "buttonText": "string", "imageUrl": "string", "imageWidth": 0, "imageHeight": 0 }, "content": { "kind": "form", "formId": "string", "successTitle": "string", "successText": "string", "redirectPageId": "string" }, "design": { "layout": "modal", "imagePosition": "top", "accentColor": "string" }, "trigger": { "desktop": { "kind": "entry", "delaySeconds": 0 }, "mobile": { "kind": "entry", "delaySeconds": 0 } }, "targeting": { "surfaces": [ "pages" ], "pages": { "mode": "all", "pageIds": [ "string" ] }, "device": "all", "audience": "all", "hideForSubscribers": true }, "frequency": { "kind": "once", "days": 0 }, "schedule": { "startsAt": "string", "endsAt": "string" }, "createdAt": "string", "updatedAt": "string"}{ "error": "string", "message": "string"}Pop-up detail
/popups/{popupId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Response Body
application/json
application/json
curl -X GET "https://example.com/popups/string"{ "id": "string", "name": "string", "status": "draft", "priority": 0, "language": "pl", "copy": { "title": "string", "text": "string", "buttonText": "string", "imageUrl": "string", "imageWidth": 0, "imageHeight": 0 }, "content": { "kind": "form", "formId": "string", "successTitle": "string", "successText": "string", "redirectPageId": "string" }, "design": { "layout": "modal", "imagePosition": "top", "accentColor": "string" }, "trigger": { "desktop": { "kind": "entry", "delaySeconds": 0 }, "mobile": { "kind": "entry", "delaySeconds": 0 } }, "targeting": { "surfaces": [ "pages" ], "pages": { "mode": "all", "pageIds": [ "string" ] }, "device": "all", "audience": "all", "hideForSubscribers": true }, "frequency": { "kind": "once", "days": 0 }, "schedule": { "startsAt": "string", "endsAt": "string" }, "createdAt": "string", "updatedAt": "string"}{ "error": "string", "message": "string"}Update a pop-up
/popups/{popupId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
PATCH /popups/:popupId. An active pop-up must stay complete (title, button, form).
Response Body
application/json
application/json
curl -X PATCH "https://example.com/popups/string" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "string", "name": "string", "status": "draft", "priority": 0, "language": "pl", "copy": { "title": "string", "text": "string", "buttonText": "string", "imageUrl": "string", "imageWidth": 0, "imageHeight": 0 }, "content": { "kind": "form", "formId": "string", "successTitle": "string", "successText": "string", "redirectPageId": "string" }, "design": { "layout": "modal", "imagePosition": "top", "accentColor": "string" }, "trigger": { "desktop": { "kind": "entry", "delaySeconds": 0 }, "mobile": { "kind": "entry", "delaySeconds": 0 } }, "targeting": { "surfaces": [ "pages" ], "pages": { "mode": "all", "pageIds": [ "string" ] }, "device": "all", "audience": "all", "hideForSubscribers": true }, "frequency": { "kind": "once", "days": 0 }, "schedule": { "startsAt": "string", "endsAt": "string" }, "createdAt": "string", "updatedAt": "string"}{ "error": "string", "message": "string"}Delete a pop-up
/popups/{popupId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Response Body
application/json
application/json
curl -X DELETE "https://example.com/popups/string"{ "popupId": "string"}{ "error": "string", "message": "string"}Activate or pause a pop-up
/popups/{popupId}/statusAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /popups/:popupId/status: activation checks completeness, the plan and the active cap.
Response Body
application/json
application/json
curl -X POST "https://example.com/popups/string/status" \ -H "Content-Type: application/json" \ -d '{ "status": "active" }'{ "id": "string", "name": "string", "status": "draft", "priority": 0, "language": "pl", "copy": { "title": "string", "text": "string", "buttonText": "string", "imageUrl": "string", "imageWidth": 0, "imageHeight": 0 }, "content": { "kind": "form", "formId": "string", "successTitle": "string", "successText": "string", "redirectPageId": "string" }, "design": { "layout": "modal", "imagePosition": "top", "accentColor": "string" }, "trigger": { "desktop": { "kind": "entry", "delaySeconds": 0 }, "mobile": { "kind": "entry", "delaySeconds": 0 } }, "targeting": { "surfaces": [ "pages" ], "pages": { "mode": "all", "pageIds": [ "string" ] }, "device": "all", "audience": "all", "hideForSubscribers": true }, "frequency": { "kind": "once", "days": 0 }, "schedule": { "startsAt": "string", "endsAt": "string" }, "createdAt": "string", "updatedAt": "string"}{ "error": "string", "message": "string"}Was this article helpful?