Form ID

REST API

Create, configure and delete forms, read submissions and manage spam, and manage webhook endpoints and deliveries with a secret key.

The REST API lets your server create, configure, pause and delete forms and their field schemas, read submissions, move them in and out of spam and delete them, and create, change, test and replay webhook endpoints. It is JSON over HTTPS at https://ikiform.com/api/v1. The OpenAPI 3.1 document is at /api/v1/openapi.json.

Creating submissions is not part of /api/v1. Post to the form endpoint with a secret key instead; see From a server.

Working with an AI agent such as Claude Code or Cursor? Connect the MCP server instead: it offers the same actions as tools, with the same keys and scopes.

API keys

Create keys in the dashboard under API keys. A key belongs to one workspace and only sees that workspace. The full key is shown once; Ikiform stores only its hash.

KindPrefixUse
Secretik_sk_For servers. Calls the REST API with the scopes you choose, and can create submissions.
Publishableik_pub_For browsers. Can only submit forms, and only from the domains you list on the key.

Scopes

ScopeGrants
forms:readGET /forms, GET /forms/:formId
forms:writePOST /forms, PATCH and DELETE /forms/:formId, PUT and DELETE /forms/:formId/fields
submissions:readGET /submissions, GET /submissions/:id
submissions:writeDELETE /submissions/:id, POST /submissions/:id/spam and /not-spam, and posting to /f/:formId
webhooks:readGET /webhooks, GET /webhooks/:endpointId and /deliveries
webhooks:writePOST /webhooks and PATCH /webhooks/:endpointId (with submissions:read), DELETE /webhooks/:endpointId, and POST to /roll-secret, /test and /replay

A key keeps the scopes it was created with. Existing keys don't gain forms:write, webhooks:read or webhooks:write; create a new key with them.

Authentication

Send the secret key as a Bearer token. The API is server to server only: it sends no CORS headers and answers browser preflights with 405, so a secret key can never work from a web page.

Terminal
curl https://ikiform.com/api/v1/forms \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
  • A missing, malformed, unknown, revoked or expired key gets 401 unauthorized with WWW-Authenticate: Bearer.
  • A publishable key gets 403 forbidden (Publishable keys can only submit forms.). A key without the needed scope gets 403 forbidden with the scope named in the message.
  • Responses are sent with Cache-Control: no-store.

The SDK examples below share one client:

ikiform.ts
import { createClient } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });

Request composer

Form
Form ID
curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Run this from your server. The REST API refuses browser requests, so this page never sends it.

Endpoints

MethodPathScopeReturns
GET/meanyCheck an API key
GET/formsforms:readList forms
GET/forms/:formIdforms:readGet a form
POST/formsforms:writeCreate a form
PATCH/forms/:formIdforms:writeUpdate a form
PUT/forms/:formId/fieldsforms:writePublish a field schema
DELETE/forms/:formId/fieldsforms:writeRemove the field schema
DELETE/forms/:formIdforms:writeDelete a form
GET/submissionssubmissions:readList submissions
GET/submissions/:idsubmissions:readGet a submission
POST/submissions/:id/spamsubmissions:writeMark as spam
POST/submissions/:id/not-spamsubmissions:writeMark as not spam
DELETE/submissions/:idsubmissions:writeDelete a submission
GET/forms/:formId/fieldsforms:readList a form's fields
GET/forms/:formId/samplesubmissions:readSample submission events
GET/webhookswebhooks:readList webhook endpoints
POST/webhookswebhooks:writeCreate a webhook endpoint
GET/webhooks/:endpointIdwebhooks:readGet a webhook endpoint
PATCH/webhooks/:endpointIdwebhooks:writeUpdate a webhook endpoint
POST/webhooks/:endpointId/roll-secretwebhooks:writeRoll the signing secret
DELETE/webhooks/:endpointIdwebhooks:writeDelete a webhook endpoint
POST/hookswebhooks:writeSubscribe a REST hook
DELETE/hooks/:hookIdwebhooks:writeUnsubscribe a REST hook
GET/webhooks/:endpointId/deliverieswebhooks:readList deliveries
POST/webhooks/:endpointId/testwebhooks:writeSend a test event
POST/webhooks/:endpointId/replaywebhooks:writeReplay failed deliveries
GET/openapi.jsonNoneThe OpenAPI document
GET/healthNone{ "ok": true }

