POST
/forms/{formId}/signupsPOST /forms/{formId}/signups
Sign someone up through a form.
Request
curl -X POST 'https://api.sendheron.com/api/v1/forms/{formId}/signups' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json'Required scopes
The key must carry these:
- signups:create
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 |
|---|---|---|---|
| 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. |
Example response
The same for every address: new, already waiting for its confirmation, already subscribed, or one we will not mail.
{
"status": "ACCEPTED"
}Responses
Returns 202 on success.
- 400
- The payload failed validation, or the request is not valid for the current state.
messagesays which kind of refusal it is, and for a payload that failed validation (validationFailed) thedescriptionnames the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". An id in the path that is not a UUID answersinvalidUUIDon every route. - 401
- Missing or invalid API key.
- 403
- Valid key, but it does not carry the required scope.
messageisapiKeys.insufficientScopesand thedescriptionnames both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was. - 404
- No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
- 409
- A duplicate, or an idempotency key reused with a different payload.
- 429
- Either rate-limit ceiling was exceeded.
messageistooManyRequests, and theRetry-Afterheader says how many seconds until the window rolls. - 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
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.