# POST /forms/{formId}/signups

Part of the SendHeron REST API. Base URL: `https://api.sendheron.com/api/v1`

Sign someone up through a form.

```http
POST https://api.sendheron.com/api/v1/forms/{formId}/signups
Authorization: Bearer <YOUR_API_KEY>
```

**Required scopes:** `signups:create`

**Success status:** `202`

**Rate limit:** 30/min per key (tighter than the default), counted against the organization's SEND ceiling (200/min).

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `formId` | uuid | yes | A signup form of the workspace the key belongs to. |

**Body parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | The address that signs up. It gets the confirmation email; nothing happens until its owner confirms. |
| `firstName` | string | no | Kept only when the form shows a first name field, and required when the form requires it. |
| `lastName` | string | no | Kept only when the form shows a last name field, and required when the form requires it. |
| `ipAddress` | string | yes | The visitor's IP address as your server saw it: behind Cloudflare the CF-Connecting-IP header, never an X-Forwarded-For value the visitor can write. Kept on the consent record as reported, and counted toward the per-visitor limit. |
| `userAgent` | string | no | The visitor's User-Agent header, kept on the consent record as reported. |

**Endpoint-specific errors** (beyond the shared error set):

- `400`: signupForms.invalidEmail, signupForms.undeliverableEmail (the domain takes no mail), signupForms.fieldRequired (the form requires a name), or a body field we do not take
- `403`: The key lacks signups:create, or the organization is suspended
- `404`: signupForms.notFound: no such form in this workspace
- `409`: signupForms.unavailable: the form takes no signups; the description says why (SWITCHED_OFF, SENDER_UNDER_REVIEW, NO_SENDER, CONTACT_LIMIT_REACHED and the rest)
- `429`: Too many requests: a limit of this key or of the visitor you reported; Retry-After says when to try again

**Example response.** The same for every address: new, already waiting for its confirmation, already subscribed, or one we will not mail.

```json
{
  "status": "ACCEPTED"
}
```

> For a signup form you build yourself, called from your server (a Next.js Server Action or route handler), never from the browser: the key is a secret. The person gets the form's confirmation email, in the form's language, and becomes a subscribed contact on the form's list, with its tags, only once they confirm; this route always asks for that confirmation, whatever the form's double opt-in setting. The form also decides the consent sentence kept on the record, so show your visitor that exact sentence next to your form. Protect the call the way the form protects itself: your Server Action is public, so run your own bot check (for example Cloudflare Turnstile, verified on your server) before calling, and rate-limit by visitor. The answer is the same `{ "status": "ACCEPTED" }` for every address, so it cannot tell anyone whether an address is subscribed; show the visitor "check your inbox" and nothing more. Limits: 30 a minute per key, plus hourly and daily ceilings per key, and a per-visitor limit on the IP address you report (counted for your key only). Each inbox gets at most a few confirmation emails a day across every form; past that the answer is still `ACCEPTED` and no email goes out. A key that holds only `signups:create` can do nothing else.


---

Rate limits: 30/min per key (tighter than the default), counted against the organization's SEND ceiling (200/min). Both windows are one minute. They limit requests; how much mail goes out in a day is under [Daily sending](https://sendheron.com/docs#daily-sending).
