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. A direct submission that needs missing AI auto-fill values requires a timed submissionId. Retain it across network and CAPTCHA retries; do not generate a new ID for an unanswered request. The ID uses the same format and retry window as timed record Idempotency-Key values. Confirmation has its own persisted server identity and token expiry.
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
submissionId- Type
- string
- Description
- Stable ID for one input, required when direct contact creation needs AI auto-fill. Format rpi1.<Unix milliseconds>.<UUIDv4>. Keep the original ID with the original input for retries. The recovery window is 24 hours rounded up to the next minute.
- 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.
- 410The record operation expired or its stored response was erased. Reconcile the original operation before starting a new one.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
- 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.