API Reference

Installation

npm install @formtress/js

Current version: 1.0.0

submitForm(options)

Submits form data to the Formtress endpoint.

import { submitForm } from '@formtress/js'

const result = await submitForm({
  url: 'https://app.formtress.com/api/f/your-form-id',
  data: new FormData(formElement),
})

Parameters

Name	Type	Required	Description
options	object	Yes	Submission options.
options.url	string	Yes	The form’s submit URL (https://app.formtress.com/api/f/your-form-id). Typically read from form.action.
options.data	FormData	Yes	A FormData instance containing the fields to submit.

Return value

Returns Promise<SubmitResult>.

interface SubmitResult {
  ok: boolean
  message?: string
  status?: number
}

Field	Type	Description
ok	boolean	true if the submission was accepted and passed validation.
message	string | undefined	Error message from the server. Only present when ok is false.
status	number | undefined	HTTP status code from the server.

Multi-value fields

FormData natively supports multi-value fields — checkbox groups, <select multiple>, etc. Every selected value is submitted and stored comma-joined (e.g. "Web,Design"), so no special handling is needed on your side.

Webflow script

The Webflow script progressively enhances standard HTML forms that submit directly to Formtress. Forms work without JavaScript; the script adds Webflow’s native success/error states and loading text support.

CDN URL

https://cdn.jsdelivr.net/npm/@formtress/js@1.0.0/dist/js/webflow.js

Behavior

1. On DOMContentLoaded, finds all <form> elements whose action points to the Formtress submit endpoint.
2. Attaches a submit handler to each form.
3. Intercepts and prevents the default form submission.
4. Collects form data and sends it to the form’s action URL via fetch.
5. On success: triggers Webflow’s native success state.
6. On error: triggers Webflow’s error state and updates any data-ft-error element.
7. Without the script: the form submits normally via standard HTML, and spam protection still runs server-side.

Pinning a version

Always pin to a specific version in production:

<script src="https://cdn.jsdelivr.net/npm/@formtress/js@1.0.0/dist/js/webflow.js"></script>

To get the latest version automatically (not recommended for production):

<script src="https://cdn.jsdelivr.net/npm/@formtress/js@latest/dist/js/webflow.js"></script>

---

@formtress/server

npm install @formtress/server

Current version: 0.1.0

POST /public/api/v1/filter

The raw HTTP endpoint behind @formtress/server. No data is stored; this endpoint only returns a spam score.

Headers

Header	Required	Description
Authorization	Yes	Bearer ftk_<your-api-key>
Content-Type	Yes	application/json

Request body

{
  "ip": "1.2.3.4",
  "headers": Object.fromEntries(request.headers),
  "fields": [
    { "name": "email", "value": "test@gmail.com", "type": "email" },
    { "name": "message", "value": "Hello world", "type": "text" }
  ],
  "blockFreeEmailProviders": true
}

Field	Type	Required	Description
ip	string	Yes	End-user’s IP address (used for rate limiting).
headers	Record<string, string>	Yes	Forwarded request headers from the end-user’s browser.
fields	Array<{ name, value, type }>	No	Field values for content-level spam detection.
blockFreeEmailProviders	boolean	No	Flag free email providers (e.g. gmail.com) as spam. Defaults to false.

Response (200 OK)

{
  "isSpam": true,
  "score": 0.85,
  "rateLimited": false,
  "fieldErrors": {
    "email": "spam detected"
  }
}

Field	Type	Description
isSpam	boolean	Whether the submission was detected as spam.
score	number	Spam confidence score (0–1).
rateLimited	boolean	Whether the end-user was rate limited.
fieldErrors	Record<string, string>?	Per-field spam errors (only present if fields were flagged).

Response (401 Unauthorized)

{ "error": "Invalid or missing API key" }

Response (400 Bad Request)

{
  "error": "Invalid request body",
  "issues": { ... }
}

Endpoint URL

https://app.formtress.com/public/api/v1/filter