API reference · Forms

Forms and submissions

Create studio-owned form definitions, conditional questions, and submissions that use the same records as ClassFlow widgets.

Endpoints7

Primary objectFormObject

Tenant boundaryCredential studio

GET/forms

List forms

Lists published forms by default. Authorized form managers can include drafts.

Required scope: forms:read
Success: 200
Response: Page<FormObject>

Parameters

include_draftsquery

boolean

Include draft and archived forms. Defaults to false.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/forms" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "object": "list",
  "data": [{
    "id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
    "object": "form",
    "title": "Child-care interest",
    "slug": "child-care-interest",
    "fields": [
      { "key": "child_care_help", "label": "Would child care help you visit JUX?", "type": "select", "options_layout": "buttons", "options": ["Yes", "Maybe", "No", "Not now"], "required": true },
      { "key": "child_count", "label": "Number of children", "type": "select", "options": ["1", "2", "3+"], "display_when": { "field_key": "child_care_help", "op": "in", "value": ["Yes", "Maybe"] } }
    ],
    "settings": { "confirmation_message": "Thanks — we saved your answers." },
    "status": "published"
  }],
  "has_more": false,
  "next_cursor": null
}

POST/forms

Create a form

Creates a draft or published studio form through the canonical form service.

Required scope: forms:write
Success: 201
Response: FormObject

Request body

Send a JSON object matching PartnerFormCreate.

application/json

{
  "title": "Child-care interest",
  "slug": "child-care-interest",
  "status": "published",
  "fields": [
    {
      "key": "child_care_help",
      "label": "Would child care help you visit JUX?",
      "type": "select",
      "required": true,
      "options_layout": "buttons",
      "options": ["Yes", "Maybe", "No", "Not now"]
    },
    {
      "key": "child_count",
      "label": "Number of children",
      "type": "select",
      "options": ["1", "2", "3+"],
      "display_when": {
        "field_key": "child_care_help",
        "op": "in",
        "value": ["Yes", "Maybe"]
      }
    }
  ]
}

Example request

curl -X POST "https://api.getclassflow.com/partner/v1/forms" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "Child-care interest",
  "slug": "child-care-interest",
  "status": "published",
  "fields": [
    {
      "key": "child_care_help",
      "label": "Would child care help you visit JUX?",
      "type": "select",
      "required": true,
      "options_layout": "buttons",
      "options": ["Yes", "Maybe", "No", "Not now"]
    },
    {
      "key": "child_count",
      "label": "Number of children",
      "type": "select",
      "options": ["1", "2", "3+"],
      "display_when": {
        "field_key": "child_care_help",
        "op": "in",
        "value": ["Yes", "Maybe"]
      }
    }
  ]
}'

Example response

201 · application/json

{
  "id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
  "object": "form",
  "title": "Child-care interest",
  "slug": "child-care-interest",
  "fields": [
    { "key": "child_care_help", "label": "Would child care help you visit JUX?", "type": "select", "options_layout": "buttons", "options": ["Yes", "Maybe", "No", "Not now"], "required": true },
    { "key": "child_count", "label": "Number of children", "type": "select", "options": ["1", "2", "3+"], "display_when": { "field_key": "child_care_help", "op": "in", "value": ["Yes", "Maybe"] } }
  ],
  "settings": { "confirmation_message": "Thanks — we saved your answers." },
  "status": "published"
}

PUT/forms/{form_id}

Update a form

Replaces supplied form properties while preserving the studio and form identity.

Required scope: forms:write
Success: 200
Response: FormObject

Parameters

form_idpathrequired

uuid

The stable ClassFlow identifier for the form.

Request body

Send a JSON object matching StudioFormUpdate.

application/json

{
  "status": "published",
  "settings": {
    "confirmation_message": "Thanks — we saved your answers."
  }
}

Example request

curl -X PUT "https://api.getclassflow.com/partner/v1/forms/YOUR_FORM_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "status": "published",
  "settings": {
    "confirmation_message": "Thanks — we saved your answers."
  }
}'

Example response

200 · application/json

{
  "id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
  "object": "form",
  "title": "Child-care interest",
  "slug": "child-care-interest",
  "fields": [
    { "key": "child_care_help", "label": "Would child care help you visit JUX?", "type": "select", "options_layout": "buttons", "options": ["Yes", "Maybe", "No", "Not now"], "required": true },
    { "key": "child_count", "label": "Number of children", "type": "select", "options": ["1", "2", "3+"], "display_when": { "field_key": "child_care_help", "op": "in", "value": ["Yes", "Maybe"] } }
  ],
  "settings": { "confirmation_message": "Thanks — we saved your answers." },
  "status": "published"
}

