Surface
Contact UsDashboard
HomeDocsGuides
API ReferenceResponses

Component Response Shapes

Reference documentation for all supported component response shapes

The data array in form responses contains question responses, where each response object follows a specific shape based on the component type. This page documents all supported component response shapes.

Response Structure

Each question response in the data array follows this structure:

{
  questionId: string;
  response: {
    type: string; // Component type
    componentShapeVersion?: string; // Optional version (e.g., "2.0")
    headline?: string; // Optional headline
    leadAttribute?: string; // Optional lead attribute
    // ... component-specific fields
  }
}

Identity Info

Component Type: "IdentityInfo"

›Response Fields
typestringrequired

Always "IdentityInfo" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

firstNamestring

First name of the respondent.

lastNamestring

Last name of the respondent.

emailAddressstring

Email address of the respondent.

workEmailAddressstring

Work email address of the respondent.

phoneNumberstring

Phone number of the respondent.

companyNamestring

Company name of the respondent.

numberOfEmployeesstring

Number of employees at the company.

websiteUrlstring

Website URL of the company.

titlestring

Job title of the respondent.

streetAddressstring

Street address.

aptSuiteEtcstring

Apartment, suite, or other address details.

citystring

City name.

statestring

State or province.

countrystring

Country name.

zipCodestring

ZIP or postal code.

companyRevenuestring

Company revenue range.

profilePictureUrlstring

URL to the profile picture.

fullNamestring

Calculated full name (firstName + lastName).

readExternalStateIdstring

External state ID being read.

triggerExternalStatesIdsarray

Array of external state IDs to trigger.

enrichedFieldsarray

Array of field names that were enriched.

enrichmentTypestring

Type of enrichment applied.

Example:

{
  "questionId": "identity_123",
  "response": {
    "type": "IdentityInfo",
    "componentShapeVersion": "2.0",
    "headline": "Tell us about yourself",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "companyName": "Acme Corp",
    "fullName": "John Doe"
  }
}

Multiple Choice Question (MCQ)

Component Type: "MultipleOptionsQuestion"

›Response Fields
typestringrequired

Always "MultipleOptionsQuestion" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

choicesarrayrequired

Array of choice objects, each containing:

keystring

The choice text/value.

valueboolean

Whether this choice is selected.

indexnumber

Index of the choice in the list.

selectedOtherboolean

Whether the "Other" option is selected.

Example:

{
  "questionId": "moq_123",
  "response": {
    "type": "MultipleOptionsQuestion",
    "componentShapeVersion": "2.0",
    "headline": "Select all that apply",
    "choices": [
      { "key": "Option 1", "value": true, "index": 0 },
      { "key": "Option 2", "value": false, "index": 1 },
      { "key": "Option 3", "value": true, "index": 2 }
    ],
    "selectedOther": false
  }
}

Component Type: "Dropdown"

›Response Fields
typestringrequired

Always "Dropdown" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

selectedstring | array

Selected value(s). Can be a single string for single-select dropdowns, or an array of strings for multi-select dropdowns.

Example (Single Select):

{
  "questionId": "dropdown_123",
  "response": {
    "type": "Dropdown",
    "componentShapeVersion": "2.0",
    "headline": "Select a country",
    "selected": "United States"
  }
}

Example (Multi-Select):

{
  "questionId": "dropdown_123",
  "response": {
    "type": "Dropdown",
    "componentShapeVersion": "2.0",
    "headline": "Select countries",
    "selected": ["United States", "Canada", "Mexico"]
  }
}

Short Input

Component Type: "ShortInput"

›Response Fields
typestringrequired

Always "ShortInput" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

inputstringrequired

The text input value entered by the user.

Example:

{
  "questionId": "shortinput_123",
  "response": {
    "type": "ShortInput",
    "componentShapeVersion": "2.0",
    "headline": "What's your name?",
    "input": "John Doe"
  }
}

Long Input

Component Type: "LongInput"

›Response Fields
typestringrequired

Always "LongInput" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

inputstringrequired

The textarea input value entered by the user.

Example:

{
  "questionId": "longinput_123",
  "response": {
    "type": "LongInput",
    "componentShapeVersion": "2.0",
    "headline": "Tell us more",
    "input": "This is a longer text response..."
  }
}

Graphic Options

Component Type: "GraphicOptions"

›Response Fields
typestringrequired

Always "GraphicOptions" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

indexnumberrequired

Index of the selected option.

valuestringrequired

Value/label of the selected option.

Example:

{
  "questionId": "graphic_123",
  "response": {
    "type": "GraphicOptions",
    "componentShapeVersion": "2.0",
    "headline": "Choose a plan",
    "index": 2,
    "value": "Premium Plan"
  }
}

Calendly Screen

Component Type: "CalendlyScreen"

