Survey Data Model

Data Model Overview

Primary Entities

Survey Responses: Individual customer responses to surveys with optional overall rating

Answers: Question-level detail for each response, including free text and numeric scale answers

Key Relationships

Many-to-One: Survey Response → Shop (each response is linked to one shop)

Many-to-One: Survey Response → Customer (each response is linked to one customer)

Many-to-One: Survey Response → Survey (each response belongs to one survey)

One-to-Many: Survey Response → Answers (each response contains one or more answers)

Tip

Denormalized Structure: This endpoint returns one row per answer. A single survey response with 5 questions will produce 5 rows sharing the same STEER_SURVEY_RESPONSE_ID but with different answer fields. Use STEER_SURVEY_RESPONSE_ID to group answers back into their parent response.

Note

Question Types: Surveys support five question types — FreeText, LinearScale, OptionsSingleChoice, OptionsMultipleChoices, and ReviewButtons. The ANSWER_NUMERIC_VALUE field is only populated for LinearScale questions (range 0–100, or 0–10 for NPS). All other types store their answers in ANSWER_TEXT as a JSON array.

Field Specifications

Survey Identification

Core identification fields linking survey responses to tenants, shops, and customers.

Field Name	Data Type	Description	Required
STEER_TENANT_ID	String (UUID)	Unique tenant identifier (parent organization)	Yes
STEER_SHOP_ID	String (UUID)	Shop location identifier where the survey was issued	Yes
STEER_CUSTOMER_ID	String (UUID)	Customer identifier who submitted the response	Yes
STEER_SURVEY_ID	String (UUID)	Unique survey identifier (groups all responses for a survey)	Yes
STEER_SURVEY_RESPONSE_ID	String (UUID)	Unique survey response identifier (groups all answers for one submission)	Yes

Response Metrics

Overall response-level metrics.

Field Name	Data Type	Description	Required
SURVEY_RATING	Number	Optional overall satisfaction rating (1–5 scale). Separate from individual question answers	No
SURVEY_ANSWER_COUNT	Number	Total number of answers in this response	Yes

Timestamps

Response timing in both UTC and local timezone.

Field Name	Data Type	Description	Required
POSTED_AT	Timestamp	Response submitted timestamp (UTC)	Yes
POSTED_AT_LOCAL	Timestamp	Response submitted timestamp (shop’s local timezone)	Yes

Answer Details

Individual question/answer pair fields. Each row represents one answer within a response.

Field Name	Data Type	Description	Required
ANSWER_TYPE	String	Type of survey question (see enum values)	Yes
ANSWER_QUESTION	String	Full text of the survey question	Yes
ANSWER_TEXT	String	Submitted answer as a JSON array. Contains text for FreeText, OptionsSingleChoice, OptionsMultipleChoices, and ReviewButtons questions. Empty array [] for LinearScale questions. Max 1000 characters per answer	Yes
ANSWER_NUMERIC_VALUE	Number	Numeric answer value for LinearScale questions only (0–100, or 0–10 for NPS questions). Null for all other question types	No
ANSWER_IS_OPTIONAL	Boolean	Whether the question was optional in the survey	Yes

System Timestamps

Record lifecycle tracking.

Field Name	Data Type	Description	Required
STEER_CREATED_AT	Timestamp	Record creation timestamp in Steer	Yes
STEER_UPDATED_AT	Timestamp	Record last update timestamp in Steer	Yes

Field Enum Values

Answer Type

The ANSWER_TYPE field indicates the type of survey question (enum values in order):

• FreeText (1): Open-ended text question. Answer stored in ANSWER_TEXT as ["response text"]. ANSWER_NUMERIC_VALUE is null
• LinearScale (2): Numeric scale question (0–100, or 0–10 for NPS). Answer stored in ANSWER_NUMERIC_VALUE. ANSWER_TEXT is []
• OptionsSingleChoice (3): Single-select from predefined options. Selected option stored in ANSWER_TEXT as ["selected option"]. ANSWER_NUMERIC_VALUE is null
• OptionsMultipleChoices (4): Multi-select from predefined options. Selected options stored in ANSWER_TEXT as ["option1", "option2"]. ANSWER_NUMERIC_VALUE is null
• ReviewButtons (5): Button-based selection. Selected value stored in ANSWER_TEXT. ANSWER_NUMERIC_VALUE is null

Answer Text Format

