API Reference

The RizzForms API is organized into two groups: Ingest Endpoints (public, no auth required) for receiving form submissions, and API Endpoints (authenticated) for managing forms, submissions, and plugins. All responses are JSON. The base URL is https://forms.rizzness.com.

Authentication

API endpoints require a Bearer token in the Authorization header. API keys are created from the dashboard and use the frk_ prefix. Ingest endpoints are public and do not require authentication.

Authorization: Bearer frk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

See Authentication for details on permissions, roles, and error handling.

Ingest Endpoints

These public endpoints receive form submissions. No API key is required.

POST /f/:endpoint_token

Accepts standard HTML form submissions (application/x-www-form-urlencoded or multipart/form-data). On success, redirects the browser to the thank-you page or a custom success_redirect_url if configured.

curl -s -X POST https://forms.rizzness.com/f/abc123def456 \
  -d "name=Jane+Smith" \
  -d "[email protected]" \
  -d "message=Hello"

Response: 302 Found redirect to https://forms.rizzness.com/f/abc123def456/thanks (default) or your custom redirect URL.

POST /json/:endpoint_token

Accepts JSON submissions. Returns a JSON response with the submission ID and HATEOAS links.

curl -s -X POST https://forms.rizzness.com/json/abc123def456 \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "email": "[email protected]"}'

Response:

{
  "ok": true,
  "id": 789,
  "links": [
    { "rel": "submission", "href": "https://www.rizzness.com/api/submissions/789" },
    { "rel": "form", "href": "https://www.rizzness.com/api/forms/abc123def456" }
  ]
}

Add ?test=true for synchronous plugin delivery. The response will include feedback from each plugin:

curl -s -X POST "https://forms.rizzness.com/json/abc123def456?test=true" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

API Root

GET /api/

Returns the HATEOAS root with your account ID and links to all available resources.

Auth: Bearer token required.

curl -s https://www.rizzness.com/api/ \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "account_id": 1,
  "links": [
    { "rel": "forms", "href": "https://www.rizzness.com/api/forms" },
    { "rel": "submissions", "href": "https://www.rizzness.com/api/submissions" },
    { "rel": "spam", "href": "https://www.rizzness.com/api/submissions/spam" }
  ]
}

Forms

POST /api/forms

Create a new form.

Auth: Bearer token required. Permission: can_create_forms.

curl -s -X POST https://www.rizzness.com/api/forms \
  -H "Authorization: Bearer frk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact Form"}'

Request body:

{
  "name": "Contact Form"
}

Response:

{
  "ok": true,
  "form": {
    "id": 42,
    "name": "Contact Form",
    "endpoint_token": "abc123def456",
    "submission_url": "https://forms.rizzness.com/f/abc123def456",
    "json_url": "https://forms.rizzness.com/json/abc123def456",
    "embed_html": "<form action=\"https://forms.rizzness.com/f/abc123def456\" method=\"POST\">...</form>",
    "submission_count": 0,
    "submission_spam_count": 0,
    "last_submission_at": null
  }
}

GET /api/forms

List all forms in your account.

Auth: Bearer token required.

curl -s https://www.rizzness.com/api/forms \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "forms": [
    {
      "id": 42,
      "name": "Contact Form",
      "endpoint_token": "abc123def456",
      "submission_url": "https://forms.rizzness.com/f/abc123def456",
      "json_url": "https://forms.rizzness.com/json/abc123def456",
      "embed_html": "<form action=\"...\" method=\"POST\">...</form>",
      "submission_count": 150,
      "submission_spam_count": 3,
      "last_submission_at": "2026-03-22T14:30:00Z",
      "examples": { "curl": "curl -X POST ..." },
      "help": "https://forms.rizzness.com/docs/getting-started"
    }
  ]
}

GET /api/forms/:id

Get a single form by its endpoint_token.

Auth: Bearer token required.

curl -s https://www.rizzness.com/api/forms/abc123def456 \
  -H "Authorization: Bearer frk_your_api_key"

Response: Same fields as a single item in the list response above.

PATCH /api/forms/:id

Update a form's settings.

Auth: Bearer token required. Permission: can_create_forms.

Updatable fields:

name — form display name
success_redirect_url — custom URL to redirect to after submission
is_active — true or false to enable/disable the form
notification_email_addresses — array of email addresses for submission notifications