›Response Fields
typestringrequired

Always "CalendlyScreen" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

autoscrollsboolean

Whether the component autoscrolls.

eventScheduledbooleanrequired

Whether an event was scheduled.

uristringrequired

Calendly URI for the scheduled event.

meetingTimestring

Meeting start time (ISO 8601 format).

meetingEndTimestring

Meeting end time (ISO 8601 format).

ownerEmailsstring

Owner email address(es).

guestEmailsstring

Guest email address(es).

Example:

{
  "questionId": "calendly_123",
  "response": {
    "type": "CalendlyScreen",
    "componentShapeVersion": "2.0",
    "headline": "Schedule a meeting",
    "autoscrolls": true,
    "eventScheduled": true,
    "uri": "https://calendly.com/user/meeting",
    "meetingTime": "2024-01-15T10:00:00Z",
    "meetingEndTime": "2024-01-15T10:30:00Z",
    "ownerEmails": "owner@example.com",
    "guestEmails": "guest@example.com"
  }
}

File Uploader

Component Type: "FileUploader"

›Response Fields
typestringrequired

Always "FileUploader" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

fileUrlstring

URL of the uploaded file.

Example:

{
  "questionId": "file_123",
  "response": {
    "type": "FileUploader",
    "componentShapeVersion": "2.0",
    "headline": "Upload a file",
    "fileUrl": "https://example.com/uploads/file.pdf"
  }
}

Disclaimer

Component Type: "Disclaimer"

›Response Fields
typestringrequired

Always "Disclaimer" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

checkboolean

Whether the disclaimer checkbox is checked.

Example:

{
  "questionId": "disclaimer_123",
  "response": {
    "type": "Disclaimer",
    "componentShapeVersion": "2.0",
    "headline": "Terms and Conditions",
    "check": true
  }
}

Recaptcha

Component Type: "Recaptcha"

›Response Fields
typestringrequired

Always "Recaptcha" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

inputstringrequired

The reCAPTCHA token/response.

Example:

{
  "questionId": "recaptcha_123",
  "response": {
    "type": "Recaptcha",
    "componentShapeVersion": "2.0",
    "headline": "Verify you're human",
    "input": "03AGdBq25..."
  }
}

Password Input

Component Type: "PasswordInput"

›Response Fields
typestringrequired

Always "PasswordInput" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

inputstringrequired

The password value (should be hashed/encrypted).

Example:

{
  "questionId": "password_123",
  "response": {
    "type": "PasswordInput",
    "componentShapeVersion": "2.0",
    "headline": "Enter your password",
    "input": "hashed_password_value"
  }
}

Password Creator Input

Component Type: "PasswordCreatorInput"

›Response Fields
typestringrequired

Always "PasswordCreatorInput" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

inputstringrequired

The created password value (should be hashed/encrypted).

Example:

{
  "questionId": "passwordcreator_123",
  "response": {
    "type": "PasswordCreatorInput",
    "componentShapeVersion": "2.0",
    "headline": "Create a password",
    "input": "hashed_password_value"
  }
}

Turnstile Widget

Component Type: "TurnstileWidget"

›Response Fields
typestringrequired

Always "TurnstileWidget" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

tokenstringrequired

Cloudflare Turnstile token.

Example:

{
  "questionId": "turnstile_123",
  "response": {
    "type": "TurnstileWidget",
    "componentShapeVersion": "2.0",
    "headline": "Verify with Turnstile",
    "token": "0.abcdefghijklmnop..."
  }
}

AI Chatbot

Component Type: "AiChatbot"

›Response Fields
typestringrequired

Always "AiChatbot" for this component type.

componentShapeVersionstring

Version of the component shape (e.g., "2.0").

headlinestring

Optional headline text displayed with the component.

leadAttributestring

Optional lead attribute mapping for CRM integration.

summarystringrequired

Summary of the conversation.

chatbotModestringrequired

Mode of the chatbot. Can be "Conversation" or "Questionnaire".

historystring

Conversation history.

qnastring

Q&A data if in questionnaire mode.

Example:

{
  "questionId": "aichatbot_123",
  "response": {
    "type": "AiChatbot",
    "componentShapeVersion": "2.0",
    "headline": "Chat with AI",
    "summary": "User asked about pricing and features",
    "chatbotMode": "Conversation",
    "history": "User: What are your prices?\nAI: Our pricing starts at $99/month..."
  }
}

Get Form Responses

Retrieve responses for a specific form

Overview

Connect any MCP-compatible AI assistant to Surface Forms and query your data with natural language

On this page

Response StructureIdentity InfoMultiple Choice Question (MCQ)DropdownShort InputLong InputGraphic OptionsCalendly ScreenFile UploaderDisclaimerRecaptchaPassword InputPassword Creator InputTurnstile WidgetAI Chatbot