Forms API

Endpoints

Create a form

Omit fields and you get the starter form: an email field and a consent checkbox with GDPR-shaped wording already in it.

curl -X POST https://emailbump.com/api/v1/forms \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter", "lists": ["LIST_ID"] }'

New forms are created as draft. Publish when you’re ready with POST /v1/forms/{id}/publish.

Field types

email text textarea number date select checkboxes boolean consent lists hidden heading paragraph divider image spacer

There is no separate attribute registry to keep in step — the field is the declaration, and values are normalised (bool, number, date, string) before they merge into the contact’s attributes.

• consent needs text. That wording is stored with every submission and repeated in the confirmation email.
• lists renders checkboxes bound to real lists. Ticking nothing subscribes them to nothing — the choice was offered.
• hidden fills {{utm_source}}-style tokens from the page’s own URL. {{page_url}} and {{referrer}} also work.

The id never changes

A form’s id (frm_…) is immutable and is what every embed and API call names. Its slug is the vanity URL only, unique within your project. Rename a form, restyle it, point it at a different list — the id stays put, so the tag on your website never needs re-pasting. Renaming the slug changes /f/your-project/newsletter and nothing else.

Get the embed code

curl https://emailbump.com/api/v1/forms/frm_8f2c9a1b3d/embed \
  -H "Authorization: Bearer ebk_your_key"

Returns script, iframe, html, react, vue, url and permanent_url. The one most people want:

<script src="https://emailbump.com/f.js" data-form="frm_8f2c9a1b3d" async></script>

Submissions

Every submission is stored, including the ones the anti-spam checks turned away — a form quietly rejecting thousands of attempts from one network is only visible if the refusals are recorded next to the successes.

curl "https://emailbump.com/api/v1/forms/frm_8f2c9a1b3d/submissions?limit=50" \
  -H "Authorization: Bearer ebk_your_key"

Each row carries the consent snapshot, IP, referring page and location, plus a status of pending_confirmation, confirmed, accepted or rejected. Filter with ?status=.

Themes

A theme is shared styling for a project. Forms store only their own overrides, so changing a theme restyles every form on it — live, with no re-embedding.

curl -X PATCH https://emailbump.com/api/v1/form-themes/thm_yourbrand \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "tokens": { "accent": "#111827", "radius": 8, "font": "system" } }'

Themes are scoped to a project, like contacts, lists and templates. To reuse a brand elsewhere, copy it — the copy is an independent snapshot that drifts freely from the original. Copying names two projects, so it takes an account-scoped key; the destination may be in any workspace you’re a member of.