Forms

Marketing / lead-gen forms that live on your site and create contacts in ContactFollowUp.

Field types: text, email, phone, textarea, select, checkbox, number. Keys must match /^[a-zA-Z_][a-zA-Z0-9_]*$/.

POST/api/formsBearer token

Create a form

Publish a new form. Slug is auto-generated from name if omitted.

Required scopes:contacts.write

Request body

Name	Type	Description
`name`required	`string`	Form display name.
`slug`	`string`	URL slug. ≤ 80 chars.
`description`	`string`	Optional intro text.
`fields`required	`Field[]`	≥ 1 field. See field schema.
`redirectUrl`	`string`	Post-submit redirect URL.
`submitCtaText`	`string`	Submit button label.
`captureCompany`	`boolean`	Whether to ask for a company name.
`autoCreateContact`	`boolean`	Create a contact on submit.
`isPublished`	`boolean`	Whether the form is publicly accessible.

Request body

JSON

{ "name": "Newsletter signup", "fields": [{ "key": "email", "label": "Your email", "type": "email", "required": true }] }

Responses

201 CreatedCreated.

example

{
  "id": "frm_3wp2j…",
  "name": "Newsletter signup",
  "slug": "newsletter-signup",
  "description": null,
  "fields": [
    { "key": "email", "label": "Your email", "type": "email", "required": true }
  ],
  "redirectUrl": "https://contactfollowup.com/thanks",
  "submitCtaText": "Subscribe",
  "captureCompany": false,
  "autoCreateContact": true,
  "isPublished": true,
  "createdAt": "2026-05-18T14:00:00Z"
}

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/forms \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter signup", "fields": [{ "key": "email", "label": "Your email", "type": "email", "required": true }] }'

GET/api/formsBearer token

List forms

Forms owned by the caller (or all forms for service accounts).

Required scopes:contacts.read

Responses

200 OKForms.

example

{ "forms": [{
  "id": "frm_3wp2j…",
  "name": "Newsletter signup",
  "slug": "newsletter-signup",
  "description": null,
  "fields": [
    { "key": "email", "label": "Your email", "type": "email", "required": true }
  ],
  "redirectUrl": "https://contactfollowup.com/thanks",
  "submitCtaText": "Subscribe",
  "captureCompany": false,
  "autoCreateContact": true,
  "isPublished": true,
  "createdAt": "2026-05-18T14:00:00Z"
}] }

Code samples

Shell

curl -X GET https://app.contactfollowup.com/api/forms \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json"