Signup Forms

Create embeddable signup forms to collect contacts from your website. Forms can automatically add contacts to segments and subscribe them to topics. The public submit endpoint requires no authentication, making it safe to call from client-side code.

POST

/signup-forms

Create a new signup form. Optionally assign a segment and subscription topic for automatic contact management.

json

{
  "name": "Newsletter Signup",
  "segment_id": 1,
  "topic_id": 1,
  "fields": [
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "placeholder": "you@example.com"
    },
    {
      "name": "first_name",
      "type": "text",
      "label": "First Name",
      "required": false,
      "placeholder": "Jane"
    }
  ],
  "success_message": "Thanks for subscribing!",
  "redirect_url": "https://example.com/welcome"
}

GET

/signup-forms

List all signup forms with pagination.

json

{
  "forms": [
    {
      "id": 1,
      "public_id": "sf_abc123def456",
      "name": "Newsletter Signup",
      "active": true,
      "submission_count": 142,
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

GET

/signup-forms/:id

Get a signup form by ID, including its full field configuration.

json

{
  "id": 1,
  "public_id": "sf_abc123def456",
  "name": "Newsletter Signup",
  "segment_id": 1,
  "topic_id": 1,
  "fields": [
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true
    }
  ],
  "success_message": "Thanks for subscribing!",
  "redirect_url": "https://example.com/welcome",
  "active": true,
  "submission_count": 142,
  "created_at": "2026-03-20T10:00:00.000Z",
  "updated_at": "2026-03-20T10:00:00.000Z"
}

PATCH

/signup-forms/:id

Update a signup form. All fields are optional.

json

{
  "name": "Updated Newsletter Form",
  "active": false,
  "success_message": "You're on the list!",
  "redirect_url": null
}

DELETE

/signup-forms/:id

Delete a signup form. The public submit endpoint will stop accepting submissions immediately.

json

{
  "success": true
}

Public Submit Endpoint

The submit endpoint requires no authentication and supports CORS, making it safe to call directly from frontend JavaScript. The contact is automatically created (or updated if they already exist) and added to the form's configured segment and subscription topic.

POST

/signup-forms/:id/submit

Submit a signup form (no authentication required). Creates or updates the contact and adds them to the configured segment and topic.

json

{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe"
}

Frontend Integration

Embed a signup form on your website with a simple fetch call:

typescript

async function submitForm(formId: string, email: string) {
  const response = await fetch(
    `https://api.poststack.dev/signup-forms/${formId}/submit`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    },
  );
  return response.json();
}

Field Types

Forms support up to 10 fields, each with one of these types:

Type	Description
`email`	Email address field (required for every form)
`text`	Free-form text input
`select`	Dropdown with predefined options (provide the `options` array)