API Reference

Base URL:

Text

https://api.formerie.com

This reference covers the API /v1 surface. Public hosted forms, embeds, and customer runtime hostnames use clean runtime routes on https://forms.formerie.com or verified customer hostnames:

Text

GET  /{workspaceHandle}/{formHandle}/schema
POST /{workspaceHandle}/{formHandle}/validate
POST /{workspaceHandle}/{formHandle}/submit

Workspace-bound customer hostnames use /{formHandle}/schema, /{formHandle}/validate, and /{formHandle}/submit. Form-bound hostnames use /schema, /validate, and /submit.

Health

HTTP

GET /health

JSON

{
  "ok": true,
  "service": "formerie-api",
  "version": "0.1.0"
}

Submit Form

Canonical route:

HTTP

POST /v1/{workspaceHandle}/{formHandle}

API branded route:

HTTP

POST /v1/{formHandle}

Payload:

JSON

{
  "fields": {
    "name": "Jane Example",
    "email": "jane@example.com",
    "message": "Hello"
  },
  "verificationToken": "token-from-client",
  "metadata": {
    "pageUrl": "https://example.com/contact",
    "idempotencyKey": "frontend-generated-random-uuid"
  }
}

Accepted response:

JSON

{
  "ok": true,
  "submissionId": "uuid",
  "status": "accepted"
}

Validate Fields

Validation checks provided values without storing a submission, reserving quota, verifying CAPTCHA tokens, or sending email.

HTTP

POST /v1/{workspaceHandle}/{formHandle}/validate
POST /v1/{formHandle}/validate

Public Schema

HTTP

GET /v1/{workspaceHandle}/{formHandle}/schema
GET /v1/{formHandle}/schema

The public schema endpoint is intentionally safe for browsers. It exposes field labels, types, validation hints, verification requirements, and public metadata. It does not expose recipients, provider configuration, delivery rules, templates, allowed origins, rate-limit rules, or secrets.

Final submit remains authoritative and validates the full form.

Error Shape

JSON

{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The submitted form contains invalid fields.",
    "fields": {
      "contact.email": [
        {
          "path": "contact.email",
          "code": "FIELD_EMAIL_INVALID",
          "message": "Invalid email address.",
          "rule": "email",
          "params": {}
        }
      ]
    },
    "issues": [
      {
        "path": "contact.email",
        "code": "FIELD_EMAIL_INVALID",
        "message": "Invalid email address.",
        "rule": "email",
        "params": {}
      }
    ]
  }
}

Rate-limited requests return HTTP 429 with the public error code RATE_LIMITED. When a Retry-After header is present, clients should wait at least that many seconds before retrying. Do not retry submissions in a tight loop; show a calm retry state to the visitor instead.