Widgets

Submit signup form

Changed on

Submit a public signup form. No API key is required.

When the path value is a saved form ID, the form's stored settings are used for audience targeting and success behavior. When the path value is a company ID, this endpoint uses the legacy company-level form behavior.

Omit lists to use the workspace default lists setting, provide lists= to add the subscriber to no lists, or provide comma-separated list IDs for specific lists. Provide stable tags IDs to apply existing tags to the subscriber.

Submitting again is a fresh opt-in. A contact who unsubscribed from all email is resubscribed and their target list memberships are restored, whatever the duplicateStrategy. When the saved form's resubscribeBehavior is double_opt_in, or workspace double opt-in is on, they receive a confirmation email instead and are resubscribed when they confirm. Contacts whose address bounced or who marked your email as spam are not resubscribed. The response is the same in every case, so it does not reveal whether an address was subscribed.

post/forms/{companyIdOrFormId}

Request

  • Base URL
    https://api.sequenzy.com/api/v1
  • URL
    https://api.sequenzy.com/api/v1/forms/{companyIdOrFormId}
  • Auth
    none required

Path parameters

companyIdOrFormIdstring required

A saved form ID, or a company ID for legacy generated forms

Query parameters

listsstring

Comma-separated list IDs. Omit for workspace default lists, or provide an empty value for no lists.

tagsstring

Comma-separated tag IDs to apply to the subscriber.

duplicateStrategy'skip' | 'merge' | 'overwrite'

How to handle profile fields of an existing contact with the submitted email. Use skip to preserve fields, merge to fill missing fields, or overwrite to replace submitted fields. Merge and overwrite require duplicateStrategyToken from the form builder. Does not affect whether an unsubscribed contact is resubscribed.

duplicateStrategyTokenstring

Signed token generated by the form builder for the selected duplicateStrategy. Required for merge or overwrite.

Request body

emailstring email required

Subscriber email address

firstNamestring
lastNamestring
phonestring

Subscriber phone number in E.164 or US national format. Stored on the base subscriber profile and does not grant SMS consent.

customAttributesobject

Subscriber custom attributes

listIdsstring[]
tagIdsstring[]

Existing tag IDs to apply to the subscriber

duplicateStrategy'skip' | 'merge' | 'overwrite'

Body alternative to the duplicateStrategy query parameter. Query parameter takes precedence. Merge and overwrite require duplicateStrategyToken.

duplicateStrategyTokenstring

Body alternative to the duplicateStrategyToken query parameter.

redirectUrlstring

Http(s) URL or bare domain to redirect to after successful submission

websitestring

Honeypot field. Leave empty.

sequenzyTokenstring

Signed bot-protection token that Sequenzy's hosted embed script and popups add automatically. Custom integrations can omit it. Submissions without a valid token may be asked to confirm by email. Workspaces with strict protection ignore submissions without a token, or with a token for a different form or popup, and return the normal success response.

sequenzyBotCheckTokenstring

Cloudflare Turnstile token that the hosted embed script and popups add automatically when the form or popup has bot protection on. Custom integrations cannot obtain one. When bot protection is on, submissions without a valid token must confirm by email before they are subscribed; if the workspace's confirmation email or sender was removed after bot protection was turned on, they return 400 with a retry message instead. Ignored when bot protection is off.

Example request

{
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+12133734253",
  "customAttributes": {
    "nickname": "Ace",
    "zipcode": "19104"
  },
  "listIds": [
    "list_abc123"
  ],
  "tagIds": [
    "tag_abc123",
    "tag_def456"
  ],
  "redirectUrl": "https://example.com/thank-you"
}

Response

Form submitted successfully

successboolean

Example response

{
  "success": true
}

Changes

  • db3873ca3d4dRevision changes
    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)

  • ad2202945c5bRevision changes
    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)