The ANSWER_TEXT field is always a JSON array string:

• Single answer: ["Great service!"] (for FreeText, OptionsSingleChoice, ReviewButtons)
• Multiple answers: ["Friends/family", "Online search"] (for OptionsMultipleChoices)
• Empty: [] (for LinearScale questions — the value is in ANSWER_NUMERIC_VALUE instead)

Rating

The SURVEY_RATING field is an optional overall satisfaction rating, separate from individual question answers:

• Range: 1–5 integer
• 1: Very dissatisfied
• 2: Dissatisfied
• 3: Neutral
• 4: Satisfied
• 5: Very satisfied
• null: No overall rating provided (common — most surveys don’t capture this)

Data Quality Notes

Null Values

Note

Expected Null Values

• SURVEY_RATING is null when the survey does not capture an overall rating (most surveys). When present, constrained to 1–5
• ANSWER_NUMERIC_VALUE is null for all question types except LinearScale. For LinearScale, contains the numeric answer (0–100, or 0–10 for NPS questions)

Timezone Handling

Tip

Dual Timestamps: Each timestamp is provided in both UTC (POSTED_AT) and the shop’s local timezone (POSTED_AT_LOCAL). Use UTC timestamps for data processing and local timestamps for display purposes.

Row Multiplicity

Caution

One Row Per Answer: This endpoint returns denormalized data with one row per answer. A response with 7 questions produces 7 rows. When calculating response counts or aggregating metrics, always group by STEER_SURVEY_RESPONSE_ID to avoid overcounting.

Sample Record

Complete API response example with survey answer records:

{
  "data": [
    [
      "729051b5-3e17-4a63-ad9e-a7bc76af571d",
      "3282fa05-00cf-45c1-8f3a-7b9eb9a304ff",
      "c3c9f27c-9be0-4c95-bd7a-cad95858723d",
      "ae1f8b84-1132-429f-913e-63597c886d59",
      "11f4ec40-a155-44eb-b47c-610a403440fb",
      null,
      7,
      "2026-03-15T15:34:01.911000Z",
      "2026-03-15T10:34:01.911000Z",
      "FreeText",
      "We value your insights! Please share any additional feedback about your visit in the space provided.",
      "[\"Great service!\"]",
      null,
      false,
      "2026-03-15T15:34:01.911000Z",
      "2026-03-15T15:34:01.911000Z"
    ],
    [
      "729051b5-3e17-4a63-ad9e-a7bc76af571d",
      "3282fa05-00cf-45c1-8f3a-7b9eb9a304ff",
      "c3c9f27c-9be0-4c95-bd7a-cad95858723d",
      "ae1f8b84-1132-429f-913e-63597c886d59",
      "11f4ec40-a155-44eb-b47c-610a403440fb",
      null,
      7,
      "2026-03-15T15:34:01.911000Z",
      "2026-03-15T10:34:01.911000Z",
      "LinearScale",
      "On a scale of 1-5, how would you rate the cleanliness and comfort of the waiting area?",
      "[]",
      5,
      false,
      "2026-03-15T15:34:01.911000Z",
      "2026-03-15T15:34:01.911000Z"
    ]
  ],
  "metadata": {
    "rowType": [
      {"name": "STEER_TENANT_ID", "type": "text"},
      {"name": "STEER_SHOP_ID", "type": "text"},
      {"name": "STEER_CUSTOMER_ID", "type": "text"},
      {"name": "STEER_SURVEY_ID", "type": "text"},
      {"name": "STEER_SURVEY_RESPONSE_ID", "type": "text"},
      {"name": "SURVEY_RATING", "type": "fixed"},
      {"name": "SURVEY_ANSWER_COUNT", "type": "fixed"},
      {"name": "POSTED_AT", "type": "timestamp_ntz"},
      {"name": "POSTED_AT_LOCAL", "type": "timestamp_ntz"},
      {"name": "ANSWER_TYPE", "type": "text"},
      {"name": "ANSWER_QUESTION", "type": "text"},
      {"name": "ANSWER_TEXT", "type": "text"},
      {"name": "ANSWER_NUMERIC_VALUE", "type": "fixed"},
      {"name": "ANSWER_IS_OPTIONAL", "type": "boolean"},
      {"name": "STEER_CREATED_AT", "type": "timestamp_ntz"},
      {"name": "STEER_UPDATED_AT", "type": "timestamp_ntz"}
    ]
  }
}