Formcrest
Log inGet started

Submit API reference

The form submit endpoint is the only public, developer-facing endpoint in Formcrest v1. Send a submission to it from a browser form, fetch call, or any HTTP client.

Endpoint

Every form has a single submit URL. Replace <formId> with the form ID shown in your dashboard.

POST https://api.formcrest.com/v1/submit/<formId>

The endpoint is open to cross-origin requests, so it can be called directly from the browser. A POST is required; the same path also answers OPTIONS for CORS preflight.

Content types

The request body may be sent as any of the following:

  • application/x-www-form-urlencoded — a standard HTML form post.
  • multipart/form-data — also a standard form post. File parts are accepted by the parser but ignored in v1; only text fields are stored.
  • application/json — a flat JSON object of field names to values.

Any other content type is rejected with validation_failed. Every field you send (other than the control fields below) is captured as part of the submission, so use whatever field names suit your form. Repeated form fields with the same name are collected into an array.

Control fields

A few field names have special meaning. They are interpreted and then stripped from the stored submission rather than saved as data.

FieldPurpose
_honeyHoneypot. Leave it empty — bots that fill it in are silently filtered as spam. The names _gotcha, botfield, url, and website are also treated as honeypots; _honey is the recommended one.
cf-turnstile-responseCloudflare Turnstile token. Include it only when the form requires Turnstile. A missing or invalid token causes the submission to be filtered as spam.
access_keyAccess key, when the form requires one. Submissions without the expected key are rejected.

See Spam protection for the honeypot and Turnstile, and Form configuration for access keys and redirects.

Headers

HeaderEffect
Content-TypeOne of the accepted content types above. Required so the body can be parsed.
Accept: application/jsonForces a JSON response (success or error) instead of a redirect. Recommended for fetch and other programmatic callers.
Idempotency-KeyOptional. A unique key per logical submission. Retrying with the same key within 24 hours returns the original result instead of creating a duplicate.

Success response

In JSON mode (when Accept: application/json is set, or you posted JSON and no redirect is configured), a successful submission returns 200 with:

{ "ok": true, "submissionId": "sub_1a2b3c..." }

A submission that was accepted but filtered as spam also returns ok: true (to avoid signalling bots) and includes "filtered": "spam". A request replayed with a matching Idempotency-Key returns the original submissionId with "cached": true.

Redirect response

Otherwise — a traditional HTML form post that accepts text/html, or any form with a configured success URL — the endpoint replies with a 303 redirect. The visitor lands on the form's success URL, or on our hosted thank-you page at /thanks when none is set. A request may override the destination with a redirect field in the body.

HTTP/1.1 303 See Other
Location: https://example.com/thanks

Error response

In JSON mode, errors return the catalog's HTTP status and this envelope:

{
  "error": "<code>",
  "message": "Human-readable explanation.",
  "fieldErrors": { "email": "..." }
}

fieldErrors is present only when individual fields failed validation. For a traditional HTML form post, errors instead produce a redirect to the form's configured error URL with ?error=CODE appended. See Error codes for the full catalog and the meaning of each code.

Example request

A JSON submission asking for a JSON response back:

POST /v1/submit/abc123 HTTP/1.1
Host: api.formcrest.com
Content-Type: application/json
Accept: application/json
Idempotency-Key: 0f7c2b9a-1e3d-4c5a-9b8e-12d3f4a5b6c7

{
  "email": "jane@example.com",
  "message": "Hello from the docs"
}
HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true, "submissionId": "sub_1a2b3c4d5e" }

curl

curl https://api.formcrest.com/v1/submit/abc123 \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","message":"Hello from curl"}'
# => { "ok": true, "submissionId": "..." }

The same call with a form-encoded body (omit Accept to follow the redirect):

curl -i https://api.formcrest.com/v1/submit/abc123 \
  -d "email=jane@example.com" \
  -d "message=Hello from curl" \
  -d "_honey="

A note on scope

The submit endpoint is the only public API in v1. Account, form, and submission management is handled through the Formcrest dashboard and is not exposed as a public API yet. A broader public REST API for managing forms programmatically is planned for a future release.

Related