Public API overview
The JustForms public API lets you submit forms ad-hoc (web3forms-style) or programmatically create + manage forms on behalf of your customers — perfect for SaaS multi-tenant flows.
Authentication
Two equivalent methods. Both use an access key minted in your dashboard.
Bearer header (recommended)
Authorization: Bearer jf_live_abc123def456...
X-Access-Key header
X-Access-Key: jf_live_abc123def456...
Body field (for plain HTML forms only)
<input type="hidden" name="access_key" value="jf_live_...">
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /submit | Ad-hoc submission (web3forms-compatible) |
GET | /api/v1/me | Account info + quota |
GET | /api/v1/forms | List forms owned by this key |
POST | /api/v1/forms | Create a form. Returns embed snippets. |
GET | /api/v1/forms/:id | Get one form |
PUT | /api/v1/forms/:id | Update form fields |
DELETE | /api/v1/forms/:id | Delete form |
GET | /api/v1/forms/:id/submissions | List submissions for an owned form |
Scopes
Each access key has one or both of:
submit— allows POST /submit only. Use for web3forms-style integrations where you don't want clients managing forms.forms— allows /api/v1/forms/* CRUD. Use for SaaS dashboards letting customers create forms programmatically.
Rate limits + quotas
Two layers:
- Per-IP per minute — default 30, configurable per key
- Per-key monthly quota — default 1,000, configurable. Resets on the 1st UTC.
Hitting limits returns 429 Too Many Requests with body { "error": "..." }.
Common error responses
| Status | Error message | Cause |
|---|---|---|
| 401 | Missing access_key | No bearer header or hidden field |
| 401 | Invalid access_key | Key revoked or doesn't exist |
| 403 | Origin not allowed | Request from an origin not in key's allowlist |
| 403 | Recipient not in verified list | to field doesn't match key's verified recipients |
| 429 | Too many requests | Per-IP rate limit exceeded |
| 429 | Monthly quota exceeded | Key has used its monthly budget |