Sign in

v93

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01218121759.7 KB
Widgets

Submit signup form

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.

post/forms/{companyIdOrFormId}

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 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.

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.

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
}