API Reference

Create Campaign

post
https://api.joinpopp.com/v1/campaigns

Creates a campaign in Popp application.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Create Campaign Request

Request to create a new campaign

string
enum
required

The type of campaign to create

Allowed:
string
enum
required

How the campaign conversation should be closed. Defaults to CALENDAR_MEETING_INTEGRATION for SCHEDULING campaigns. CUSTOM requires customMessage; CALENDAR_MEETING_INTEGRATION requires calendarMeetingTemplateId.

Allowed:
string
enum
required

Communication channel used for the campaign

Allowed:
boolean

Controls falling back to email when an SMS or WhatsApp message cannot be delivered (invalid or missing phone number). When omitted, the campaign inherits the organization-level email fallback setting, including future changes to it. An explicit value overrides the organization setting in either direction: true enables fallback for this campaign even if the organization has it disabled, false disables it even if the organization has it enabled. Not applicable to EMAIL channel campaigns.

string
required

Title of the campaign

string
required

Detailed description of the campaign

string
required

Message sent when the candidate is not interested.

string
required

Message sent when a candidate is rejected (fails mandatory/knockout questions).

string

Message sent to the candidate when they successfully complete the conversation. Required when closingMethod is CUSTOM.

string

Company name for the role.

string

Location of the role.

string

Contract type for the role (e.g. Permanent, Contract, Temporary). Only used for APPLICANT_OUTREACH and NEW_CANDIDATE_OUTREACH campaigns. When provided, it overrides the contract type Popp would otherwise infer from campaignDescription.

questions
array of objects
length ≥ 1

List of screening questions included in the campaign. Not allowed for SCHEDULING campaigns.

questions
string

Additional context or instructions for the AI agent (minimum 10 characters)

integer
≥ 24

Timeout for conversations in hours (minimum 24 hours). Defaults to 48 hours.

string

Email address of the campaign owner. Must be a user in the organization.

string
enum
Defaults to LIVE

Status of the campaign. DRAFT creates the campaign without sending. Defaults to LIVE.

Allowed:
uuid

ID of the opening message template. Must match the specified channel and campaignType. Mutually exclusive with customTemplatedMessage.

string

Custom opening message template text (minimum 10 characters). SMS and Email channels only. Mutually exclusive with openingMessageTemplateId. Must contain the word STOP (uppercase) for opt-out compliance. Supports {{SCREAMING_SNAKE_CASE}} placeholders, filled in per candidate; which ones are available depends on campaignType, so see "Personalising the Opening Message" in the Campaigns guide for the table. {{CANDIDATE_FIRST_NAME}}, {{CANDIDATE_LAST_NAME}}, {{AGENT_NAME}} and {{ORGANIZATION_NAME}} work on every campaign type; SCHEDULING campaigns must also include {{MEETING_URL}}. An unrecognised name returns 400 "Unknown placeholder found"; a valid name that campaignType cannot fill returns 400 "Missing value for template variable".

string
length ≤ 200

Subject line for Email campaigns using customTemplatedMessage. Required when using customTemplatedMessage with Email channel. Maximum 200 characters. Takes the same placeholder names as customTemplatedMessage; an unrecognised name returns 400 "Invalid placeholder in subject line". Note that only the name is validated here, not whether campaignType can fill it.

string
required

AI agent name (case-insensitive, Unicode letters only, maximum 3 words). There is no agentId field — an agent cannot be referenced by ID; supply agentName together with agentTone instead. If the pair does not match your organization's default agent, a new agent is created with this name and tone.

string
enum
required

Tone used by the AI agent. Must be provided together with agentName.

Allowed:
string

Your unique identifier for the campaign in your external system.

uuid

ID of the calendar meeting template. Used when closingMethod is CALENDAR_MEETING_INTEGRATION.

boolean
Defaults to false

When true, automatic follow-up messages (nudges) will be disabled for all conversations in this campaign. Defaults to false. Cannot be used together with a non-empty nudgeSettings array.

nudgeSettings
array of objects | null

Custom nudge timing configuration. Each entry represents one follow-up nudge with a delayHours field specifying the wait time since the previous message. The array length determines the total number of nudges. An empty array disables nudging. A non-empty array cannot be used together with disableNudging: true. When omitted, defaults to 3 nudges at 24-hour intervals. Note: for WhatsApp campaigns, nudges are only sent after the candidate replies.

nudgeSettings
string
enum
Defaults to en_us

Language the campaign operates in: en_ca (Canadian English), en_gb (British English), en_us (American English), de (German), es (Spanish), fr (French), it (Italian), nl (Dutch), nl_be (Flemish), pt (Portuguese), pt_br (Brazilian Portuguese), zh_hk (Chinese), ar (Arabic), ja (Japanese), ko (Korean), ru (Russian), pl (Polish), tr (Turkish), hu (Hungarian), sv (Swedish), no (Norwegian), da (Danish). When omitted, it is derived from the language of openingMessageTemplateId, then from the organization's language when it supports only one, and finally defaults to en_us. WHATSAPP campaigns are rejected with a 400 when the language has no approved WhatsApp templates for the organization, because WhatsApp follow-up messages require a pre-approved template in the campaign language; set disableNudging to true to opt out of follow-ups and skip that check.

Responses

Updated 5 months ago

Did this page help you?
Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 5 months ago

Did this page help you?