curl -s -X PATCH https://www.rizzness.com/api/forms/abc123def456 \
  -H "Authorization: Bearer frk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Contact Form",
    "success_redirect_url": "https://yoursite.com/thank-you",
    "is_active": true,
    "notification_email_addresses": ["[email protected]"]
  }'

Response: The updated form object.

Submissions

GET /api/submissions

List non-spam submissions. Returns up to 500 results.

Auth: Bearer token required. Permission: can_read_submissions.

Query parameters:

form_id — filter by form endpoint token
range — time range: 24h, 7d, or 30d
q — full-text search across submission data

curl -s "https://www.rizzness.com/api/submissions?form_id=abc123def456&range=7d" \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "submissions": [
    {
      "id": 789,
      "form_id": 42,
      "payload_json": { "name": "Jane Smith", "email": "[email protected]" },
      "created_at": "2026-03-22T14:30:00Z"
    }
  ]
}

GET /api/submissions/:id

Get a single submission with full details.

Auth: Bearer token required. Permission: can_read_submissions.

curl -s https://www.rizzness.com/api/submissions/789 \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "submission": {
    "id": 789,
    "form_id": 42,
    "payload_json": { "name": "Jane Smith", "email": "[email protected]" },
    "special_normalized": { "email": "[email protected]" },
    "source_ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ...",
    "referrer": "https://yoursite.com/contact",
    "created_at": "2026-03-22T14:30:00Z"
  }
}

GET /api/submissions/spam

List spam submissions. Supports the same query parameters as the non-spam endpoint. Returns up to 500 results.

Auth: Bearer token required. Permission: can_read_spam_submissions.

curl -s "https://www.rizzness.com/api/submissions/spam?form_id=abc123def456&range=30d" \
  -H "Authorization: Bearer frk_your_api_key"

Response: Same structure as the non-spam submissions list.

Plugins

Plugins deliver submissions to external services. The API currently supports creating webhook plugins only. Other plugin types (Slack, Google Sheets, email forwarding, etc.) are managed through the dashboard.

GET /api/forms/:form_id/plugins

List all plugins configured on a form.

Auth: Bearer token required.

curl -s https://www.rizzness.com/api/forms/abc123def456/plugins \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "plugins": [
    {
      "id": 5,
      "plugin_type": "webhook",
      "config": { "url": "https://yoursite.com/webhooks/forms" },
      "created_at": "2026-03-20T10:00:00Z"
    }
  ]
}

POST /api/forms/:form_id/plugins

Create a webhook plugin on a form.

Auth: Bearer token required. Permission: can_create_forms.

curl -s -X POST https://www.rizzness.com/api/forms/abc123def456/plugins \
  -H "Authorization: Bearer frk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"plugin_type": "webhook", "config": {"url": "https://yoursite.com/webhooks/forms"}}'

Request body:

{
  "plugin_type": "webhook",
  "config": {
    "url": "https://yoursite.com/webhooks/forms"
  }
}

Response:

{
  "ok": true,
  "plugin": {
    "id": 5,
    "plugin_type": "webhook",
    "config": { "url": "https://yoursite.com/webhooks/forms" },
    "signing_secret": "whsec_a1b2c3d4e5f6g7h8..."
  }
}

Important: The signing_secret is shown only once in the creation response. Store it securely for verifying the X-RizzForms-Signature header on incoming webhooks.

DELETE /api/forms/:form_id/plugins/:id

Remove a plugin from a form.

Auth: Bearer token required. Permission: can_create_forms.

curl -s -X DELETE https://www.rizzness.com/api/forms/abc123def456/plugins/5 \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "message": "Plugin removed."
}

POST /api/forms/:form_id/plugins/:id/rotate_secret

Rotate the signing secret for a webhook plugin. The old secret is immediately invalidated and a new one is returned.

Auth: Bearer token required. Permission: can_create_forms.

curl -s -X POST https://www.rizzness.com/api/forms/abc123def456/plugins/5/rotate_secret \
  -H "Authorization: Bearer frk_your_api_key"

Response:

{
  "ok": true,
  "signing_secret": "whsec_new_secret_value..."
}

Stats

GET /api/stats

Returns high-level account statistics. This endpoint is available only via session authentication (browser dashboard) and does not support API key access.

Auth: Session cookie required (browser only).

curl -s https://www.rizzness.com/api/stats \
  --cookie "session=..."

Response:

{
  "ok": true,
  "stats": {
    "totalForms": 12,
    "active": 10,
    "subs24h": 47,
    "subs7d": 312
  }
}