GET/forms/{form_id}

Retrieve a form

Returns one form definition, including fields, conditions, settings, and status.

Required scope: forms:read
Success: 200
Response: FormObject

Parameters

form_idpathrequired

uuid

The stable ClassFlow identifier for the form.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/forms/YOUR_FORM_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
  "object": "form",
  "title": "Child-care interest",
  "slug": "child-care-interest",
  "fields": [
    { "key": "child_care_help", "label": "Would child care help you visit JUX?", "type": "select", "options_layout": "buttons", "options": ["Yes", "Maybe", "No", "Not now"], "required": true },
    { "key": "child_count", "label": "Number of children", "type": "select", "options": ["1", "2", "3+"], "display_when": { "field_key": "child_care_help", "op": "in", "value": ["Yes", "Maybe"] } }
  ],
  "settings": { "confirmation_message": "Thanks — we saved your answers." },
  "status": "published"
}

GET/forms/{form_id}/submissions

List form submissions

Lists submissions for one studio-owned form.

Required scope: form_submissions:read
Success: 200
Response: Page<FormSubmissionObject>

Parameters

form_idpathrequired

uuid

The stable ClassFlow identifier for the form.

cursorquery

uuid

Opaque cursor returned by the previous page. Pass it back unchanged.

limitquery

integer

Number of records to return. Defaults to 50; maximum 200.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/forms/YOUR_FORM_ID/submissions" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "object": "list",
  "data": [{
    "id": "8350c2ed-aee7-4f52-8745-45765f899518",
    "object": "form_submission",
    "form_id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
    "submitter_email": "randy@example.com",
    "data": {
      "child_care_help": "Yes",
      "child_count": "2"
    },
    "status": "pending",
    "created_at": "2026-08-02T20:35:00Z"
  }],
  "has_more": false,
  "next_cursor": null
}

POST/forms/{form_id}/submissions

Create a form submission

Validates and stores answers through the same submission flow used by the widget.

Required scope: form_submissions:write
Success: 201
Response: FormSubmissionObject

Parameters

form_idpathrequired

uuid

The stable ClassFlow identifier for the form.

Request body

Send a JSON object matching FormSubmissionCreate.

application/json

{
  "submitter_name": "Randy Example",
  "submitter_email": "randy@example.com",
  "data": {
    "child_care_help": "Yes",
    "child_count": "2",
    "age_ranges": ["1–2", "3–5"]
  }
}

Example request

curl -X POST "https://api.getclassflow.com/partner/v1/forms/YOUR_FORM_ID/submissions" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "submitter_name": "Randy Example",
  "submitter_email": "randy@example.com",
  "data": {
    "child_care_help": "Yes",
    "child_count": "2",
    "age_ranges": ["1–2", "3–5"]
  }
}'

Example response

201 · application/json

{
  "id": "8350c2ed-aee7-4f52-8745-45765f899518",
  "object": "form_submission",
  "form_id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
  "submitter_email": "randy@example.com",
  "data": {
    "child_care_help": "Yes",
    "child_count": "2"
  },
  "status": "pending",
  "created_at": "2026-08-02T20:35:00Z"
}

GET/forms/{form_id}/submissions/{submission_id}

Retrieve a form submission

Returns one submission only when both the form and submission belong to the credential’s studio.

Required scope: form_submissions:read
Success: 200
Response: FormSubmissionObject

Parameters

form_idpathrequired

uuid

The stable ClassFlow identifier for the form.

submission_idpathrequired

uuid

The stable ClassFlow identifier for the submission.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/forms/YOUR_FORM_ID/submissions/YOUR_SUBMISSION_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "id": "8350c2ed-aee7-4f52-8745-45765f899518",
  "object": "form_submission",
  "form_id": "9fc7be37-507a-46f6-a9a2-85fda0ac7342",
  "submitter_email": "randy@example.com",
  "data": {
    "child_care_help": "Yes",
    "child_count": "2"
  },
  "status": "pending",
  "created_at": "2026-08-02T20:35:00Z"
}

Object schema

FormObject

Full OpenAPI schema

fields[].keystring

Stable answer key used in submissions and conditional rules.

fields[].typeenum

text, textarea, number, email, phone, date, select, checkbox, checkbox_group, signature, file_upload, address, rating, section_break, or consent.

fields[].display_whenConditionalRule | null

Optional field_key, operator, and value rule controlling visibility.

fields[].step_indexinteger | null

Optional multi-step grouping.

settingsFormSettings

Authentication, notifications, confirmation, and redirect behavior.

statusdraft | published | archived

Publishing state.