Forms API & integration

Overview

Forms belong to a project; each definition has a human-chosen form id (slug) used by the public submit endpoint, and a MongoDB _id used by dashboard APIs.

The dashboard UI at /forms?projectId=… lists forms, opens the builder at /forms/<mongoId>?projectId=…, and shows submissions at /forms/<mongoId>/data. This page documents the HTTP API those screens call and the public endpoint third-party sites use to post leads.

Identifiers

Authentication

Dashboard APIs require a valid JWT; the public submit route does not.

• Dashboard routes (GET/POST /api/forms, GET/PUT/DELETE /api/forms/[id], GET/DELETE …/submissions): send Authorization: Bearer <JWT> with the user session token, or rely on the przio_token cookie after login.
• Project access: the user must be the project owner or a member; tool access form is enforced on list/create.
• Public submit: POST /api/forms/submit accepts JSON from any origin; CORS echoes the request Origin when present. No API key in the browser is required for submit.

REST · manage forms

Authenticated. [id] is always the Form document’s MongoDB _id.

List forms for a project

GET /api/forms?projectId=PROJECT_ID
Authorization: Bearer YOUR_SESSION_JWT

200 — { "forms": Form[] } (newest first).

Create form

POST /api/forms
Authorization: Bearer YOUR_SESSION_JWT
Content-Type: application/json

{
  "formId": "newsletter-footer",
  "name": "Newsletter signup",
  "formType": "subscription",
  "projectId": "PROJECT_ID",
  "fields": [],
  "steps": [],
  "status": "draft",
  "successClientEventEnabled": false,
  "successClientEventName": ""
}

Required: formId, name, formType, projectId. Optional: fields, steps, status, success-event flags. Custom event name must match ^[a-zA-Z0-9:_-]+$ when non-empty.

201 — { "form": Form }. Errors: duplicate formId → 400.

Get one form

GET /api/forms/FORM_MONGO_ID
Authorization: Bearer YOUR_SESSION_JWT

Update form

PUT /api/forms/FORM_MONGO_ID
Authorization: Bearer YOUR_SESSION_JWT
Content-Type: application/json

{
  "name": "Updated name",
  "fields": [ /* ... */ ],
  "status": "active",
  "successClientEventEnabled": true,
  "successClientEventName": "mystore:lead-captured"
}

Omit keys you do not want to change. To rename the slug, send "formId": "new-slug" (must stay unique).

Delete form

DELETE /api/forms/FORM_MONGO_ID
Authorization: Bearer YOUR_SESSION_JWT

200 — { "message": "Form deleted successfully" }.

REST · submit (public)

No login required. Form must exist and status must be active.

POST /api/forms/submit
Content-Type: application/json

{
  "formId": "pre-seeds",
  "data": { "email": "user@example.com" },
  "visitorId": "optional-przio-visitor-uuid",
  "isQA": false,
  "trackingType": "production"
}

• formId — slug (case-insensitive match in DB).
• data — object keyed by field name values from the form definition.
• visitorId — optional; typically from PRZIO visitor cookie for correlation.
• isQA — optional boolean for preview/test submissions.
• trackingType — optional "QA" or "production" (default production).

201 — { "message": "Form submitted successfully", "submissionId": "…" }. Server stores IP (from x-forwarded-for / x-real-ip) and user-agent.

400 — missing formId/data, or form not active. 404 — unknown formId.

REST · submissions

Authenticated; path uses Form _id.

GET /api/forms/FORM_MONGO_ID/submissions
Authorization: Bearer YOUR_SESSION_JWT

200 — { "submissions": Submission[] } sorted by submittedAt descending (matches dashboard table).

Delete submissions

DELETE /api/forms/FORM_MONGO_ID/submissions
Authorization: Bearer YOUR_SESSION_JWT
Content-Type: application/json

{ "submissionIds": ["id1", "id2"] }

Or wipe all rows:

{ "deleteAll": true }

200 — { "deletedCount": number }.

Form resource shape

Fields mirror the TypeScript model in the repo (lib/models/Form.ts).

Submission resource shape

SDK & browser events

Load sdk.min.js (or dev sdk.js) with your project id on every page that hosts an embedded form.

The minified SDK includes a small bridge that intercepts successful responses to /api/forms/submit (via fetch or XMLHttpRequest). When the embed JSON (script[type="application/json"][data-przio-form-config]) has successClientEvent.enabled === true, it dispatches:

• Always — przio:form-submit-success (detail includes formId and API response).
• Additionally — your custom event name when set and different from the default.

window.addEventListener('przio:form-submit-success', function (e) {
  console.log(e.detail); // { formId, response }
});

Embed JSON config

The bridge reads script[type="application/json"][data-przio-form-config="<formId>"]. When successClientEvent.enabled is true, events fire after a successful submit response.

Shape (conceptual):

{
  "successClientEvent": {
    "enabled": true,
    "eventName": "mystore:lead-captured"
  }
}

Implementation reference: frontend/lib/przioFormSuccessBridgeScript.ts (bundled into public SDK).

Auto-send email

Optional rules tied to a form can send email after submit when SMTP is configured.

On each successful submission, the server loads enabled AutoSendEmail rules for that form, resolves recipients (including merge tags from data and optional recipient folders), and sends via admin or user SMTP. Failures are logged to email history — configure rules in the dashboard rather than via public API here.

Field types

Each field has id, name (key in submit data), label, type, required, optional placeholder, options for choice controls, validation, and optional stepId.

Common errors

Integration checklist

• Activate the form before production traffic (status: active).
• SDK on host pages that render popup/personalization embeds.
• Re-embed after field changes so HTML + JSON config stay aligned.
• Listen for przio:form-submit-success (and custom name if configured).
• Submit payload keys must match field name values.
• Privacy — avoid logging PII in client listeners in production without policy.