Skip to navigation

JSON Response Explanation

Understanding the structure of Typeform response data

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

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

Top-level properties

PropertyTypeDescription
total_itemsintegerTotal number of responses for the form
page_countintegerNumber of pages based on current page_size
itemsarrayArray of response objects

Individual response object

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

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

PropertyTypeDescription
landing_idstringUnique ID for when respondent first opened the form
tokenstringUnique token for this response (use for pagination)
response_idstringUnique ID for the completed response
response_typestringEither "completed" or "partial"
landed_atstringISO 8601 timestamp when respondent opened form
submitted_atstringISO 8601 timestamp when form was submitted
metadataobjectBrowser and platform information
hiddenobjectHidden field values passed via URL parameters
calculatedobjectCalculated values like scores
answersarrayArray of question-answer pairs

Metadata object

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

{
  "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"
}
PropertyDescription
user_agentFull user agent string from the browser
platformDevice platform (mobile, tablet, other)
refererURL where the respondent came from
network_idInternal network identifier
browserBrowser type (often "default")

Hidden fields object

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

{
  "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:

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

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

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

Email

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

Website / URL

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

Phone number

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

Number

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

Multiple choice (single selection)

{
  "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)

{
  "field": {
    "id": "field7",
    "type": "multiple_choice",
    "ref": "interests"
  },
  "type": "choices",
  "choices": {
    "ids": ["choice1", "choice2"],
    "labels": ["Design", "Development"],
    "refs": ["design", "development"]
  }
}
{
  "field": {
    "id": "field8",
    "type": "dropdown",
    "ref": "country"
  },
  "type": "choice",
  "choice": {
    "id": "choice_usa",
    "label": "United States",
    "ref": "usa"
  }
}

Yes/No

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

Rating (stars, hearts, etc.)

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

Opinion scale

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

Date

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

File upload

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

{
  "field": {
    "id": "field14",
    "type": "picture_choice",
    "ref": "style_preference"
  },
  "type": "choice",
  "choice": {
    "id": "choice_modern",
    "label": "Modern Style",
    "ref": "modern"
  }
}
{
  "field": {
    "id": "field15",
    "type": "legal",
    "ref": "terms_agreement"
  },
  "type": "boolean",
  "boolean": true
}

Payment

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

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

Complete example response

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

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

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