Website pop-up creation and management, project organisation, and delivery and conversion statistics.
components:
schemas:
project:
title: Project
properties:
id:
type: string
format: uuid
description: Project ID
name:
type: string
description: Project name
urls:
type: array
items:
type: string
format: uri
description: Project website URL
domains:
type: array
items:
type: string
format: hostname
description: Project site domains
integrationCode:
type: string
description: Code that allows you to install a project on your website
updatedAt:
type: string
example: 2023-08-07T20:14:15.000Z
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-07T20:14:15.000Z
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
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:
* `2` - modal window;
* `3` - overlay;
* `4` - floating;
* `5` - cookie request;
* `6` - horizontal;
* `7` - video;
* `8` - launcher.
style:
type: integer
enum:
- 1
- 2
- 3
description: |
Popup style:
* `1` - white;
* `2` - dark;
* `3` - colored.
position:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
description: |
Popup position:
* `1` - bottom-left;
* `2` - bottom-right;
* `3` - automatic;
* `4` - bottom;
* `5` - bottom-center;
* `6` - left;
* `7` - right;
* `8` - center;
* `9` - top-left;
* `10` - top-right;
* `11` - top-center.
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:
* `1` - left;
* `2` - right;
* `3` - top;
* `4` - background.
type: object
video:
properties:
url:
type: string
description: URL of your video uploaded to the SendPulse file manager
format:
type: integer
description: |
Video format:
* `1` - vertical;
* `2` - horizontal.
playbackType:
type: integer
description: |
Video playing image:
* `1` - automatic;
* `2` - on click.
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-07T20:14:15.000Z
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-07T20:14:15.000Z
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-07T20:14:15.000Z
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
popupStatistic:
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
NPSStatistic:
title: NPS variant statistic
properties:
button:
title: NPS button base information
properties:
id:
type: string
format: UUID
description: Uniq ID
caption:
type: string
contactVariableName:
type: string
description: Variable name from CRM
variants:
type: array
items:
properties:
title:
type: string
description: Variant display name
option:
type: string
description: Variant value
type: object
variantsCount:
type: integer
description: Total amount of variants
displayType:
type: integer
description: NPS variants display type
type: object
date:
type: string
option:
type: string
description: Variant value
total:
type: integer
description: Total amount of voices for this variant
type: object
aggregatedNPSStatistic:
title: Aggregated NPS statistic
properties:
average:
type: integer
description: NPS score
total:
type: integer
description: Total number of results
promoter:
type: integer
description: Total promoters
neutral:
type: integer
description: Total neutral
critic:
type: integer
description: Total critic
promoterPercent:
type: integer
description: Percent of promoters
neutralPercent:
type: integer
description: Percent of neutrals
criticPercent:
type: integer
description: Percent of critics
type: object
projectStatistic:
title: Project 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).
widget:
type: integer
description: The number of visitors who use widget buttons.
type: object
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:
* `1` - frequency;
* `2` - time;
* `3` - user behavior;
* `4` - clicks;
* `5` - pages and urls;
* `6` - utm parameters;
* `7` - visitor data.
dataType:
type: string
description: Data type
name:
type: string
description: Condition name
uniq:
type: boolean
description: Is unique
type: object
userPlanInfo:
title: Tariff info
properties:
expiredAt:
type: string
description: Expiring date
daysAmount:
type: integer
description: Tariff length in days
currentDaysAmount:
type: integer
description: Used days for this moment
daysLeft:
type: integer
description: Days left
nextLimitsDrop:
type: string
description: Date for monthly limits drop
options:
type: object
properties:
views:
type: object
properties:
amount:
type: integer
description: Total available amount
amountLeft:
type: integer
description: Left amount
currentAmount:
type: integer
description: Used amount
description: Tariff limits info
type: object
subscriber:
title: Subscriber
properties:
id:
type: integer
description: Subscriber id
clientId:
type: string
description: Id formed in browser
name:
type:
- string
- 'null'
projectId:
type: string
popupId:
type: string
gender:
type: integer
description: |
Available values:
* `0` - unknown;
* `1` - male;
* `2` - female.
email:
type:
- string
- 'null'
city:
type:
- string
- 'null'
phone:
type:
- string
- 'null'
createdAt:
type: string
updatedAt:
type: string
type: object
unauthorizedResponse:
description: Unauthorized
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.
info:
title: SendPulse Pop-up 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'
openapi: 3.1.2
paths:
/public/api/widgets/list:
get:
tags:
- Project
summary: Get a list of projects
description: Returns a list of projects with information about each project
parameters:
- 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 projects
type: array
items:
$ref: '#/components/schemas/project'
pageInfo:
$ref: '#/components/schemas/pageInfo'
type: object
'400':
description: Validation error
'401':
$ref: '#/components/schemas/unauthorizedResponse'
'404':
description: Resource Not Found
operationId: listWidgets
x-ai-role: project_manager
x-ai-description: >-
Returns a paginated catalog of widgets (projects) available in the
account. Widgets are the core structural units in SendPulse's project
layer — each represents a configurable component tied to a campaign or
automation flow. Use this endpoint to discover existing projects before
creating or modifying them.
x-ai-reasoning-instructions:
- >-
If the user hasn't specified pagination params, default to first=10
and offset=0.
- >-
If the result set looks incomplete, suggest increasing 'first' or
paginating using 'offset' + 'pageInfo'.
- >-
Check pageInfo.hasNextPage (or equivalent) to determine if more
records exist beyond the current page.
x-ai-responding-instructions:
- >-
Summarize how many projects were returned and whether more pages are
available.
- If the list is empty, suggest the user create a new project first.
- >-
If the user is looking for a specific project, suggest filtering by
name on the client side or refining the query.
x-ai-suggestions:
- >-
Use offset-based pagination to iterate through all projects: increment
offset by the value of 'first' on each call.
- >-
Combine with a project-detail endpoint to fetch full configuration for
a specific widget.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/public/api/widgets:
post:
tags:
- Project
summary: Create a project
description: >-
Creates a new project with the specified properties and returns a copy
of the information with the project ID
requestBody:
content:
application/json:
schema:
properties:
name:
type: string
description: Project name
url:
type: string
description: Project website URL
type: object
responses:
'201':
description: Operation successful
content:
application/json:
schema:
properties:
result:
type: boolean
data:
$ref: '#/components/schemas/project'
type: object
'400':
description: Validation error
content:
application/json:
example:
result: false
errors:
name.length.max: Too long, max length - {{255}}
url: Invalid URL 'bad_url'
'401':
$ref: '#/components/schemas/unauthorizedResponse'
'404':
description: Resource Not Found
operationId: createWidget
x-ai-role: popup_campaign_manager
x-ai-description: >-
Initializes a new popup/widget project — the root container for all
popup campaigns within SendPulse. A 'project' here groups widgets by
website or product area, binding them to a specific URL for targeting
and analytics. Creating a project is the mandatory first step before any
popup can be designed, published, or tracked.
x-ai-reasoning-instructions:
- >-
Check whether a project with the same name or URL already exists
before creating a new one to avoid duplication.
- >-
Validate that the `url` is a well-formed absolute URL (e.g.,
https://example.com); relative paths and bare domains will be
rejected.
- >-
Ask the user to confirm the target website URL — it determines which
domain popups will be scoped to.
- >-
If `name` is not provided, suggest deriving it from the domain part of
the URL for clarity.
x-ai-responding-instructions:
- >-
Confirm successful creation by surfacing the new project ID from the
`data` object.
- >-
Remind the user that the next step is creating individual widgets
(popups) within this project.
- >-
On a 400 error, parse the `errors` object and explain each field-level
constraint violation in plain language.
- >-
On a 401, inform the user that OAuth2 client credentials are required
and guide them through obtaining a token.
x-ai-suggestions:
- Main Website — https://mycompany.com
- Blog — https://blog.mycompany.com
- Landing Page Q2 — https://promo.mycompany.com/q2
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
/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: fal
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-popups-openapi.yml