Check an API key

GET /me with any scope.

  • Works with any scope. Automation platforms call it to test a connection and to name it after the workspace.
curl https://ikiform.com/api/v1/me \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

List forms

GET /forms with the forms:read scope.

  • Newest first. Takes limit (1 to 100, default 25) and cursor.
curl "https://ikiform.com/api/v1/forms?limit=10" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Get a form

GET /forms/:formId with the forms:read scope.

  • Also returns fields and definition, the published field schema, or null when the form has none and accepts any fields, and whether notifications are on.
curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Create a form

POST /forms with the forms:write scope.

  • Only name is required. Send JSON with Content-Type: application/json.
  • Post submissions to the returned endpoint. Add a hidden input named honeypot_field and leave it empty.
  • It also takes every setting Update a form takes, except status.
curl -X POST https://ikiform.com/api/v1/forms \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Waitlist", "allowed_domains": ["example.com"], "redirect_url": "https://example.com/thanks" }'

Update a form

PATCH /forms/:formId with the forms:write scope.

  • Send only what changes. status is active or paused; a paused form refuses posts. A form Ikiform disabled returns 403.
  • Send [] or null to clear allowed_domains or redirect_url, and null as honeypot_field for _gotcha.
  • spam_check is off, ikiform (our human check) or custom (your Turnstile widget, with turnstile_site_key and turnstile_secret). The secret is stored encrypted and never returned; null removes it and turns custom off.
  • origin_mismatch is spam or reject for posts from sites outside allowed_domains.
  • rate_limit takes preset (standard, relaxed, strict or custom), plus per_ip, window_seconds (10, 60, 600, 3600 or 86400) and optional per_form_per_minute for custom. It is write-only, so bots can't read it.
  • notifications: { "enabled": false } stops new-submission emails. Recipients are chosen in the dashboard.
  • Unknown fields return 400 invalid_request naming the field.
curl -X PATCH https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused", "origin_mismatch": "reject", "rate_limit": { "preset": "strict" } }'

Publish a field schema

PUT /forms/:formId/fields with the forms:write scope.

  • The body is a form definition: version 1, a title and up to 100 fields, the same format as Fields. It can be up to 256 KB.
  • From then on, posts are validated against it and posts that don't match are rejected with 422. A definition with problems returns 422 validation_failed, and error.fields lists them by path, like fields.0.type.
curl -X PUT https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/fields \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1, "title": "Contact", "fields": [{ "id": "email", "type": "email", "label": "Email", "required": true }, { "id": "message", "type": "textarea", "label": "Message" }] }'

Remove the field schema

DELETE /forms/:formId/fields with the forms:write scope.

  • The form accepts any fields again.
curl -X DELETE https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/fields \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Delete a form

DELETE /forms/:formId with the forms:write scope.

  • The endpoint stops accepting posts at once, and the form disappears from lists. Deleting again returns 404.
curl -X DELETE https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

List submissions

GET /submissions with the submissions:read scope.

ParameterValuesDefault
form_idA form idAll forms in the workspace
statusreceived or spamBoth
limit1 to 10025
cursornext_cursor from the previous pageThe first page
  • Newest first. A form_id from another workspace returns an empty list rather than an error, so ids can't be probed.
curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Get a submission

