Customer Data Model

Data Model Overview

🏗️ Primary Entities

Customers: Individual or business customers with personal info, addresses, and preferences

Contacts: Primary and secondary email and phone records

Consent: Subscription and communication consent statuses

🔗 Key Relationships

Many-to-One: Customer → Tenant (each customer belongs to one tenant)

Many-to-One: Customer → Shop (primary shop assignment)

Field Specifications

Customer Identification

Core identification fields linking customers to tenants and shops.

Field Name	Data Type	Description	Required
STEER_TENANT_ID	String (UUID)	Unique tenant identifier (parent organization)	Yes
STEER_SHOP_ID	String (UUID)	Primary shop location identifier	Yes
STEER_CUSTOMER_ID	String (UUID)	Unique customer identifier	Yes
EXTERNAL_CUSTOMER_ID	String	Customer identifier(s) in the external source system (shop management system). When a customer maps to multiple current external records, the identifiers are returned as a comma-separated list (delimiter is , — comma followed by a space), sorted ascending	No

Personal Information

Customer name and classification details.

Field Name	Data Type	Description	Required
CUSTOMER_FIRST_NAME	String	Customer first name	No
CUSTOMER_LAST_NAME	String	Customer last name	No
CUSTOMER_COMPANY_NAME	String	Company name (for business customers)	No
CUSTOMER_TYPE	String	Customer classification type	Yes

Customer Address

Physical address with geolocation and validation status.

Field Name	Data Type	Description	Required
CUSTOMER_ADDRESS_1	String	Primary street address	No
CUSTOMER_ADDRESS_2	String	Secondary address line (suite, unit, etc.)	No
CUSTOMER_CITY	String	City name	No
CUSTOMER_STATE	String	State or province name	No
CUSTOMER_ZIPCODE	String	Postal/ZIP code	No
CUSTOMER_ADDRESS_VALIDATION_STATUS	String	Address validation status	No
CUSTOMER_LATITUDE	Number	Address latitude coordinate	No
CUSTOMER_LONGITUDE	Number	Address longitude coordinate	No

Primary Contact

Primary email and phone contact details.

Field Name	Data Type	Description	Required
CUSTOMER_PRIMARY_EMAIL	String	Primary email address	No
CUSTOMER_EMAIL_VALIDATION_STATUS	String	Primary email validation status	No
CUSTOMER_PRIMARY_PHONE	String	Primary phone number	No
CUSTOMER_PRIMARY_PHONE_TYPE	String	Phone line type	No
CUSTOMER_PRIMARY_PHONE_LABEL	String	Free-form phone label (e.g., “Home”, “Work”)	No
CUSTOMER_PHONE_VALIDATION_STATUS	String	Primary phone validation status	No

Other Contacts

Additional email and phone records aggregated as comma-separated lists.

Field Name	Data Type	Description	Required
CUSTOMER_OTHER_EMAILS	String	Comma-separated list of non-primary email addresses (delimiter is , — comma followed by a space, e.g., a@example.com, b@example.com). Secondary contacts do not have individual validation status fields	No
CUSTOMER_OTHER_PHONES	String	Comma-separated list of non-primary phone numbers (delimiter is , — comma followed by a space). Secondary contacts do not have individual validation status fields	No

Subscription / Consent

Communication consent statuses for marketing compliance.

Field Name	Data Type	Description	Required
CUSTOMER_EMAIL_SUBSCRIPTION_STATUS	String	Email marketing consent status	No
CUSTOMER_TEXT_SUBSCRIPTION_STATUS	String	SMS/text messaging consent status	No
CUSTOMER_DIRECT_MAIL_SUBSCRIPTION_STATUS	String	Direct mail consent status	No
CUSTOMER_BLOCKED_INCOMING_STEER	Boolean	Whether the customer is blocked from incoming Steer communications	No

Additional Fields

Field Name	Data Type	Description	Required
CUSTOMER_BIRTHDAY	String	Customer date of birth in YYYY-MM-DD format (e.g., 1990-05-15)	No
CUSTOMER_INSURANCE	String	Customer insurance provider name (free-text, e.g., State Farm, Geico)	No

System Metadata

Field Name	Data Type	Description	Required
STEER_CREATED_AT	Timestamp	Customer record creation timestamp in Steer (UTC)	Yes
STEER_UPDATED_AT	Timestamp	Last modification timestamp for this customer record (UTC)	Yes

Field Enum Values

Customer Type

• Person: Individual customer
• Business: Business/company customer

Subscription Status

Applies to CUSTOMER_EMAIL_SUBSCRIPTION_STATUS, CUSTOMER_TEXT_SUBSCRIPTION_STATUS, and CUSTOMER_DIRECT_MAIL_SUBSCRIPTION_STATUS:

• Eligible: Customer can receive communications via this channel
• NotEligible: Customer cannot receive communications via this channel
• Unsubscribed: Customer has opted out of communications
• WaitingForApproval: Consent request pending customer approval
• DisabledDuplicate: Account has been disabled because it was identified as a duplicate of another customer record. The customer’s communications are managed through their primary (non-duplicate) record. These records should be excluded from marketing sends

Caution

Marketing Compliance: Only customers with Eligible subscription status are authorized for marketing communications via the respective channel (email, SMS, or direct mail). External systems must strictly enforce this rule to maintain compliance with communication regulations.

