Surface Labs Documentation

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"

Show Response Fields

type

string

required

Always "IdentityInfo" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

firstName

string

First name of the respondent.

lastName

string

Last name of the respondent.

emailAddress

string

Email address of the respondent.

workEmailAddress

string

Work email address of the respondent.

phoneNumber

string

Phone number of the respondent.

companyName

string

Company name of the respondent.

numberOfEmployees

string

Number of employees at the company.

websiteUrl

string

Website URL of the company.

title

string

Job title of the respondent.

streetAddress

string

Street address.

aptSuiteEtc

string

Apartment, suite, or other address details.

city

string

City name.

state

string

State or province.

country

string

Country name.

zipCode

string

ZIP or postal code.

companyRevenue

string

Company revenue range.

profilePictureUrl

string

URL to the profile picture.

fullName

string

Calculated full name (firstName + lastName).

readExternalStateId

string

External state ID being read.

triggerExternalStatesIds

array

Array of external state IDs to trigger.

enrichedFields

array

Array of field names that were enriched.

enrichmentType

string

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"

Show Response Fields

type

string

required

Always "MultipleOptionsQuestion" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

choices

array

required

Array of choice objects, each containing:

key

string

The choice text/value.

value

boolean

Whether this choice is selected.

index

number

Index of the choice in the list.

selectedOther

boolean

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"

Show Response Fields

type

string

required

Always "Dropdown" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

selected

string | 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"

Show Response Fields

type

string

required

Always "ShortInput" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

input

string

required

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"

Show Response Fields

type

string

required

Always "LongInput" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

input

string

required

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"

Show Response Fields

type

string

required

Always "GraphicOptions" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

index

number

required

Index of the selected option.

value

string

required

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"

Show Response Fields

type

string

required

Always "CalendlyScreen" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

autoscrolls

boolean

Whether the component autoscrolls.

eventScheduled

boolean

required

Whether an event was scheduled.

uri

string

required

Calendly URI for the scheduled event.

meetingTime

string

Meeting start time (ISO 8601 format).

meetingEndTime

string

Meeting end time (ISO 8601 format).

ownerEmails

string

Owner email address(es).

guestEmails

string

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"

Show Response Fields

type

string

required

Always "FileUploader" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

fileUrl

string

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"

Show Response Fields

type

string

required

Always "Disclaimer" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

check

boolean

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"

Show Response Fields

type

string

required

Always "Recaptcha" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

input

string

required

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"

Show Response Fields

type

string

required

Always "PasswordInput" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

input

string

required

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"

Show Response Fields

type

string

required

Always "PasswordCreatorInput" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

input

string

required

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"
  }
}

Component Type: "TurnstileWidget"

Show Response Fields

type

string

required

Always "TurnstileWidget" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

token

string

required

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"

Show Response Fields

type

string

required

Always "AiChatbot" for this component type.

componentShapeVersion

string

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

headline

string

Optional headline text displayed with the component.

leadAttribute

string

Optional lead attribute mapping for CRM integration.

summary

string

required

Summary of the conversation.

chatbotMode

string

required

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

history

string

Conversation history.

qna

string

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..."
  }
}

Surface Tag

Form Embedding

API Reference

MCP Server

Events

External Forms

Workflows

Website Visitor De-Anonymization

Tracking

Platform

Component Response Shapes

Response Structure

Identity Info

Multiple Choice Question (MCQ)

Short Input

Long Input

Graphic Options

Calendly Screen

File Uploader

Disclaimer

Recaptcha

Password Input

Password Creator Input

Turnstile Widget

AI Chatbot

​Response Structure

​Identity Info

​Multiple Choice Question (MCQ)

​Dropdown

​Short Input

​Long Input

​Graphic Options

​Calendly Screen

​File Uploader

​Disclaimer

​Recaptcha

​Password Input

​Password Creator Input

​Turnstile Widget

​AI Chatbot

Response Structure

Identity Info

Multiple Choice Question (MCQ)

Dropdown

Short Input

Long Input

Graphic Options

Calendly Screen

File Uploader

Disclaimer

Recaptcha

Password Input

Password Creator Input

Turnstile Widget

AI Chatbot