> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://typeform.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://typeform.ferndocs.com/_mcp/server.

# JSON Response Explanation

> Detailed guide to the JSON structure of Typeform responses, including all field types and metadata.

When you retrieve responses from the Responses API, the data is returned in a structured JSON format. This guide explains each component of the response structure so you can efficiently parse and work with your data.

## Response structure overview

```json
{
  "total_items": 100,
  "page_count": 10,
  "items": [...]
}
```

### Top-level properties

| Property      | Type    | Description                                |
| ------------- | ------- | ------------------------------------------ |
| `total_items` | integer | Total number of responses for the form     |
| `page_count`  | integer | Number of pages based on current page_size |
| `items`       | array   | Array of response objects                  |

## Individual response object

Each item in the `items` array represents a single form submission:

```json
{
  "landing_id": "abc123xyz789",
  "token": "abc123xyz789",
  "response_id": "abc123xyz789",
  "response_type": "completed",
  "landed_at": "2024-01-15T10:30:00Z",
  "submitted_at": "2024-01-15T10:35:25Z",
  "metadata": {
    "user_agent": "Mozilla/5.0...",
    "platform": "other",
    "referer": "https://example.com",
    "network_id": "abc123",
    "browser": "default"
  },
  "hidden": {
    "user_id": "12345",
    "source": "email"
  },
  "calculated": {
    "score": 85
  },
  "answers": [...]
}
```

### Response metadata properties

| Property        | Type   | Description                                         |
| --------------- | ------ | --------------------------------------------------- |
| `landing_id`    | string | Unique ID for when respondent first opened the form |
| `token`         | string | Unique token for this response (use for pagination) |
| `response_id`   | string | Unique ID for the completed response                |
| `response_type` | string | Either `"completed"` or `"partial"`                 |
| `landed_at`     | string | ISO 8601 timestamp when respondent opened form      |
| `submitted_at`  | string | ISO 8601 timestamp when form was submitted          |
| `metadata`      | object | Browser and platform information                    |
| `hidden`        | object | Hidden field values passed via URL parameters       |
| `calculated`    | object | Calculated values like scores                       |
| `answers`       | array  | Array of question-answer pairs                      |

## Metadata object

The `metadata` object contains information about how the form was accessed:

```json
{
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "platform": "other",
  "referer": "https://example.com/landing-page",
  "network_id": "abc123def456",
  "browser": "default"
}
```

| Property     | Description                                   |
| ------------ | --------------------------------------------- |
| `user_agent` | Full user agent string from the browser       |
| `platform`   | Device platform (`mobile`, `tablet`, `other`) |
| `referer`    | URL where the respondent came from            |
| `network_id` | Internal network identifier                   |
| `browser`    | Browser type (often `"default"`)              |

## Hidden fields object

Hidden fields passed via URL parameters appear in the `hidden` object:

```json
{
  "user_id": "12345",
  "source": "email_campaign",
  "utm_source": "newsletter",
  "utm_medium": "email"
}
```

These correspond to the Hidden Fields you defined when creating your form.

## Calculated object

Contains calculated values based on form logic:

```json
{
  "score": 85
}
```

Currently, the main calculated value is `score` for forms with scoring enabled.

## Answers array

The `answers` array contains all question-answer pairs. Each answer object has a specific structure based on the field type.

### Answer object structure

```json
{
  "field": {
    "id": "field_abc123",
    "type": "short_text",
    "ref": "customer_name"
  },
  "type": "text",
  "text": "John Smith"
}
```

Common properties:

* `field`: Information about the question
  * `id`: Unique field ID
  * `type`: Field type
  * `ref`: Custom reference you assigned
* `type`: Answer data type
* Answer value in type-specific property

## Field types and answer formats

### Short text / Long text

```json
{
  "field": {
    "id": "field1",
    "type": "short_text",
    "ref": "name"
  },
  "type": "text",
  "text": "John Smith"
}
```

### Email

```json
{
  "field": {
    "id": "field2",
    "type": "email",
    "ref": "email_address"
  },
  "type": "email",
  "email": "john@example.com"
}
```

### Website / URL

```json
{
  "field": {
    "id": "field3",
    "type": "website",
    "ref": "company_website"
  },
  "type": "url",
  "url": "https://example.com"
}
```

### Phone number

```json
{
  "field": {
    "id": "field4",
    "type": "phone_number",
    "ref": "phone"
  },
  "type": "phone_number",
  "phone_number": "+1-555-0123"
}
```

### Number

```json
{
  "field": {
    "id": "field5",
    "type": "number",
    "ref": "employee_count"
  },
  "type": "number",
  "number": 50
}
```

### Multiple choice (single selection)

```json
{
  "field": {
    "id": "field6",
    "type": "multiple_choice",
    "ref": "product_interest"
  },
  "type": "choice",
  "choice": {
    "id": "choice_xyz",
    "label": "Product A",
    "ref": "product_a"
  }
}
```

### Multiple choice (multiple selections)

```json
{
  "field": {
    "id": "field7",
    "type": "multiple_choice",
    "ref": "interests"
  },
  "type": "choices",
  "choices": {
    "ids": ["choice1", "choice2"],
    "labels": ["Design", "Development"],
    "refs": ["design", "development"]
  }
}
```

### Dropdown

```json
{
  "field": {
    "id": "field8",
    "type": "dropdown",
    "ref": "country"
  },
  "type": "choice",
  "choice": {
    "id": "choice_usa",
    "label": "United States",
    "ref": "usa"
  }
}
```