Validation Status

Applies to CUSTOMER_EMAIL_VALIDATION_STATUS, CUSTOMER_PHONE_VALIDATION_STATUS, and CUSTOMER_ADDRESS_VALIDATION_STATUS:

• Valid: Contact information has been validated successfully
• Invalid: Contact information failed validation
• ValidationPending: Validation is in progress or not yet performed
• Deactivated: Contact information has been deactivated

Phone Type

• Unknown: Phone type not determined
• Mobile: Mobile/cell phone
• Landline: Landline phone
• Voip: Voice over IP phone

Timestamp Handling

Caution

Timezone: The STEER_UPDATED_AT and STEER_CREATED_AT fields are stored as timestamp_ntz (timestamp without timezone) in UTC. Data consumers should convert to local time using the shop’s timezone when displaying to end users.

Data Quality Notes

Null Values

Note

Expected Null Values

• EXTERNAL_CUSTOMER_ID may be null if the customer has no current mapping to an external source system
• Personal info fields (CUSTOMER_FIRST_NAME, CUSTOMER_LAST_NAME, CUSTOMER_COMPANY_NAME) may be null based on data completeness
• Address fields may be null if address information has not been provided
• CUSTOMER_LATITUDE and CUSTOMER_LONGITUDE may be null if address geocoding has not been performed
• Contact fields (CUSTOMER_PRIMARY_EMAIL, CUSTOMER_PRIMARY_PHONE) may be null if no primary contact is set
• CUSTOMER_OTHER_EMAILS and CUSTOMER_OTHER_PHONES may be null if no secondary contacts exist
• CUSTOMER_BIRTHDAY and CUSTOMER_INSURANCE may be null based on data availability

Sample Record

Complete API response example with a customer record:

{
  "data": [
    [
      "f2e3d4c5-b6a7-8901-2345-6789abcdef01",
      "c3d4e5f6-a7b8-9012-3456-789abcdef012",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "1004578, 2231987",
      "Sarah",
      "Johnson",
      null,
      "Person",
      "123 Main St",
      "Apt 4B",
      "New York",
      "New York",
      "10001",
      "Valid",
      "40.712776",
      "-74.005974",
      "sarah.johnson@example.com",
      "Valid",
      "+1-212-555-0123",
      "Mobile",
      "Personal",
      "Valid",
      null,
      null,
      "Eligible",
      "Eligible",
      "NotEligible",
      false,
      "1990-05-15",
      null,
      "2024-06-15T14:30:00.000Z",
      "2025-03-10T05:00:01.701Z"
    ]
  ],
  "metadata": {
    "rowType": [
      {"name": "STEER_TENANT_ID", "type": "text"},
      {"name": "STEER_SHOP_ID", "type": "text"},
      {"name": "STEER_CUSTOMER_ID", "type": "text"},
      {"name": "EXTERNAL_CUSTOMER_ID", "type": "text"},
      {"name": "CUSTOMER_FIRST_NAME", "type": "text"},
      {"name": "CUSTOMER_LAST_NAME", "type": "text"},
      {"name": "CUSTOMER_COMPANY_NAME", "type": "text"},
      {"name": "CUSTOMER_TYPE", "type": "text"},
      {"name": "CUSTOMER_ADDRESS_1", "type": "text"},
      {"name": "CUSTOMER_ADDRESS_2", "type": "text"},
      {"name": "CUSTOMER_CITY", "type": "text"},
      {"name": "CUSTOMER_STATE", "type": "text"},
      {"name": "CUSTOMER_ZIPCODE", "type": "text"},
      {"name": "CUSTOMER_ADDRESS_VALIDATION_STATUS", "type": "text"},
      {"name": "CUSTOMER_LATITUDE", "type": "real"},
      {"name": "CUSTOMER_LONGITUDE", "type": "real"},
      {"name": "CUSTOMER_PRIMARY_EMAIL", "type": "text"},
      {"name": "CUSTOMER_EMAIL_VALIDATION_STATUS", "type": "text"},
      {"name": "CUSTOMER_PRIMARY_PHONE", "type": "text"},
      {"name": "CUSTOMER_PRIMARY_PHONE_TYPE", "type": "text"},
      {"name": "CUSTOMER_PRIMARY_PHONE_LABEL", "type": "text"},
      {"name": "CUSTOMER_PHONE_VALIDATION_STATUS", "type": "text"},
      {"name": "CUSTOMER_OTHER_EMAILS", "type": "text"},
      {"name": "CUSTOMER_OTHER_PHONES", "type": "text"},
      {"name": "CUSTOMER_EMAIL_SUBSCRIPTION_STATUS", "type": "text"},
      {"name": "CUSTOMER_TEXT_SUBSCRIPTION_STATUS", "type": "text"},
      {"name": "CUSTOMER_DIRECT_MAIL_SUBSCRIPTION_STATUS", "type": "text"},
      {"name": "CUSTOMER_BLOCKED_INCOMING_STEER", "type": "boolean"},
      {"name": "CUSTOMER_BIRTHDAY", "type": "text"},
      {"name": "CUSTOMER_INSURANCE", "type": "text"},
      {"name": "STEER_CREATED_AT", "type": "timestamp_ntz"},
      {"name": "STEER_UPDATED_AT", "type": "timestamp_ntz"}
    ]
  }
}