openapi: 3.2.0 info: title: SendPulse Pop-up Popup API description: API for managing pop-ups in SendPulse. This API allows you to create, update, and delete pop-ups, as well as retrieve information about them and their performance. version: '1.0' servers: - description: Production server url: https://api.sendpulse.com/v2/pop-ups security: - apiKey: [] - oauth2: [] tags: - name: Popup paths: /public/api/popups/conditions: get: tags: - Popup summary: Get a list of available display conditions for popups description: Returns a list of available display conditions for popups with detailed information responses: '200': description: Operation successful content: application/json: schema: properties: result: type: boolean data: description: List of available display conditions type: array items: $ref: '#/components/schemas/scenarioSetting' pageInfo: $ref: '#/components/schemas/pageInfo' type: object operationId: getPopupConditions x-ai-role: conversion_optimization_specialist x-ai-description: Returns the full catalog of display conditions available for popup targeting rules. Display conditions are the fundamental building blocks of popup triggers — they define WHEN and FOR WHOM a popup appears (e.g., time on page, scroll depth, exit intent, URL match, device type). Knowing available conditions is a prerequisite before constructing or modifying any popup scenario. x-ai-reasoning-instructions: - Always fetch this list before building or explaining popup targeting scenarios — available conditions may vary by account tier or platform version. - Use this endpoint to validate user-specified condition types before applying them to a popup. - If the user asks 'how can I show a popup only to mobile users?' or similar questions, map their intent to specific condition entries from this list. - Correlate condition identifiers from this response with the `scenarioSetting` schema when constructing popup display rules. x-ai-responding-instructions: - Group conditions by logical category (e.g., behavioral, geographic, device, traffic source) if the data supports it — this helps the user pick the right condition faster. - If the user is new to popups, explain that conditions combine into targeting rules that control popup visibility. - Highlight any conditions relevant to the user's stated goal (e.g., exit intent for cart abandonment, scroll depth for content engagement). x-ai-suggestions: - After retrieving conditions, use the relevant condition IDs to configure a popup scenario via the popup update or create endpoint. - Combine multiple conditions with AND/OR logic to build precise audience targeting. - Check `pageInfo` to determine if pagination is needed for accounts with extended condition sets. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly /public/api/popups/list/quiz/{projectId}: get: tags: - Popup summary: Get a list of quiz pop-ups by your project ID description: Returns a list of quiz pop-ups using your project ID with information about each pop-up parameters: - name: projectId in: path description: Project ID schema: type: string format: uuid required: true - name: first in: query description: Limit on the number of displayed records. The default number is 10 schema: type: integer - name: offset in: query description: Limit on the number of displayed records schema: type: integer responses: '200': description: Operation successful content: application/json: schema: properties: result: type: boolean data: description: List of popups type: array items: $ref: '#/components/schemas/popup' pageInfo: $ref: '#/components/schemas/pageInfo' type: object '400': description: Validation error content: application/json: example: result: false errors: widgetId: Invalid id {{'7803a6ea-4b32-44d7-a245-5cda4e4f20'}} '401': $ref: '#/components/schemas/unauthorizedResponse' '403': $ref: '#/components/schemas/accessDeniedResponse' '404': description: Resource Not Found operationId: listQuizPopupsByProject x-ai-role: conversion_optimization_specialist x-ai-description: Retrieves all quiz-type pop-ups scoped to a specific project. Quiz pop-ups are interactive lead-capture tools that segment visitors based on their answers — useful for personalization pipelines, audience segmentation audits, and campaign performance reviews. Use this to inventory active quizzes before launching new ones or to sync pop-up state with external analytics. x-ai-reasoning-instructions: - Verify the projectId is a valid UUID before calling; malformed IDs return 400 with field-level errors. - Default page size is 10 — if the project is large, paginate using `first` + `offset` to avoid incomplete results. - Cross-reference returned pop-up IDs with campaign records when diagnosing conversion drop-offs. - If the response is empty, confirm the project has quiz-type widgets created — other pop-up types are returned by separate endpoints. x-ai-responding-instructions: - Report the total number of quiz pop-ups found and summarize key fields (name, status, ID) for each. - If `pageInfo` indicates more records exist, suggest repeating the call with an incremented `offset`. - On 403, clarify that the OAuth2 token may lack scope for this project — advise re-authenticating with correct client credentials. - On 404, confirm the projectId exists and belongs to the authenticated account. x-ai-suggestions: - 'Start with `first: 10, offset: 0` and iterate if `pageInfo` shows more pages.' - After listing, use individual pop-up IDs to fetch detailed statistics or update quiz content. - Filter results client-side by status field to distinguish active vs. paused quizzes. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly /public/api/popups/list/{projectId}: get: tags: - Popup summary: Get a list of pop-ups by your project ID description: Returns a list of pop-ups using your project ID with information about each pop-up parameters: - name: projectId in: path description: Project ID schema: type: string format: uuid required: true - name: first in: query description: Limit on the number of displayed records. The default number is 10 schema: type: integer - name: offset in: query description: Limit on the number of displayed records schema: type: integer responses: '200': description: Operation successful content: application/json: schema: properties: result: type: boolean data: description: List of popups type: array items: $ref: '#/components/schemas/popup' pageInfo: $ref: '#/components/schemas/pageInfo' type: object '400': description: Validation error content: application/json: example: result: false errors: widgetId: Invalid id {{'7803a6ea-4b32-44d7-a245-5cda4e4f20'}} '401': $ref: '#/components/schemas/unauthorizedResponse' '403': $ref: '#/components/schemas/accessDeniedResponse' '404': description: Resource Not Found operationId: listPopupsByProjectId x-ai-role: conversion_optimization_specialist x-ai-description: Retrieves the full inventory of pop-ups associated with a specific project. In SendPulse, a project acts as the organizational unit grouping all pop-up widgets — this endpoint is the entry point for auditing, managing, or selecting pop-ups before triggering display logic or analytics workflows. Pagination via `first`/`offset` is essential for projects with large widget libraries. x-ai-reasoning-instructions: - Confirm the projectId is a valid UUID before calling — malformed IDs return a 400 with field-level error details. - If the user wants all popups, start with the default limit (10) and check `pageInfo` to determine if additional pages exist. - When the user provides a project name instead of ID, first resolve the project UUID via the projects listing endpoint. - If the response returns an empty array, verify the projectId belongs to the authenticated account — a 404 may indicate ownership mismatch rather than an empty project. x-ai-responding-instructions: - Present the popup list with key identifiers (name, ID, status) to help the user orient quickly. - If `pageInfo` indicates more records exist, proactively suggest fetching the next page with adjusted `offset`. - On 401/403, distinguish between invalid credentials and insufficient permissions — the user may need to re-authenticate or request access to the project. - On 404, clarify that the projectId may not belong to the current account, not just that it doesn't exist. x-ai-suggestions: - Use `first=50` to retrieve a larger batch if the project is known to have many popups. - Combine with a popup details endpoint to drill into a specific widget after listing. - Iterate with `offset` increments equal to `first` to paginate through the full list. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly /public/api/popups/{popupId}/set-state: post: tags: - Popup summary: Set a pop-up state description: Enables or disables a pop-up on your website parameters: - name: popupId in: path description: Pop-up ID. It can be obtained using the "Get a list of projects" method or in the pop-up builder address bar in your account. schema: type: string format: uuid required: true requestBody: content: application/json: schema: properties: is_enabled: type: boolean description: Sets a pop-up state. If you want to enable your pop-up, pass "true", and if you want to disable it, pass "false". type: object responses: '200': description: Operation successful content: application/json: schema: properties: result: type: boolean data: $ref: '#/components/schemas/popup' type: object '400': description: Validation error content: application/json: example: result: false errors: id: Invalid id {{'af1b0e2a-bff9-4d09-a7d9-99d61d2b43b'}} isEnabled: Invalid boolean value '23' '401': $ref: '#/components/schemas/unauthorizedResponse' '404': description: Resource Not Found operationId: setPopupState x-ai-role: conversion_optimization_specialist x-ai-description: Controls the live visibility of a pop-up on the target website. Toggling a pop-up state is a high-impact, instantly effective action — enabling it starts showing the pop-up to visitors immediately, while disabling it suppresses it without deleting any configuration or accumulated statistics. Use this as the primary on/off switch for campaigns, A/B tests, or seasonal promotions. x-ai-reasoning-instructions: - Confirm the popupId exists and belongs to the user's account before toggling — an invalid UUID will produce a 400 error. - Before enabling, consider whether the pop-up is part of an active A/B test or scheduled campaign to avoid unintended conflicts. - If the user wants to temporarily pause a pop-up (e.g., during site maintenance), prefer disabling over deleting — all settings and stats are preserved. - Verify the boolean value is strictly true or false, not a string like '1' or 'yes', as the API rejects non-boolean values. x-ai-responding-instructions: - 'Confirm the new state explicitly: ''Pop-up has been enabled / disabled successfully.''' - If enabling, mention that the pop-up will now be visible to website visitors immediately. - If disabling, reassure the user that the pop-up configuration and statistics are preserved and it can be re-enabled at any time. - On a 404 error, suggest verifying the popupId via the 'Get a list of projects' endpoint. x-ai-suggestions: - 'To enable: set is_enabled to true' - 'To pause a campaign without losing data: set is_enabled to false' - Follow up with 'Get a list of projects' to verify the updated state x-ai-capabilities: confirmation: type: Recommended message: This will immediately change the pop-up visibility on the live website. Confirm the intended state (enable/disable). security_info: data_handling: - ResourceStateUpdate /public/api/popups/{popupId}: delete: tags: - Popup summary: Delete popup description: Delete popup parameters: - name: popupId in: path description: Pop-up ID. It can be obtained using the "Get a list of projects" method or in the pop-up builder address bar in your account. schema: type: string format: uuid required: true requestBody: content: application/json: schema: properties: is_enabled: type: boolean description: Delete popup". type: object responses: '200': description: Operation successful content: application/json: schema: properties: result: type: boolean type: object '400': description: Validation error content: application/json: example: result: false errors: id: Invalid id {{'af1b0e2a-bff9-4d09-a7d9-99d61d2b43b'}} isEnabled: Invalid boolean value '23' '401': $ref: '#/components/schemas/unauthorizedResponse' '403': $ref: '#/components/schemas/accessDeniedResponse' '404': description: Resource Not Found operationId: deletePopup x-ai-role: conversion_optimization_specialist x-ai-description: Permanently removes a popup from the account. This is a destructive, irreversible operation — once deleted, the popup and all associated display rules, targeting settings, and collected statistics are gone. Use this only when a popup is fully obsolete; consider disabling it first via the update endpoint if you may need to reactivate it later. x-ai-reasoning-instructions: - Before deleting, confirm the popupId belongs to the correct popup — retrieve its details first if there is any ambiguity. - 'Warn the user that deletion is permanent and cannot be undone; suggest disabling the popup (is_enabled: false) as a safer alternative if unsure.' - Check whether the popup is currently active on a live site — deleting an active popup may break embedded scripts or integrations. - If the user provides a name instead of a UUID, resolve the ID via the list endpoint before proceeding. x-ai-responding-instructions: - Confirm successful deletion by echoing the popupId that was removed. - If result is true, suggest reviewing remaining popups to ensure no related funnels are broken. - On 404, clarify that the popup may have already been deleted or the ID is incorrect. - On 400, surface the specific validation error (invalid UUID format or invalid boolean) so the user can correct the request. x-ai-suggestions: - Retrieve popup list first with `getPopupList` to confirm the correct popupId before deletion. - 'Consider using the update endpoint to set is_enabled: false instead of permanent deletion.' - After deletion, audit remaining popups to verify campaign integrity. x-ai-capabilities: confirmation: type: Required message: This action permanently deletes the popup and cannot be undone. Confirm the popupId before proceeding. security_info: data_handling: - IrreversibleDelete components: schemas: unauthorizedResponse: description: Unauthorized pageInfo: title: Page Info properties: total: type: integer description: Total number of records offset: type: integer description: Limit on the number of displayed records first: type: integer description: Record count offset arguments: type: object type: object scenarioSetting: title: Display condition properties: groupId: type: integer description: "Behavior group:\n * `1` - frequency;\n * `2` - time;\n * `3` - user behavior;\n * `4` - clicks;\n * `5` - pages and urls;\n * `6` - utm parameters;\n * `7` - visitor data.\n" dataType: type: string description: Data type name: type: string description: Condition name uniq: type: boolean description: Is unique type: object popup: title: Popup properties: id: type: string format: uuid description: Project ID widgetId: type: string format: uuid description: Pop-up ID isEnabled: type: boolean description: Sets a pop-up state. If you want to show your pop-up, pass "true", and if you want to hide it, pass "false". type: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 description: "Popup type:\n * `2` - modal window;\n * `3` - overlay;\n * `4` - floating;\n * `5` - cookie request;\n * `6` - horizontal;\n * `7` - video;\n * `8` - launcher.\n" style: type: integer enum: - 1 - 2 - 3 description: "Popup style:\n * `1` - white;\n * `2` - dark;\n * `3` - colored.\n" position: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 description: "Popup position:\n * `1` - bottom-left;\n * `2` - bottom-right;\n * `3` - automatic;\n * `4` - bottom;\n * `5` - bottom-center;\n * `6` - left;\n * `7` - right;\n * `8` - center;\n * `9` - top-left;\n * `10` - top-right;\n * `11` - top-center.\n" text: type: - string - 'null' description: Text message name: type: string description: Pop-up name color: type: - string - 'null' description: Button style color image: properties: url: type: string description: URL of your image uploaded to the SendPulse file manager position: type: integer enum: - 1 - 2 - 3 - 4 description: "Popup image position:\n * `1` - left;\n * `2` - right;\n * `3` - top;\n * `4` - background.\n" type: object video: properties: url: type: string description: URL of your video uploaded to the SendPulse file manager format: type: integer description: "Video format:\n * `1` - vertical;\n * `2` - horizontal.\n" playbackType: type: integer description: "Video playing image:\n * `1` - automatic;\n * `2` - on click.\n" type: object containsNPS: type: boolean description: Show of popup contains NPS statistic: title: Popup statistic properties: peopleReached: type: integer description: The number of times your widget was viewed engagements: type: integer description: The number of visitors who interacted with your widget, expanded it, read its message, clicked its button, and followed the link. subscriptions: type: integer description: The number of email addresses or phone numbers customers entered in the "Email Address Request" or "Phone Number Request" form. formEngagements: type: integer description: The number of leads who submitted your form wereClosed: type: integer description: The number of visitors who closed your widget (clicked the "cross" icon). type: object preview: type: string description: Preview image url abtest: title: AB test information properties: status: type: integer description: 'AB test status. Possible variants: * `0` - finished; * `1` - active. ' finishInitiator: type: integer description: 'AB test finish initiator. Possible values: * `1` - manal (by user); * `2` - auto (reached finish condition). ' finishCondition: type: array description: List of finish conditions for AB test items: properties: trigger: type: integer description: 'Trigger for AB test finish. Possible values: * `1` - by date (timestamp in value); * `2` - by views (peopleReached); * `3` - by subscriptions. ' value: type: integer description: Max value for trigger type: object winner: type: string description: Winner variant ID. Empty if test not finished yet. separatedConditions: type: boolean description: True if variants use different show conditions. statistic: properties: peopleReached: type: integer description: Total amount of views for both variants subscriptions: type: integer description: Total amount of subscriptions for both variants type: object participants: properties: A: properties: id: type: string preview: type: string description: Preview image url statistic: properties: peopleReached: type: integer description: Total amount of views subscriptions: type: integer description: Total amount of subscriptions type: object type: object B: properties: id: type: string preview: type: string description: Preview image url statistic: properties: peopleReached: type: integer description: Total amount of views subscriptions: type: integer description: Total amount of subscriptions type: object type: object type: object createdAt: type: string example: 2023-08-07 20:14:15+00:00 description: 'The date and time your AB test was created. Output in the YYYY-MM-DD hh: mm: ss format with a decimal fraction of a second and time zone designator.' type: object updatedAt: type: string example: 2023-08-07 20:14:15+00:00 description: 'The date and time your project was last updated. Output in the YYYY-MM-DD hh: mm: ss format with a decimal fraction of a second and time zone designator.' createdAt: type: string example: 2023-08-07 20:14:15+00:00 description: 'The date and time your project was created. Output in the YYYY-MM-DD hh: mm: ss format with a decimal fraction of a second and time zone designator.' type: object accessDeniedResponse: description: Access denied securitySchemes: apiKey: type: http scheme: bearer bearerFormat: API Key description: 'Static API Key authentication. A long-lived token generated manually in the SendPulse account settings. ' x-ai-description: 'Permanent authentication token. Ideal for simple integrations without token refresh logic. ' outh2: type: oauth2 description: OAuth 2.0 Client Credentials flow for temporary access tokens. flows: clientCredentials: tokenUrl: https://api.sendpulse.com/oauth/access_token scopes: {} x-ai-description: 'Standard OAuth 2.0 flow using Client ID and Client Secret. Provides temporary tokens (valid for 1 hour) for enhanced security. '