API reference · v1
Forms
Public form submission and double opt-in confirmation.
Submit a form
/v1/forms/{formId}/submitPublic endpoint · no API key required
Public, unauthenticated form submission (the tenant is derived from the form, not an API key). Validates required fields, CAPTCHA, and consent, then upserts the contact or (for double opt-in, when the visitor opted in to email) stores a pending record and emails a confirmation link. A declined-consent submission always goes through the direct path even on a double opt-in form. Rate limits: per IP 10/60s and per form 120/60s (both fail open if Redis is down), plus a separate per-recipient/per-form cap on confirmation emails. Error: rate_limit_exceeded.
Path parameters
- Name
formId- Type
- string
- Requirement
- Required
- Description
- The form id.
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
contact- Type
- object
- Requirement
- Required
- Description
- Flat contact input for the form's contact schema. Custom attribute keys are passed at the top level.
- Name
emailMarketingConsent- Type
- boolean | null
- Description
- See the request example and OpenAPI schema for this field.
- Name
captchaToken- Type
- string | null
- Description
- See the request example and OpenAPI schema for this field.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/forms/form_BcwDvBUeSaSDILA5tHgpmU7I/submit' \
-X POST \
-H "Content-Type: application/json" \
-d '{
"contact": {
"email": "[email protected]",
"firstName": "Sarah"
},
"emailMarketingConsent": false
}'Response
{
"data": {
"contactId": "con_BcwDvBUeSaSDILA5tHgpmU7I"
},
"warnings": []
}Status codes
- 200The submission was accepted.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 404The referenced resource was not found.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Confirm a double opt-in
/v1/forms/{formId}/confirm/{token}Public endpoint · no API key required
Public browser navigation target for the double opt-in email link. Redeems the token, upserts the confirmed contact, and always redirects (302) to the hosted result page. Every failure path (missing/expired token, unpublished form) also redirects to a "failed" landing page rather than returning a JSON error. Same rate limits as forms.submit.
Path parameters
- Name
formId- Type
- string
- Requirement
- Required
- Description
- The form id.
- Name
token- Type
- string
- Requirement
- Required
- Description
- The single-use double opt-in token from the confirmation email.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/forms/form_BcwDvBUeSaSDILA5tHgpmU7I/confirm/string' \
--includeStatus codes
- 302Redirect to the hosted confirmation result page.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.