HTforms
Start free

Documentation

Everything you need to embed HTforms on WordPress or call the API.

1. Install the WordPress plugin

  1. Requires WordPress 6.0+ and PHP 7.4+.
  2. Download htform.zip. In WordPress go to Plugins → Add New → Upload Plugin, choose the file, then Activate.
  3. In HTforms open WordPress & API, create an API key and copy it.
  4. In WordPress open HTforms → Connection. Paste your HTforms URL and the API key, then Save & test.
  5. Edit any page: add the HTforms block and pick a form, or paste [htform id="FORM-ID"]. Works in Elementor, Divi and others via their shortcode widget.

Security model

  • The API key is stored in WordPress options and is only used server-side. It never appears in page HTML or JavaScript.
  • Visitors submit to your own WordPress site (admin-ajax.php, protected by a nonce). WordPress forwards the entry to HTforms with the key.
  • HTforms re-validates every value against the published form and checks the form belongs to the key's workspace.

2. API reference (v1)

Base URL: https://YOUR-HTFORMS-DOMAIN/api/public/v1. Responses are JSON: { data } or { error: { code, message, fields? } }.

Authentication

Send Authorization: Bearer htf_live_…. Keys are scoped to one workspace and can be revoked any time.

GET /status

curl -H "Authorization: Bearer $KEY" https://…/api/public/v1/status
→ 200 { "data": { "connected": true, "api_version": "v1", "workspace": "Acme", "plan": "free" } }

GET /forms

Lists forms in the key's workspace (requires key).

GET /forms/:id

Returns a published form definition. Key optional; with a key, the form must belong to your workspace. Add ?view=1 to count a view.

POST /forms/:id/submissions

JSON { values: { fieldId: value }, _hp: "", _ts: 1712345678901 } or multipart form-data (needed for file uploads; use field[] for checkboxes).

curl -X POST https://…/api/public/v1/forms/$FORM/submissions \
  -H "Content-Type: application/json" \
  -d '{"values":{"name":"Ada","email":"ada@example.com","message":"Hi"}}'
→ 201 { "data": { "id": "…", "message": "Thanks!", "redirect_url": null } }

Errors

  • 401 invalid_api_key — missing, wrong or revoked key.
  • 403 forbidden — the form belongs to another workspace.
  • 404 form_not_found — not published or doesn't exist.
  • 422 validation_failed — see error.fields.
  • 429 rate_limited — 8 submissions/minute per visitor per form; 120 reads/minute per IP.
  • 402 plan_limit — monthly entry limit reached.
  • 503 temporary_failure / upload_failed — safe to retry with backoff.

Limits

Files up to 10 MB each (per-field limit configurable); executable and script file types are rejected. Requests over 25 MB are refused.

3. Troubleshooting

  • "Invalid API key" — create a new key; keys are shown only once. Check it wasn't revoked.
  • Form doesn't appear — make sure it is Published. Then use HTforms → Troubleshooting → Clear cache (forms are cached for 5 minutes).
  • Connection test fails — your host must allow outgoing HTTPS. The Troubleshooting tab shows the exact error.
  • Submissions fail behind a caching plugin — exclude admin-ajax.php; nonces refresh every 12 hours, so very long page caching can expire them.
  • Uploads rejected — check the allowed types and size on the file field.