GET /submissions/:id with the submissions:read scope.

    curl https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    Mark as spam

    POST /submissions/:id/spam with the submissions:write scope.

    • Moves a received submission to spam, lowers the form's submission_count, cancels its pending submission.created deliveries and sends submission.updated to subscribed endpoints.
    • Calling it on a submission that is already spam returns it unchanged.
    curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    Mark as not spam

    POST /submissions/:id/not-spam with the submissions:write scope.

    • Moves it back to received, clears its spam score and reasons, and sends submission.updated to subscribed endpoints, plus submission.created to subscribed endpoints that never received one for it.
    • Calling it on a received submission returns it unchanged.
    curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    Delete a submission

    DELETE /submissions/:id with the submissions:write scope.

    • Permanently removes the submission and its webhook deliveries, then sends submission.deleted to subscribed endpoints. There is no undo. Deleting again returns 404.
    curl -X DELETE https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    List a form's fields

    GET /forms/:formId/fields with the forms:read scope.

    • Lists the fields a submission can carry, for mapping in Zapier, Make or n8n. key is the name the value has in fields.
    • source is definition when the form has published fields. Otherwise the list is built from the keys of its 25 most recent submissions, with reserved _ keys left out.
    curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/fields \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    Sample submission events

    GET /forms/:formId/sample with the submissions:read scope.

    • Returns up to 3 recent received submissions in exactly the body a submission.created webhook carries, so a tool can show real data while you set it up.
    • A form without submissions gets one example built from its fields, with submission_id set to sub_example.
    curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx/sample \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    List webhook endpoints

    GET /webhooks with the webhooks:read scope.

    • Returns every endpoint in the workspace in one page.
    • Signing secrets and custom header values are never returned. header_names lists the custom headers each delivery carries.
    curl https://ikiform.com/api/v1/webhooks \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

    Create a webhook endpoint

    POST /webhooks with the webhooks:write scope.

    • url follows the endpoint URL rules. Omit form_id for every form.
    • event_types defaults to submission.created. headers is a list of { name, value }, stored encrypted; see Custom headers.
    • secret is returned only here, so store it now. Past your plan's endpoint limit you get 402 plan_required.
    • Creating or changing an endpoint also needs submissions:read, because the endpoint receives submission data.
    curl -X POST https://ikiform.com/api/v1/webhooks \
      -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "url": "https://example.com/webhooks/ikiform", "form_id": "frm_xxxxxxxxxxxxxxxx", "headers": [{ "name": "Authorization", "value": "Bearer your-token" }] }'

    Get a webhook endpoint

    GET /webhooks/:endpointId with the webhooks:read scope.

      curl https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

      Update a webhook endpoint

      PATCH /webhooks/:endpointId with the webhooks:write scope.

      • Send only what changes: url, form_id, description, event_types, headers or status.
      • status: "disabled" stops deliveries and "active" resumes them. Resuming doesn't send what was missed: replay it.
      • headers replaces the saved list; "value": null keeps a saved value. When url changes, send every value again so a token never reaches a new host by mistake.
      curl -X PATCH https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "status": "disabled" }'

      Roll the signing secret

      POST /webhooks/:endpointId/roll-secret with the webhooks:write scope.

      • Returns a new signing secret once. The old one keeps working for 24 hours, so you can update your server without dropping deliveries.
      curl -X POST https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/roll-secret \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

      Delete a webhook endpoint

      DELETE /webhooks/:endpointId with the webhooks:write scope.

      • Deletes the endpoint and its delivery history. Pending deliveries to it are dropped.
      curl -X DELETE https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

      Subscribe a REST hook

      POST /hooks with the webhooks:write scope.

      • Creates a webhook endpoint for an automation platform. It takes the same fields as Create a webhook endpoint, plus managed_by: zapier, make, n8n or automation (the default).
      • It's a normal endpoint: it counts toward your plan's endpoint limit, shows in the dashboard and is signed. When its receiver answers 410 Gone, it's deleted without the usual email, because the platform has turned it off.
      • Needs submissions:read too, because the hook receives submission data.
      curl -X POST https://ikiform.com/api/v1/hooks \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "url": "https://hooks.zapier.com/hooks/standard/123/abc", "form_id": "frm_xxxxxxxxxxxxxxxx", "managed_by": "zapier" }'

      Unsubscribe a REST hook

      DELETE /hooks/:hookId with the webhooks:write scope.

      curl -X DELETE https://ikiform.com/api/v1/hooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3 \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

      List deliveries

      GET /webhooks/:endpointId/deliveries with the webhooks:read scope.

      • Newest first. status is succeeded, pending or failed; failed includes cancelled deliveries. Takes limit and cursor like the other lists.
      • last_status_code and last_error come from the latest attempt.
      curl "https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/deliveries?status=failed&limit=50" \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

      Send a test event

      POST /webhooks/:endpointId/test with the webhooks:write scope.

      • Queues an endpoint.test event and returns the delivery. List deliveries to see how your server answered.
      • A disabled endpoint returns 409 conflict. Enable it first.
      curl -X POST https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/test \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

      Replay failed deliveries

      POST /webhooks/:endpointId/replay with the webhooks:write scope.

      • window is 24h, 3d or 7d. Every delivery created in that window that failed or was cancelled is sent again within about a minute, up to 1,000 per call.
      • If more is true, call again to replay the rest.
      • A disabled endpoint returns 409 conflict. Test events are never replayed. See Replaying failed deliveries.
      curl -X POST https://ikiform.com/api/v1/webhooks/whk_01k7v2b8f4h6j2k9m3n5p7q1r3/replay \
        -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "window": "24h" }'

      Objects

      Objects are snake_case JSON with an object field. Timestamps are ISO 8601 in UTC with milliseconds. Submission, endpoint and delivery ids are ordered by time (sub_, whk_ and dlv_ plus 26 characters); form ids are random (frm_ plus 16 characters).

      Form fieldDescription
      statusactive, paused or disabled
      submission_countReceived submissions, not spam
      endpointThe URL to post submissions to
      honeypot_fieldThe hidden field bots fill in. Leave it empty in your form
      allowed_domainsSites allowed to post, subdomains included. Empty allows any site
      redirect_urlWhere browsers go after a plain HTML post, or null for the Ikiform thank-you page
      spam_checkoff, ikiform or custom, with turnstile_site_key and turnstile_secret_set for custom
      origin_mismatchspam or reject: what happens to posts from sites outside allowed_domains
      fields, definition, notificationsOnly when retrieving, creating or updating one form. The field schema, or null without one, and whether new submissions are emailed
      Webhook endpoint fieldDescription
      form_idThe one form it receives events for, or null for every form
      statusactive or disabled, with disabled_reason when disabled
      event_typesThe events it is subscribed to
      header_namesCustom headers sent with each delivery. Values are never returned
      failing_since, consecutive_failures, circuit_open_untilFailure tracking. Deliveries are paused until circuit_open_until after repeated failures
      Delivery fieldDescription
      statuspending, succeeded, failed or cancelled
      attempt_countAttempts so far
      last_status_code, last_errorYour server's status code, or the error, from the latest attempt
      next_attempt_atWhen a pending delivery is tried next
      Submission fieldDescription
      statusreceived or spam
      fieldsThe stored values
      metauser_agent, origin, referrer, country, subject, reply_to. Every key is present and any value can be null. The IP hash is never returned
      spam.score, spam.reasonsThe spam score and reasons, such as honeypot or origin_mismatch

      Pagination

      Lists are newest first and use opaque cursors.

      1. Request without a cursor.
      2. If has_more is true, send next_cursor as cursor with the same filters.
      3. Stop when next_cursor is null.

      Pages are stable while new submissions arrive: new ones appear on the first page, never as duplicates further down. Don't build or parse cursors yourself; an invalid one returns 400 invalid_request.

      for await (const submission of ikiform.submissions.iterate({ formId: "frm_xxxxxxxxxxxxxxxx" })) {
        console.log(submission.id, submission.fields);
      }

      Errors

      Errors use the same envelope as form submissions. Every response has an X-Request-Id header, which errors repeat as request_id.

      403 Forbidden
      {
        "ok": false,
        "error": { "code": "forbidden", "message": "This API key is missing the forms:read scope." },
        "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
      }
      StatusCodeWhen
      400invalid_requestA query parameter or body field is invalid; the message names it, and error.fields maps a body field to its messages
      400invalid_bodyThe body isn't a JSON object
      401unauthorizedMissing or invalid key
      402plan_requiredCreating a webhook endpoint past the number your plan includes
      403forbiddenPublishable key, a missing scope, or resuming a form Ikiform disabled
      404not_foundUnknown route or id, or an id in another workspace, exactly like one that doesn't exist
      405method_not_allowedA browser preflight
      409conflictTesting or replaying a disabled webhook endpoint
      413payload_too_largeThe body is over 16 KB, or 256 KB for a field schema
      415unsupported_media_typeThe body isn't sent as application/json
      422validation_failedA field schema has problems; error.fields lists them by path
      429rate_limitedOver the per-key rate limit
      500server_errorSomething failed on our side; quote request_id

      Rate limit

      Each key can make 100 requests per 60 seconds. Over the limit, the API returns 429 rate_limited with a Retry-After header in seconds. The SDK exposes it as error.retryAfter.

      Dashboard only

      API keys, members and invites, notification recipients and billing are managed in the dashboard only. A key that leaks can't create more keys, invite someone into your workspace, send email to new addresses or spend money.