Forms

Forms allow you to create structured data collection endpoints. Define form fields as a typed schema, then collect submissions from your users. Submissions can trigger workflows (e.g. send a notification email on contact form submission).

Create Form

const form = await sdk.form.createForm({
  key: 'contact',
  schema: [
    { type: 'text', id: 'fld_name', key: 'name', required: true },
    { type: 'text', id: 'fld_email', key: 'email', required: true },
    { type: 'text', id: 'fld_message', key: 'message', required: true },
  ],
});

Schema Field Types

Type	Extra options
text	required
number	required, min, max
boolean	required
date	required
geo_location	required
select	required, options: string[]

Response

{
  "id": "form_abc123",
  "key": "contact",
  "businessId": "biz_123",
  "schema": [
    { "type": "text", "id": "fld_name", "key": "name", "required": true },
    { "type": "text", "id": "fld_email", "key": "email", "required": true },
    { "type": "text", "id": "fld_message", "key": "message", "required": true }
  ],
  "status": "active",
  "createdAt": 1704067200,
  "updatedAt": 1704067200
}

Get Form

Retrieve a form by ID or key.

// By ID
const form = await sdk.form.getForm({ id: 'form_abc123' });

// By key
const form = await sdk.form.getForm({ key: 'contact' });

List Forms

const { items, cursor } = await sdk.form.getForms({
  status: 'active',
  limit: 20,
});

Update Form

await sdk.form.updateForm({
  id: 'form_abc123',
  schema: [
    { type: 'text', id: 'fld_name', key: 'name', required: true },
    { type: 'text', id: 'fld_email', key: 'email', required: true },
    { type: 'text', id: 'fld_phone', key: 'phone', required: false },
    { type: 'text', id: 'fld_message', key: 'message', required: true },
  ],
});

Delete Form

Deletes the form and all its submissions.

await sdk.form.deleteForm({ id: 'form_abc123' });

Submit Form

Submit data to a form. This endpoint is public and is typically called from your frontend by end users.

await sdk.form.submit({
  formId: 'form_abc123',
  fields: [
    { type: 'text', id: 'fld_name', key: 'name', value: 'Jane Doe' },
    { type: 'text', id: 'fld_email', key: 'email', value: 'jane@example.com' },
    { type: 'text', id: 'fld_message', key: 'message', value: 'Hello, I have a question...' },
  ],
});

Get Submissions

List submissions for a form (admin only).

const { items, cursor } = await sdk.form.getSubmissions({
  formId: 'form_abc123',
  limit: 50,
});

items.forEach(submission => {
  const name = submission.fields.find(f => f.key === 'name')?.value;
  console.log(submission.id, name, submission.createdAt);
});

Get Single Submission

const submission = await sdk.form.getSubmission({
  formId: 'form_abc123',
  id: 'sub_xyz789',
});

Submission Response

{
  "id": "sub_xyz789",
  "formId": "form_abc123",
  "businessId": "biz_123",
  "fields": [
    { "type": "text", "id": "fld_name", "key": "name", "value": "Jane Doe" },
    { "type": "text", "id": "fld_email", "key": "email", "value": "jane@example.com" },
    { "type": "text", "id": "fld_message", "key": "message", "value": "Hello!" }
  ],
  "createdAt": 1704067200
}

Update Submission

Edit a previously collected submission (admin only).

await sdk.form.updateSubmission({
  formId: 'form_abc123',
  id: 'sub_xyz789',
  fields: [
    { type: 'text', id: 'fld_name', key: 'name', value: 'Jane D.' },
    { type: 'text', id: 'fld_email', key: 'email', value: 'jane@example.com' },
    { type: 'text', id: 'fld_message', key: 'message', value: 'Updated message' },
  ],
});

Default Forms

Every new business is created with 3 default forms:

Key	Purpose
contact	Contact form
booking-intake	Booking intake form
order-notes	Order notes form