Customer-Vibes Data Model

Data Model Overview

🏗️ Primary Entities

Customers: Individual or business customers with contact information and preferences

Vehicles: Vehicle records associated with customers

Integrations: External system mappings for both customers and vehicles

Appointments & Services: Historical service data and scheduling information

🔗 Key Relationships

One-to-Many: Customer → Vehicles

One-to-One: Customer → Integration (when steer_entity = 'Customer')

One-to-One: Vehicle → Integration (when steer_entity = 'Vehicle')

Field Specifications

Customer Identification

Core identification fields for customer records with internal and external system mapping.

Field Name	Data Type	Description	Required
steer_customer_id	String	Internal customer identifier (primary key)	Yes
vast_customer_id	String	External system customer ID (when integrated)	No
customer_type	String	Customer classification type (Person, Business)	Yes
customer_stage	String	Customer lifecycle stage (Customer, Prospect)	Yes

Customer Demographics

Personal and business information for customer records.

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_city	String	Customer city	No
customer_state	String	Customer state/province	No
customer_zip	String	Customer postal code	No

Contact Information

Communication channels and consent preferences for marketing compliance.

Field Name	Data Type	Description	Required
customer_phone_number	String	Primary phone number	No
customer_text_consent_status	String	SMS/text messaging consent status	No
customer_email	String	Primary email address	No
customer_email_consent_status	String	Email marketing consent status	No

Consent Status Values

Text/SMS Consent

• Eligible: Customer can receive SMS/text messages
• NotEligible: Customer cannot receive SMS/text messages
• Unsubscribed: Customer has opted out of SMS/text messaging
• WaitingForApproval: Consent request pending customer approval
• DisabledDuplicate: Account disabled due to duplicate detection

Email Consent

• Eligible: Customer can receive email communications
• NotEligible: Customer cannot receive email communications
• Unsubscribed: Customer has opted out of email communications
• WaitingForApproval: Consent request pending customer approval
• DisabledDuplicate: Account disabled due to duplicate detection

Caution

⚠️ CRITICAL MARKETING COMPLIANCE: Only customers with Eligible consent status are authorized for marketing communications via the respective channel (SMS or email). External systems must strictly enforce this rule to maintain compliance with communication regulations.

Vehicle Information

Vehicle records linked to customer profiles with internal and external system mapping.

Field Name	Data Type	Description	Required
steer_vehicle_id	String	Internal vehicle identifier	No
vast_vehicle_id	String	External system vehicle ID (when integrated)	No
vehicle_make	String	Vehicle manufacturer (Steer’s recognized/corrected value)	No
vehicle_year	String	Vehicle model year (Steer’s recognized/corrected value)	No
vehicle_model	String	Vehicle model name (Steer’s recognized/corrected value)	No
vehicle_original_specification_make	String	Original vehicle make from initial data entry	No
vehicle_original_specification_model	String	Original vehicle model from initial data entry	No
vehicle_original_specification_year	String	Original vehicle year from initial data entry	No

Note

Vehicle Data Accuracy: The API provides both corrected and original vehicle specifications:

• Corrected fields (vehicle_make, vehicle_year, vehicle_model): Steer’s standardized and validated vehicle information
• Original specification fields: Raw data as originally entered, useful for data quality analysis and customer verification

Location & Business Context

Service location and tenant information for multi-location business support.

Field Name	Data Type	Description	Required
shop_location_name	String	Service location name	Yes
shop_time_zone	String	Location time zone (for converting UTC timestamps)	Yes
tenant_name	String	Business/brand name	Yes

Service History

Historical appointment and service data aggregated to show most recent activity.

Field Name	Data Type	Description	Required
last_appointment_date	Unix Timestamp	Most recent appointment date as Unix timestamp with nanoseconds (scheduled, started, ended, or missed)	No
last_visit_date	Unix Timestamp	Most recent completed service date as Unix timestamp with nanoseconds (paid invoice)	No

System Metadata

Tracking information for data synchronization and change detection.

Field Name	Data Type	Description	Required
updated	Unix Timestamp	Last modification timestamp with nanoseconds across all related entities	Yes

Business Rules

Customer Stage Determination

The customer_stage field is calculated using the following business logic:

Customer

Someone who has visited a shop or exists in the shop management system (VAST). This includes anyone with an external integration ID OR has completed paid invoices.

Prospect

Someone who can potentially visit a shop, or tried to book an appointment with the shop but didn’t finish the booking process. This includes individuals with no external integration ID AND no paid invoices AND has abandoned booking records.

Integration Mapping

External system integration follows these mapping rules:

• vast_customer_id is populated when an integration record exists with steer_entity = 'Customer'
• vast_vehicle_id is populated when an integration record exists with steer_entity = 'Vehicle'
• Both fields can be null if no integration exists for the respective entity

Data Aggregation Rules

📅 Appointments

Multiple appointments are aggregated to show the most recent activity across all appointment statuses

💳 Invoices

Multiple invoices are aggregated to show the most recent payment completion

⏱️ Updates

The updated field reflects the latest modification timestamp across all related entities

Data Quality Notes

Null Values

Understanding when fields may contain null values:

Note

Expected Null Values

• Vehicle information may be null for customers without registered vehicles
• Integration IDs will be null for entities not synchronized with external systems
• Contact information fields may be null based on customer data completeness

Consent Management

Tip

Consent Status Enforcement

• Consent status fields indicate customer preferences for communication channels
• These should be respected in all downstream marketing and communication processes
• Only Eligible status authorizes marketing communications

Integration Considerations

Time Zone Handling

Caution

Critical Time Zone Requirements

• All timestamp fields are Unix timestamps in UTC format
• Data consumers must convert Unix timestamps to appropriate local time using the shop_time_zone field
• The shop_time_zone field represents the customer’s primary service location time zone
• Use standard time zone conversion libraries to handle daylight saving time transitions accurately

Data Freshness

Tip

Change Detection Strategy

The updated field provides a reliable indicator for incremental data synchronization. Recommended to use this field for change detection and delta processing workflows.

Sample Record

Complete example of a customer record with all fields populated:

{
  "steer_customer_id": "4b62d36a-a5d6-4308-8d40-af6358104775",
  "vast_customer_id": "0015069558",
  "customer_type": "Person",
  "customer_stage": "Customer",
  "customer_first_name": "Sarah",
  "customer_last_name": "Johnson",
  "customer_company_name": null,
  "customer_city": "Austin",
  "customer_state": "Texas",
  "customer_zip": "78701",
  "shop_time_zone": "America/Chicago",
  "customer_phone_number": "+1-512-555-0123",
  "customer_text_consent_status": "Eligible",
  "customer_email": "sarah.johnson@example.com",
  "customer_email_consent_status": "Eligible",
  "steer_vehicle_id": "f154d8db-cbe1-461e-bc7b-5fae9eeeead2",
  "vast_vehicle_id": "15000171790",
  "vehicle_make": "Honda",
  "vehicle_year": "2019",
  "vehicle_model": "Accord",
  "vehicle_original_specification_make": "HONDA",
  "vehicle_original_specification_model": "ACCORD",
  "vehicle_original_specification_year": "2019",
  "shop_location_name": "Central Auto Care",
  "tenant_name": "AutoCare Plus",
  "last_appointment_date": "1701457200.000000000",
  "last_visit_date": null,
  "updated": "1750254263.614000000"
}