Skip to main content
POST
Create a survey draft

Authorizations

Authorization
string
header
required

An API key (utk_live_...) or an app's OAuth access token (uto_...).

Headers

Idempotency-Key
string

Any 1 to 255 printable ASCII characters, without a space at either end. The answer to the first request with a key is kept for 24 hours per credential: the same request again gets it back (Idempotent-Replayed: true), another request with the key is 409 PUB-002-002, and while the first still runs 409 PUB-002-003. A server error is not kept, and a request that never answered frees its key after 2 minutes: a retry with the key then runs again.

Maximum string length: 255

Body

application/json

Any other field is 400 PUB-008-001.

name
string
required
Required string length: 1 - 255
channel
enum<string>

website (default) or link; email is 400 PUB-008-009.

Available options:
website,
link
defaultLanguage
string

A language the organization offers (default en).

Example:

"en"

languages
string[]

Every language the survey is written in, within the plan; the default language is always one.

displayMode
enum<string>

steps (default), all or chat.

Available options:
steps,
all,
chat
position
enum<string>
Available options:
bottom-right,
bottom-left,
top-right,
top-left,
center-modal
texts
object

The widget's words by key (title, subtitle, submitButton, prevButton, nextButton, startButton, closeButton, successTitle, successMessage, errorMessage, requiredField, redirectNote, minimizedText, launcherLabel); null removes one.

siteId
string<uuid>

website: the site to run on (GET /sites); without it, the oldest site.

targeting
object

The targeting every plan runs. Only the parts sent change; any other field is 400 PUB-008-001.

questions
object[]
Maximum array length: 200

Response

Created.

id
string<uuid>
required
name
string
required
status
enum<string>
required
Available options:
draft,
active,
paused,
archived
channel
enum<string>
required
Available options:
website,
link,
email
site
object | null
required
draftVersion
integer
required

Send it back as expectedDraftVersion.

editable
boolean
required

True only for a survey in draft status: the API edits nothing else.

editorUrl
string<uri>
required

The survey in the Usertick editor, where a person publishes it. Give it to the person.

defaultLanguage
string
required
languages
string[]
required
displayMode
enum<string>
required
Available options:
steps,
all,
chat
position
string
required
texts
object
required
targeting
object
required
questions
object[]
required
publishChecks
object[]
required

What publishing would refuse now: a report for the person who publishes. Nothing here blocks saving a draft.

createdAt
string<date-time>
required
Example:

"2026-09-30T10:00:00.000Z"

updatedAt
string<date-time>
required
Example:

"2026-09-30T10:00:00.000Z"

aiGenerated
boolean
required

True when Usertick AI wrote text in the survey's own fields; each question has its own. Read only.

aiGeneratedAt
string<date-time> | null
required

When text Usertick AI wrote was first stored here; null when people wrote all of it.

Example:

"2026-09-30T10:00:00.000Z"

Last modified on November 8, 2026