> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Signup Form

> Submit a public signup form and create or update a subscriber.

# Submit Signup Form

You can submit an embedded signup form or popup without an API key. The endpoint accepts `application/x-www-form-urlencoded` form posts and JSON.

<Note>
  Forms created in the dashboard post to the [saved form
  endpoint](/api-reference/widgets/submit-saved-form), which stores audience
  targeting and success behavior server-side. This company-level endpoint keeps
  working for popups and existing deployed embeds.
</Note>

## Request

<ParamField path="companyId" type="string" required>
  Your company ID.
</ParamField>

<ParamField body="email" type="string" required>
  The subscriber's email address.
</ParamField>

<ParamField body="firstName" type="string">
  The subscriber's first name.
</ParamField>

<ParamField body="lastName" type="string">
  The subscriber's last name.
</ParamField>

<ParamField body="customAttributes[fieldKey]" type="string">
  Submit a subscriber custom attribute from an HTML form, for example
  `customAttributes[nickname]=Ace`.
</ParamField>

<ParamField body="customAttributes" type="object">
  JSON alternative for custom integrations.
</ParamField>

<ParamField query="lists" type="string">
  Comma-separated list IDs. Omit this to use your workspace default lists, or
  use an empty `lists=` value to add the subscriber to no lists.
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated tag IDs to apply to the subscriber.
</ParamField>

<ParamField query="duplicateStrategy" type="string" default="skip">
  How to handle an existing contact with the submitted email. Use `skip` to
  preserve existing fields, `merge` to fill only missing fields, or `overwrite`
  to replace submitted fields. `merge` and `overwrite` require a matching
  `duplicateStrategyToken` from the Sequenzy form builder.
</ParamField>

<ParamField query="duplicateStrategyToken" type="string">
  Signed token generated by the Sequenzy form builder for the selected
  `duplicateStrategy`. Required when `duplicateStrategy` is `merge` or
  `overwrite`.
</ParamField>

<ParamField body="duplicateStrategy" type="string" default="skip">
  Body alternative to the `duplicateStrategy` query parameter for custom
  integrations. Query parameter takes precedence when both are present. `merge`
  and `overwrite` require a matching `duplicateStrategyToken`.
</ParamField>

<ParamField body="duplicateStrategyToken" type="string">
  Body alternative to the `duplicateStrategyToken` query parameter.
</ParamField>

<ParamField body="listIds[]" type="string[]">
  Existing deployed embed format for repeated list IDs.
</ParamField>

<ParamField body="tagIds[]" type="string[]">
  Existing deployed embed format for repeated tag IDs.
</ParamField>

<ParamField body="website" type="string">
  Honeypot field. Leave it empty.
</ParamField>

<ParamField body="redirectUrl" type="string">
  `http` or `https` URL, or a domain such as `google.com`, to redirect visitors
  to after a successful submission.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/forms/company_123?lists=list_abc123,list_def456&tags=tag_abc123&duplicateStrategy=merge&duplicateStrategyToken=SIGNED_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "email=user@example.com" \
  --data-urlencode "customAttributes[nickname]=Ace"
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {"success": true}
  ```

  ```text 303 theme={null}
  Location: https://example.com/thank-you
  ```

  ```json 400 theme={null}
  { "success": false, "message": "Please enter a valid email address" }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "message": "Please enter a valid redirect URL"
  }
  ```

  ```json 400 theme={null}
  { "success": false, "message": "This email address cannot be subscribed" }
  ```

  ```json 404 theme={null}
  { "success": false, "message": "Invalid form configuration" }
  ```

  ```json 429 theme={null}
  { "success": false, "message": "Too many requests. Please try again later." }
  ```

  ```json 500 theme={null}
  { "success": false, "message": "An error occurred. Please try again." }
  ```
</ResponseExample>