Poper API: Projects, campaigns, leads, and analytics

Poper's Public API lets you fetch account data that is useful for reporting, automation, AI assistants, and internal dashboards.

This guide covers the API endpoints for projects, domains, campaigns, leads, and analytics.

Base URL

https://api.poper.ai/general/v1

All endpoints in this guide use POST.

Requests can be sent as application/json or application/x-www-form-urlencoded.

Authentication

Include your Poper API key in the request body as api_key.

Example:

curl -X POST "https://api.poper.ai/general/v1/projects/list" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_POPER_API_KEY"}'

Treat your API key like a password. Do not expose it in frontend code or public repositories.

Projects and domains

List projects

POST /projects/list

Returns every project available to the API key owner. Each project includes its related domains, and the response also includes a flat domains array.

Required body fields:

Field	Type	Description
`api_key`	string	Your Poper API key

Example request:

curl -X POST "https://api.poper.ai/general/v1/projects/list" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_POPER_API_KEY"}'

Example response shape:

{
  "projects": [
    {
      "id": 123,
      "name": "Main Project",
      "domains": []
    }
  ],
  "domains": []
}

List domains

POST /domains/list

This is an alias of /projects/list. Use it when you mainly need the flat domain list.

Required body fields:

Field	Type	Description
`api_key`	string	Your Poper API key

Campaigns

List all campaigns or filter by category

POST /campaigns/list

Returns campaigns owned by the API key owner. You can fetch all campaigns or filter by campaign category, project, domain, type, or limit.

Required body fields:

Field	Type	Description
`api_key`	string	Your Poper API key

Optional body fields:

Field	Type	Description
`category`	string	`all`, `popups`, `widgets`, `games`, `forms`, `quizzes`, or `surveys`
`types`	string	Comma-separated campaign type values. Overrides `category` when provided
`project_id`	integer	Return campaigns from a specific project
`domain`	string	Return campaigns for a specific domain
`include_null_domain`	boolean	Include campaigns that are not attached to a domain
`limit`	integer	Maximum number of campaigns to return

Example request:

curl -X POST "https://api.poper.ai/general/v1/campaigns/list" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key":"YOUR_POPER_API_KEY",
    "category":"forms",
    "domain":"example.com",
    "limit":50
  }'

Example response shape:

{
  "campaigns": [],
  "popups": [],
  "count": 0,
  "byType": {},
  "supportedTypes": ["popup", "widget", "embed", "video", "game", "form", "quiz", "nps"]
}

If quiz campaigns are returned, the response may also include quizStats.

Campaign category mapping:

Category	Campaign types
`popups`	`popup`
`widgets`	`widget`, `embed`, `video`, and `widgetv2:*` types
`games`	`game`
`forms`	`form`
`quizzes`	`quiz`
`surveys`	`nps`

Dedicated campaign list endpoints

These endpoints are shortcuts for common campaign categories:

Endpoint	Description
`POST /popups/list`	List popup campaigns
`POST /forms/list`	List form campaigns
`POST /quizzes/list`	List quiz campaigns
`POST /surveys/list`	List NPS survey campaigns

Each shortcut accepts:

Field	Type	Description
`api_key`	string	Your Poper API key
`project_id`	integer	Optional project filter
`domain`	string	Optional domain filter
`limit`	integer	Optional result limit

Example:

curl -X POST "https://api.poper.ai/general/v1/forms/list" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_POPER_API_KEY","domain":"example.com"}'

For widgets and games, use /campaigns/list with category=widgets or category=games.

Leads and responses

List leads

POST /leads/list

Fetches campaign leads and responses.

You can either provide one or more campaign IDs directly, or omit campaign IDs and select campaigns using filters like category, project_id, and domain.

Required body fields:

Field	Type	Description
`api_key`	string	Your Poper API key

Optional body fields:

Field	Type	Description
`popup_id`	string	Single campaign ID or comma-separated campaign IDs
`popup_ids`	string	Alias for `popup_id`
`category`	string	`all`, `popups`, `widgets`, `games`, `forms`, `quizzes`, or `surveys`
`project_id`	integer	Select campaigns from a project
`domain`	string	Select campaigns from a domain
`page`	integer	Page number. Defaults to `1`
`per_page`	integer	Page size. Defaults to `100`
`view_responses_option`	string	`completed`, `pending`, or `all`. Defaults to `completed`
`days`	integer	Optional lookback window

Example using campaign IDs:

curl -X POST "https://api.poper.ai/general/v1/leads/list" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key":"YOUR_POPER_API_KEY",
    "popup_id":"123,456",
    "page":1,
    "per_page":100,
    "view_responses_option":"completed"
  }'

Example using filters:

curl -X POST "https://api.poper.ai/general/v1/leads/list" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key":"YOUR_POPER_API_KEY",
    "category":"forms",
    "domain":"example.com"
  }'

Example response shape:

{
  "popupIDs": [123, 456],
  "totalCount": 10,
  "responses": []
}

Analytics

Get domain analytics

POST /analytics/overview

Returns aggregate analytics for a domain using the same aggregation data as the Poper analytics dashboard.

Required body fields:

Field	Type	Description
`api_key`	string	Your Poper API key
`domain`	string	Domain to fetch analytics for

Optional body fields:

Field	Type	Description
`date`	string	`today`, `last-7-days`, `last-30-days`, `last-90-days`, or `custom`. Defaults to `last-30-days`
`custom_start`	string	Start date for `custom` range
`custom_end`	string	End date for `custom` range
`report_mode`	string	Optional report mode

Example:

curl -X POST "https://api.poper.ai/general/v1/analytics/overview" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key":"YOUR_POPER_API_KEY",
    "domain":"example.com",
    "date":"last-30-days"
  }'

Example response shape:

{
  "analytics": {}
}

Get campaign analytics

POST /analytics/campaigns

Returns aggregate analytics for one or more campaigns on a domain.

Required body fields:

Field	Type	Description
`api_key`	string	Your Poper API key
`domain`	string	Domain to fetch analytics for
`popup_ids`	string	Single campaign ID or comma-separated campaign IDs

Optional body fields:

Field	Type	Description
`date`	string	`today`, `last-7-days`, `last-30-days`, `last-90-days`, or `custom`. Defaults to `last-30-days`
`custom_start`	string	Start date for `custom` range
`custom_end`	string	End date for `custom` range
`report_mode`	string	Optional report mode

Example:

curl -X POST "https://api.poper.ai/general/v1/analytics/campaigns" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key":"YOUR_POPER_API_KEY",
    "domain":"example.com",
    "popup_ids":"123,456",
    "date":"last-7-days"
  }'

Example response shape:

{
  "analytics": {}
}

Error responses

If a required field is missing or invalid, the API returns a 400 response.

Examples:

{"error":"Domain is required"}

{"error":"popup_ids is required"}

{"error":"Invalid date range"}

Notes

All campaign-related IDs use the campaign or popup ID field returned by campaign list endpoints.
popup_id, popup_ids, and popupIDs are accepted in places that need campaign IDs.
project_id and projectID are accepted when filtering campaigns by project.
per_page and perPage are accepted for lead pagination.
report_mode and reportMode are accepted for analytics.