### Yes/No

```json
{
  "field": {
    "id": "field9",
    "type": "yes_no",
    "ref": "subscribe"
  },
  "type": "boolean",
  "boolean": true
}
```

### Rating (stars, hearts, etc.)

```json
{
  "field": {
    "id": "field10",
    "type": "rating",
    "ref": "satisfaction"
  },
  "type": "number",
  "number": 5
}
```

### Opinion scale

```json
{
  "field": {
    "id": "field11",
    "type": "opinion_scale",
    "ref": "nps_score"
  },
  "type": "number",
  "number": 9
}
```

### Date

```json
{
  "field": {
    "id": "field12",
    "type": "date",
    "ref": "appointment_date"
  },
  "type": "date",
  "date": "2024-03-15"
}
```

### File upload

```json
{
  "field": {
    "id": "field13",
    "type": "file_upload",
    "ref": "resume"
  },
  "type": "file_url",
  "file_url": "https://api.typeform.com/forms/{form_id}/responses/{response_id}/fields/{field_id}/files/resume.pdf"
}
```

### Picture choice

```json
{
  "field": {
    "id": "field14",
    "type": "picture_choice",
    "ref": "style_preference"
  },
  "type": "choice",
  "choice": {
    "id": "choice_modern",
    "label": "Modern Style",
    "ref": "modern"
  }
}
```

### Legal consent

```json
{
  "field": {
    "id": "field15",
    "type": "legal",
    "ref": "terms_agreement"
  },
  "type": "boolean",
  "boolean": true
}
```

### Payment

```json
{
  "field": {
    "id": "field16",
    "type": "payment",
    "ref": "payment"
  },
  "type": "payment",
  "payment": {
    "amount": "99.99",
    "last4": "4242",
    "name": "John Smith",
    "success": true,
    "currency": "USD",
    "transaction_id": "ch_1ABC123xyz"
  }
}
```

### Ranking

```json
{
  "field": {
    "id": "field17",
    "type": "ranking",
    "ref": "priorities"
  },
  "type": "choices",
  "choices": {
    "labels": ["Speed", "Quality", "Price"]
  }
}
```

## Complete example response

```json
{
  "total_items": 1,
  "page_count": 1,
  "items": [
    {
      "landing_id": "abc123xyz",
      "token": "abc123xyz",
      "response_id": "abc123xyz",
      "response_type": "completed",
      "landed_at": "2024-01-15T10:30:00Z",
      "submitted_at": "2024-01-15T10:35:25Z",
      "metadata": {
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "platform": "other",
        "referer": "https://example.com",
        "network_id": "abc123",
        "browser": "default"
      },
      "hidden": {
        "user_id": "12345",
        "source": "email"
      },
      "calculated": {
        "score": 85
      },
      "answers": [
        {
          "field": {
            "id": "field1",
            "type": "short_text",
            "ref": "name"
          },
          "type": "text",
          "text": "John Smith"
        },
        {
          "field": {
            "id": "field2",
            "type": "email",
            "ref": "email"
          },
          "type": "email",
          "email": "john@example.com"
        },
        {
          "field": {
            "id": "field3",
            "type": "multiple_choice",
            "ref": "satisfaction"
          },
          "type": "choice",
          "choice": {
            "id": "choice_satisfied",
            "label": "Very Satisfied",
            "ref": "very_satisfied"
          }
        },
        {
          "field": {
            "id": "field4",
            "type": "opinion_scale",
            "ref": "nps"
          },
          "type": "number",
          "number": 9
        }
      ]
    }
  ]
}
```

## Working with response data

### Accessing answers by reference

```javascript
function getAnswerByRef(response, ref) {
  const answer = response.answers.find((a) => a.field.ref === ref);

  if (!answer) return null;

  // Return the appropriate value based on type
  switch (answer.type) {
    case 'text':
      return answer.text;
    case 'email':
      return answer.email;
    case 'number':
      return answer.number;
    case 'choice':
      return answer.choice.label;
    case 'choices':
      return answer.choices.labels;
    case 'boolean':
      return answer.boolean;
    // ... handle other types
    default:
      return answer;
  }
}

// Usage
const customerName = getAnswerByRef(response, 'name');
const email = getAnswerByRef(response, 'email');
```

### Type checking

```javascript
function isCompletedResponse(response) {
  return (
    response.response_type === 'completed' && response.submitted_at !== null
  );
}

function getCompletionTime(response) {
  const landed = new Date(response.landed_at);
  const submitted = new Date(response.submitted_at);
  return (submitted - landed) / 1000; // seconds
}
```

## Best practices

1. **Use refs for lookups**: Reference answers by `ref` rather than field ID for maintainability
2. **Check answer types**: Always verify answer type before accessing type-specific properties
3. **Handle missing answers**: Questions can be optional, so answers might not exist
4. **Parse dates correctly**: Use proper date parsing for timestamp fields
5. **Cache field mappings**: Build a lookup table of refs to field types for efficient processing

## Next steps

* See [Walkthroughs](/responses-api/walkthroughs) for practical examples
* Learn about [filtering responses](/responses-api/walkthroughs#filter-and-paginate-responses)
* Implement [Right to be Forgotten](/responses-api/right-to-be-forgotten) for data compliance
* Check the [API Reference](/api-reference) for complete endpoint details