BUbuttondown
Forms

Create Form

Changed on

Create a new form

post/forms

Request

  • Base URL
    https://api.buttondown.com/v1
  • URL
    https://api.buttondown.com/v1/forms
  • Auth
    API key in header Authorization

Request body

titlestring required

The human-readable title of the form, shown in the UI and on the hosted form page.

slugstring required

A URL-safe identifier used in the form's hosted URL (e.g. /forms/{slug}). Must be unique per newsletter.

bodystring

Markdown body rendered above the subscribe fields on the hosted form page.

cssstring

Custom CSS applied to the hosted form page.

success_bodystring

Markdown shown to the subscriber after a successful submission.

surveysstring[]

IDs of surveys to attach to this form. Responses are associated with the submitting subscriber.

tagsstring[]

UUIDs or TypeIDs of tags applied to subscribers who sign up through this form.

adminboolean

If true, the form acts as an admin-only signup form — it skips confirmation and can accept additional subscriber fields.

status'active' | 'inactive'

An enumeration.

Example request

{
  "title": "Contact Form",
  "slug": "contact",
  "success_body": "Thank you for your submission!",
  "surveys": [
    "srv_01h8abcdefghjkmnpqrstvwxyz"
  ],
  "tags": [
    "sub_tag_0k28edc3fw896bp4mrhc535z5k"
  ]
}

Response

Created

idstring required

A unique TypeID associated with the object.

creation_datestring date-time required

The date and time at which the object was first created.

titlestring required

The human-readable title of the form, shown in the UI and on the hosted form page.

slugstring required

A URL-safe identifier used in the form's hosted URL (e.g. /forms/{slug}). Must be unique per newsletter.

bodystring required

Markdown body rendered above the subscribe fields on the hosted form page.

cssstring required

Custom CSS applied to the hosted form page.

success_bodystring required

Markdown shown to the subscriber after a successful submission.

surveysstring[] required

IDs of surveys to attach to this form. Responses are associated with the submitting subscriber.

tagsstring[] required

UUIDs or TypeIDs of tags applied to subscribers who sign up through this form.

adminboolean required

If true, the form acts as an admin-only signup form — it skips confirmation and can accept additional subscriber fields.

status'active' | 'inactive' required

An enumeration.

subscriber_countinteger required

The number of subscribers who signed up through this form.

confirmed_subscriber_countinteger required

The number of confirmed subscribers who signed up through this form.

page_view_countinteger required

The number of page views for this form.

Example response

{
  "tags": [
    "sub_tag_0k28edc3fw896bp4mrhc535z5k"
  ]
}

Changes

  • 11e4fd327eb3Revision changes
    • warning

      added the new tag_not_found enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the required property to the response with the status

  • 228cc05ba97dRevision changes
    • info

      added the non-success response with the status