Forms

Forms collect structured data from your users — typically lead capture, surveys, or onboarding flows. The Forms API is read-only: forms themselves are configured in the dashboard (see the Forms feature docs), and submissions are created when users fill them out. The API lets you list forms, fetch a single form’s configuration, and read submissions.

The Form object

string

The agent that owns this form.

string

string | null

object

Configuration for built-in fields (name, email, phone, etc.) — JSON shape varies by form.

object

Configuration for custom fields the workspace has defined.

object

Configuration for survey questions, if the form is a survey form.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

The Submission object

string

string | null

Linked contact, if the submission was associated with one.

object

The submitter’s answers, keyed by field name.

boolean

true if the submission was created by an internal user (e.g. via dashboard testing). Filtered out of submission lists by default.

string

ISO 8601 timestamp.

List forms

GET

GET /api/v1/forms

Query parameters

Param	Type	Description
`bot_id`	string	Restrict to forms owned by a specific agent
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl https://clarky.ai/api/v1/forms \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "f_01HFRM...",
      "workspace_id": "w_01HXXX...",
      "bot_id": "b_01HDEF...",
      "name": "Demo Request",
      "description": "Lead capture form for the marketing site",
      "standard_fields": {
        "first_name": { "enabled": true, "required": true },
        "email": { "enabled": true, "required": true }
      },
      "custom_fields": {},
      "survey_questions": {},
      "created_at": "2026-02-10T10:00:00.000Z",
      "updated_at": "2026-04-15T08:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}

Get a form

GET

GET /api/v1/forms/{id}

Returns the full form configuration, including every standard, custom, and survey field.

Example

curl https://clarky.ai/api/v1/forms/f_01HFRM \
  -H "Authorization: Bearer ck_live_example"

{
  "data": {
    "id": "f_01HFRM...",
    "workspace_id": "w_01HXXX...",
    "bot_id": "b_01HDEF...",
    "name": "Demo Request",
    "description": "Lead capture form for the marketing site",
    "standard_fields": {
      "first_name": { "enabled": true, "required": true },
      "last_name": { "enabled": true, "required": false },
      "email": { "enabled": true, "required": true },
      "company": { "enabled": true, "required": false }
    },
    "custom_fields": {
      "team_size": {
        "label": "How big is your team?",
        "type": "select",
        "options": ["1-10", "11-50", "51-200", "200+"]
      }
    },
    "survey_questions": {},
    "created_at": "2026-02-10T10:00:00.000Z",
    "updated_at": "2026-04-15T08:00:00.000Z"
  }
}

List form submissions

GET

GET /api/v1/forms/{id}/submissions

Returns a paginated list of submissions for a single form, in reverse-chronological order.

Query parameters

Param	Type	Description
`include_internal`	boolean	Include submissions where `is_internal=true` (default `false`)
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/forms/f_01HFRM/submissions?page_size=50" \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "s_01HSUB...",
      "form_id": "f_01HFRM...",
      "contact_id": "c_01HXYZ...",
      "custom_field_responses": {
        "first_name": "Ada",
        "email": "ada@example.com",
        "company": "Analytical Engines Inc.",
        "team_size": "11-50"
      },
      "is_internal": false,
      "submitted_at": "2026-04-29T13:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 }
}

By default, submissions where is_internal=true (typically internal test fills from the dashboard) are excluded. Pass include_internal=true to see them — useful when reconciling totals against the dashboard’s “include internal” toggle.

Get a submission

GET

GET /api/v1/submissions/{id}

Example

curl https://clarky.ai/api/v1/submissions/s_01HSUB \
  -H "Authorization: Bearer ck_live_example"

{
  "data": {
    "id": "s_01HSUB...",
    "form_id": "f_01HFRM...",
    "contact_id": "c_01HXYZ...",
    "custom_field_responses": {
      "first_name": "Ada",
      "email": "ada@example.com",
      "company": "Analytical Engines Inc.",
      "team_size": "11-50"
    },
    "is_internal": false,
    "submitted_at": "2026-04-29T13:00:00.000Z"
  }
}

To get notified the moment a new submission lands — instead of polling — set up a Webhook on the contact-created or form-submission events.

Getting Started

Resources

The Form object

The Submission object

List forms

Query parameters

Example

Get a form

Example

List form submissions

Query parameters

Example

Get a submission

Example

​The Form object

​The Submission object

​List forms

​Query parameters

​Example

​Get a form

​Example

​List form submissions

​Query parameters

​Example

​Get a submission

​Example

The Form object

The Submission object

List forms

Query parameters

Example

Get a form

Example

List form submissions

Query parameters

Example

Get a submission

Example