API Reference

Forms

Read your signup forms and draft them: where each form stands, its draft, what Publish would still refuse, and its numbers. A draft takes no signups. A person publishes a form in PristineSend, and every version is checked before it goes live, so nothing here can put a page in front of visitors.

Overview

MethodPathDescription
GET/api/v1/formsEvery form of the account, newest first.
GET/api/v1/forms/{id}One form: its draft, what Publish would still refuse, its numbers and what its draft may name.
POST/api/v1/formsA new form, as a draft.
PATCH/api/v1/forms/{id}A change to a form's draft, at the draft_updated_at you read.

Reading needs the forms:read scope (“Read forms”), which new AI connections get. Creating and changing need forms:write (“Edit form drafts”), which is never part of the default access for new agents: tick it in Settings → Developer. A test key may write drafts too: a draft sends nothing.

List forms

GET/api/v1/forms

Every form of the account, newest first. An account keeps at most 50, so the list is whole: no cursor. Each form carries the fields below that do not need its draft, and confirmed_last_30_days.

Get a form

GET/api/v1/forms/{id}
FieldTypeDescription
statusstringdraft (never live), live (its page takes signups, unless paused) or unpublished (taken down).
in_reviewbooleanA version a person published is being checked before it goes live.
pausedstring | nullbreaker (too many bounces or complaints on its confirmations) or operator (paused by us); null when not paused.
urlstring | nullThe page on pristinesend.page; null while your account has no page address, which comes with a verified domain. It takes signups only while the form is live.
draft_updated_atstringGive it back, exactly as you read it, to change the draft.
app_urlstringThe form in PristineSend, where a person publishes it.
confirmed_last_30_daysnumber | nullIn the list: confirmed signups in the last 30 UTC days; null for a form never live.
draftobjectThe draft as the editor holds it (below). What is live is the version a person last published, which may differ.
to_finisharrayWhat Publish would refuse in the draft itself, each { field, message }, in Publish's words: a missing heading or button, a birthday with no date property, a question with no words, a topic deleted or archived.
forms_offbooleanWe turned your account's forms off: Publish is refused and no form takes signups.
numbersobject | nullGET /forms/{id} only: the last 30 UTC days once the form has been live (views, signups, confirmation emails sent, confirmed, not sent and why, bounced, marked as spam, the confirm rate and the top sources); null for a form never live.
choicesobjectWhat your drafts may name: topics (id, name, archived), date_properties and text_properties (key, name).

Create a form

POST/api/v1/forms

A name and, if you like, its slug (the last part of its address; one the name suggests when left out), its language (one of en, de, es, fr, pt, sv, da, nb and fi, for our words on the page, the confirm page and the confirmation email) and any of the draft's fields. Everything is checked as Save checks it in the editor before the form is made, so a refused create makes nothing. Send an Idempotency-Key so a retry cannot make a second form; the SDK sends one for you.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

const { data: form, link_notes } = await ps.forms.create({
  name: "Newsletter",
  language: "de",
  heading: "Unser Newsletter",
  fields: { first_name: true },
})
// form.to_finish lists what Publish would still refuse.
// Send the person to form.app_url to check it and press Publish.

link_notes names any link kept without being opened (its site did not answer just now): it is opened again before the form goes live.

Change a draft

PATCH/api/v1/forms/{id}

The draft_updated_at you read, and only what changes: fields is merged key by key, a list or the picture is replaced whole, and a link given as null or empty is taken off. A draft saved since you read it is refused with 409, never overwritten. A new language changes our default heading, button and thank-you words while they are still ours, as the editor does, unless you give them. The answer is the form as saved.

curl -X PATCH "https://pristinesend.com/api/v1/forms/<id>" \
  -H "Authorization: Bearer ps_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"draft_updated_at":"2026-11-06T10:00:00.123456+00:00","topic_ids":["2b9f…"],"fields":{"last_name":true}}'

The draft's fields

FieldTypeDescription
headingstringUp to 120 characters. Publish needs one.
introstringUp to 600 characters under the heading; line breaks kept, at most one blank line in a row.
buttonstringThe submit button's words, up to 40 characters. Publish needs them.
thank_youstringUp to 400 characters, shown under “You're subscribed” once someone confirms.
fieldsobjectfirst_name, last_name and birthday, each true or false: what else the form asks. The email address is always asked. A change merges these key by key.
birthday_propertystring | nullThe date property a birthday is saved in, from choices.date_properties. Publish needs one when the birthday is asked.
questionsarrayUp to 5 questions of your own, each { property, label, required }: its answer is saved in a text property from choices.text_properties, its label up to 60 characters.
topic_idsarrayUp to 10 topics the form offers, in order, from choices.topics.
tagsarrayUp to 10 tags, each up to 50 characters, given to everyone who confirms.
pictureobject | null{ image_id, alt }: a picture from your library above the heading (an id from GET /design-kit, or from POST /pictures), and its words for a screen reader, up to 160 characters. Null for none.
continue_url / privacy_url / legal_urlstring | nullContinue after confirming, the privacy link and the Legal notice (an Impressum): https pages on one of your verified domains, opened when they change. Null or empty for none.
powered_byboolean“Powered by PristineSend” under the form. It can be turned off from the Growth plan up; on Starter it shows whatever this says.

A field the endpoint does not take is refused, never ignored. Text is kept as a visitor sees it: characters that draw nothing are removed and one-line fields lose their line breaks.

Errors

StatuscodeWhen
400missing_fieldA create with no name, or a change with no draft_updated_at.
400invalid_fieldA field the endpoint does not take, a value of the wrong kind or over its limit, a topic or property your account does not have, a picture not in your library, a link off your verified domains or one that does not open, or an address that is not allowed (param names the field).
400invalid_requestA body that is not a JSON object, or a change that names nothing besides draft_updated_at.
403insufficient_scopeThe key lacks forms:read (reading) or forms:write (creating and changing).
404not_foundNo form with this id in your account, or forms are not available on your account yet.
409conflictThe draft was saved after the draft_updated_at you gave (read it again and redo your change), the address is another form's or was retired, it cannot change because the form has been live or a version is in review, or your account already has 50 forms.
429rate_limitedYour account saved 60 drafts, templates and forms this minute. Retry-After says when to try again.
503service_unavailableA read or a write behind the request failed: send the same request again.

See Error codes for the envelope and the full list.