JavaScript and fetch

Any code that can send an HTTP request can submit to Ikiform. Post JSON, FormData or urlencoded data to https://ikiform.com/f/<formId> and read a JSON answer. The SDK wraps this in one function, but it is optional. For framework walkthroughs, see the guides for Next.js, React, Vue, Svelte and Astro.

With fetch

const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({
    name: "Ada Lovelace",
    email: "ada@example.com",
    message: "Hello",
  }),
});

const result = await response.json();
if (!result.ok) console.error(result.error.code, result.error.fields);

Try it

curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","message":"Hello from the Ikiform docs."}'

Endpoints

Opening /f/<formId> itself in a browser tab is a GET, which answers 404 not_found. That is expected: the endpoint only takes posts.

Body formats

Bodies must be UTF-8. A charset other than utf-8 gets 415 unsupported_charset, and bytes that aren't valid UTF-8 get the same code. A JSON array or a malformed body gets 400 invalid_body.

Headers

Request headers

Response headers

CORS

The submission endpoint accepts cross-origin posts from any site. Preflights always succeed and echo the request's origin. No cookies or credentials are used, so CORS is not what protects your form: allowed domains are. With allowed domains set, a post from another site is stored as spam or refused, depending on the form's setting. See Allowed domains.

OPTIONS /f/frm_xxxxxxxxxxxxxxxx HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, Accept, Idempotency-Key, Authorization
Access-Control-Max-Age: 86400
Vary: Origin

Responses

Success is 201 with the new submission id. Errors use one envelope everywhere, with field errors keyed by field id when validation fails. Every code is listed on Errors.

{ "ok": true, "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" }

Idempotency

Send an Idempotency-Key header, or an _idempotency field, to make retries safe. Keys are up to 255 characters and are scoped to the form for 24 hours. The header wins when both are sent.

Posts that fail before the submission is stored, such as validation errors, don't keep the key, so you can fix the data and retry with the same key. A safe retry loop:

const key = crypto.randomUUID();

async function send(attempt = 1) {
  const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Idempotency-Key": key },
    body: JSON.stringify({ email: "ada@example.com" }),
  }).catch(() => null);
  if (response && response.status < 500 && response.status !== 429) return response.json();
  if (attempt === 3) throw new Error("Ikiform is unreachable");
  const wait = Number(response?.headers.get("Retry-After")) || attempt * 2;
  await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  return send(attempt + 1);
}