Forms API

Overview

The Forms API turns your ticketing setup into a form service. You build a form in the dashboard — a contact form, a refund request, a campaign entry, a sign-up — and post submissions to it from your own website or app. Every submission becomes a ticket in the same inbox your agents already work, with the answers attached, a confirmation email if you want one, and the same departments, SLAs and routing rules as any other ticket.

It is deliberately form-shaped, not ticket-shaped: no subject to invent, no required end-user id for anonymous visitors, first-class email so the receipt can always go out, and an explicit locale so the receipt is in the right language.

How It Works

1. Build the form in the dashboard under Tickets → Forms: add fields, pick the department it routes to, choose whether it creates support work, optionally cap submissions per person, then Activate it.
2. Your backend calls GET /external/v1/forms/:form_key to fetch the field definitions and renders the form on your site from that source of truth — so editing the form in the dashboard never silently drifts from what your site shows.
3. Your site posts to your backend, which relays to POST /external/v1/forms/:form_key/submissions with the answers keyed by field id.
4. We validate, enforce the per-person limit, create the ticket, snapshot the answers on it, send the receipt (if configured), and return the ticket number.

Authentication

Use your Tickets API key, minted in the dashboard at Settings → API Keys → Tickets API. Keys may be widget-scoped; a scoped key can only reach forms bound to that widget (plus org-wide forms).

Authorization: Bearer nextcap_tk_YOUR_KEY

# or, equivalently:

X-Api-Key: nextcap_tk_YOUR_KEY

Quick Start

With a form whose key is contact-us and two fields (f_topic, a select; f_message, long text):

// In your backend — never from the browser.
const res = await fetch("https://api.nextcap.ai/api/v1/external/v1/forms/contact-us/submissions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.NEXTCAP_TICKETS_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_user_id: user?.id,          // optional; makes per-person limits real
    email: "alice@acme.com",
    name: "Alice",
    locale: "en",
    origin_url: "https://acme.com/contact",
    answers: [
      { question_id: "f_topic",   value: "billing" },
      { question_id: "f_message", value: "I was charged twice for invoice #4421." },
    ],
  }),
});

const body = await res.json();
// {
//   submission_id: "…",
//   attempt_number: 1,
//   ticket: { id: "…", number: 1042 },
//   confirmation: { sent: true, locale: "en" }
// }

Identity & Per-Person Limits

A form can cap how many times one person may submit (Submissions per person in the dashboard; max_submissions in the API). To enforce that we need to know who is submitting. Resolution order, strongest first:

The limit is enforced by a unique index, not a read-then-write, so two tabs racing on the last allowed attempt cannot both get through. Attempts are numbered per person; nothing is ever deleted — an unlock voids the current attempt so the person can submit again, and the voided row stays in the record with who authorised it and why.

Confirmation Emails & the Receipt Flag

If the form has a primary email field (or you pass email) and the ticket auto-reply is configured, the submitter gets a confirmation. Only fields you explicitly mark Echo in confirmation email in the dashboard are included in it — every other answer is omitted from the email on purpose, so an ID number or account number is never reflected back into an inbox by accident. Agents still see every answer on the ticket. The response tells you whether the receipt went out and, if not, why (confirmation.sent / confirmation.reason).

Endpoints

Base URL https://api.nextcap.ai/api/v1. :form_key is the URL-safe key shown on the form in the dashboard.

const res = await fetch("https://api.nextcap.ai/api/v1/external/v1/forms/contact-us?locale=fr", {
  headers: { "Authorization": "Bearer " + process.env.NEXTCAP_TICKETS_KEY },
});
const form = await res.json();
// form.fields → render one input per field, keyed by field.id

{
  "form_key": "contact-us",
  "name": "Contact us",
  "description": null,
  "status": "active",
  "default_locale": "en",
  "max_submissions": null,
  "fields": [
    {
      "id": "f_topic",
      "type": "select",
      "label": "What is this about?",
      "description": null,
      "placeholder": null,
      "helper_url": null,
      "required": true,
      "position": 0,
      "options": [
        { "value": "billing", "label": "Billing" },
        { "value": "bug", "label": "Something is broken" }
      ],
      "validation": {}
    },
    {
      "id": "f_message",
      "type": "long_text",
      "label": "Tell us more",
      "required": true,
      "position": 1,
      "options": [],
      "validation": { "maxLength": 4000 }
    }
  ]
}

{
  "locked": false,
  "attempts_used": 0,
  "max_submissions": 1,
  "last_submission_id": null,
  "last_submitted_at": null
}

{
  "submission_id": "5c1a…",
  "attempt_number": 1,
  "ticket": { "id": "9b2f…", "number": 1042 },
  "confirmation": { "sent": true, "locale": "en" }
}

{
  "unlocked": true,
  "form_key": "contact-us",
  "voided_submission_ids": ["5c1a…"],
  "attempts_used": 0,
  "max_submissions": 1
}

Errors

Errors are { message, details } with a machine-readable message so you can surface the right field to the end user without parsing prose.

Where Submissions Show Up

• Tickets inbox — each submission is a ticket (source api) with the answers rendered on the timeline. Data-only forms still create the row, just without SLA or notifications.
• Tickets → Forms → (form) → Submissions — every attempt per person, active and voided, with a link to the ticket and an operator unlock.
• Webhooks — ticket.created fires as for any ticket; the ticket's metadata carries formId, formKey, formSubmissionId and formAttemptNumber.