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

# Forms API

> The subscribe endpoint behind embedded forms.

The forms API powers [embedded forms](/en/integrations/embedded-forms). You usually let the Senderz form bundle call it, but you can call it directly.

## Subscribe

```http theme={null}
POST /api/v1/forms/subscribe
```

Authenticated with the [`X-Sender-Tenant` + `X-API-Key`](/en/api-reference/authentication) headers. Requires the `embedded_forms` feature and passes the workspace's origin allowlist.

### Body

<ParamField body="email" type="string" required>
  Subscriber email (max 320).
</ParamField>

<ParamField body="phone" type="string">
  Subscriber phone (max 40).
</ParamField>

<ParamField body="formId" type="string">
  A label for which form this came from (max 120). Client-supplied — not a
  security boundary.
</ParamField>

<ParamField body="fields" type="object">
  Extra field values. Native catalog keys route to their column; everything
  else lands in custom properties.
</ParamField>

<ParamField body="sourceUrl" type="string">
  The page URL the form was submitted from (max 2048).
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="contactId" type="string">
  The upserted contact's UUID.
</ResponseField>

<ResponseField name="isNew" type="boolean">
  `true` if this created a new contact.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.senderz.app/api/v1/forms/subscribe \
    -H "X-Sender-Tenant: your-workspace-slug" \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Origin: https://yourstore.com" \
    -d '{ "email": "dana@example.com", "fields": { "firstName": "Dana" } }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "ok": true, "contactId": "b2f1c0de-…", "isNew": true }
  }
  ```
</CodeGroup>

<Info>
  Subscribing sets email consent to `subscribed` with source
  `embedded_form`, and enrols `contact_created` / `list_joined` flows.
</Info>

<Warning>
  This endpoint is rate limited to **10 requests per minute**, and rejects
  submissions from origins not on your allowlist with `403`. Configure the
  allowlist in Settings → Embedded Forms.
</Warning>