Skip to content
POLST Developer Docs

Create a new campaign owned by the authenticated brand.

POST
/brands/me/campaigns

Creates a campaign with an ordered polstIds[] list. Every polstId MUST be owned by the caller’s brand and not archived/deleted; otherwise 400 INVALID_POLST_OWNERSHIP with details.foreignPolstIds.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-Polst-Idempotency-Key
required
string
>= 8 characters <= 255 characters

Idempotency key, 8–255 URL-safe chars.

Request Body required

Section titled “Request Body required ”
object
name
required
string
>= 1 characters <= 255 characters
isPublic
boolean
endsAt
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
polstIds
required
Array<string>
>= 1 items <= 100 items

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Campaign created.

object
data
required
object
campaignId
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
title
required
string
>= 1 characters
description
required
Any of:
string
polsts
required
Array<object>
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
slug
required
string
>= 1 characters
title
required
string
>= 1 characters
optionA
required
object
label
required
Any of:
string
imageUrl
required
Any of:
string
imageVariants
required
Array<object>
object
url
required
string
width
required
integer
> 0 <= 9007199254740991
optionB
required
object
label
required
Any of:
string
imageUrl
required
Any of:
string
imageVariants
required
Array<object>
object
url
required
string
width
required
integer
> 0 <= 9007199254740991
images
required
object
combined
required
Any of:
string
large
required
Any of:
string
medium
required
Any of:
string
small
required
Any of:
string
social
required
Any of:
string
imageVariants
required
Array<object>
object
url
required
string
width
required
integer
> 0 <= 9007199254740991
placeholder
required
Any of:
string
tallies
required
object
optionA
required
integer
<= 9007199254740991
optionB
required
integer
<= 9007199254740991
total
required
integer
<= 9007199254740991
status
required
string
Allowed values: scheduled open closed
startsAt
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
endsAt
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
brand
required
Any of:
object
slug
required
string
>= 1 characters
name
required
string
>= 1 characters
theme
required
object
accent
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
background
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
foreground
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
radius
required
string
Allowed values: NONE SM MD LG FULL
density
required
string
Allowed values: COMPACT COMFORTABLE
fontStack
required
string
Allowed values: SYSTEM SERIF MONO BRAND
fontBrandUrl
required
Any of:
string
<= 2048 characters
logoLightUrl
required
Any of:
string
<= 2048 characters
logoDarkUrl
required
Any of:
string
<= 2048 characters
faviconUrl
required
Any of:
string
<= 2048 characters
hideWatermark
required
boolean
customCss
required
Any of:
string
<= 4096 characters
version
required
integer
<= 9007199254740991
titleColor
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
titleSize
required
Any of:
integer
>= 10 <= 96
titleWeight
required
Any of:
integer
>= 100 <= 900
titlePlacement
required
string
Allowed values: ABOVE BELOW HIDDEN
labelColor
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
labelSize
required
Any of:
integer
>= 10 <= 72
labelPlacement
required
string
Allowed values: HEADER OVERLAID BELOW HIDDEN
labelAlign
required
string
Allowed values: LEFT CENTER
headerFill
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
orBadgeBg
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
orBadgeFg
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
orBadgeDiameter
required
Any of:
integer
>= 24 <= 96
imageRatio
required
Any of:
number
>= 0.25 <= 4
elevation
required
string
Allowed values: FLAT LIFTED
createdAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
userVote
required
Any of:
string
Allowed values: A B
totalSteps
required
integer
<= 9007199254740991
brand
required
object
slug
required
string
>= 1 characters
name
required
string
>= 1 characters
theme
required
object
accent
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
background
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
foreground
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
radius
required
string
Allowed values: NONE SM MD LG FULL
density
required
string
Allowed values: COMPACT COMFORTABLE
fontStack
required
string
Allowed values: SYSTEM SERIF MONO BRAND
fontBrandUrl
required
Any of:
string
<= 2048 characters
logoLightUrl
required
Any of:
string
<= 2048 characters
logoDarkUrl
required
Any of:
string
<= 2048 characters
faviconUrl
required
Any of:
string
<= 2048 characters
hideWatermark
required
boolean
customCss
required
Any of:
string
<= 4096 characters
version
required
integer
<= 9007199254740991
titleColor
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
titleSize
required
Any of:
integer
>= 10 <= 96
titleWeight
required
Any of:
integer
>= 100 <= 900
titlePlacement
required
string
Allowed values: ABOVE BELOW HIDDEN
labelColor
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
labelSize
required
Any of:
integer
>= 10 <= 72
labelPlacement
required
string
Allowed values: HEADER OVERLAID BELOW HIDDEN
labelAlign
required
string
Allowed values: LEFT CENTER
headerFill
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
orBadgeBg
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
orBadgeFg
required
Any of:
string
/^#([0-9a-f]{6}|[0-9a-f]{8})$/
orBadgeDiameter
required
Any of:
integer
>= 24 <= 96
imageRatio
required
Any of:
number
>= 0.25 <= 4
elevation
required
string
Allowed values: FLAT LIFTED
status
required
string
Allowed values: scheduled open closed
startsAt
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
endsAt
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
state
required
string
Allowed values: active ended
isPublic
required
boolean
polstCount
required
integer
<= 9007199254740991
createdAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
updatedAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

400

Section titled “400 ”

INVALID_POLST_OWNERSHIP or missing idempotency key.

401

Section titled “401 ”

Missing or invalid bearer token.

403

Section titled “403 ”

Bearer token lacks manage scope or has no brand context.

409

Section titled “409 ”

A campaign with this name already exists for the brand.

422

Section titled “422 ”

Request body failed validation.