User Object
Overview
The user object represents a customer or visitor interacting with your website or application. It captures identification, contact information, geographic data, order history, and custom properties for user segmentation and personalization across destinations.
No fields are strictly required — include as much data as available. The more complete the user data, the better the attribution and audience matching across advertising platforms.
Email and phone must be provided as plaintext only — do not send pre-hashed values. DATA Reshape automatically normalizes and hashes all PII before sending to destinations.
Complete Reference
user object
id string recommended
Unique customer identifier in your system.
id: "CUSTOMER_INTERNAL_ID"
email string recommended
Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.
email: "[email protected]"
phone string recommended
Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.
phone: "+40712345678"
first_name string recommended
Customer first name
first_name: "John"
last_name string recommended
Customer last name
last_name: "Doe"
country string
Country name or ISO country code
country: "Romania"
region string recommended
State, province, or region name
region: "Bucuresti"
city string recommended
City or locality name
city: "Bucuresti"
street string
Street address including number
street: "Strada Principala 1"
postal_code string
Postal code or ZIP code
postal_code: "700000"
orders_total_number number recommended
Cumulative number of orders placed by this user
orders_total_number: 5
orders_canceled_number number recommended
Cumulative number of orders placed and canceled by this user
orders_canceled_number: 0
orders_total_value number recommended
Cumulative lifetime user orders value (decimal format: 2500.50)
orders_total_value: 1234.99
orders_refunded_value number recommended
Cumulative lifetime user orders value canceled (decimal format: 2500.50)
orders_refunded_value: 250.99
predicted_value number
Predicted lifetime value of a customer for your business
predicted_value: 100.99
created_at number recommended
Timestamp in milliseconds since Unix epoch representing the first time the user was recorded
created_at: 1754926521690
properties object recommended
Custom Customer Properties Examples
Use the properties object to store custom user attributes, with property names defined by each business as needed, that enable advanced segmentation, personalization, and analytics across your marketing campaigns.
- E-commerce Customer
- B2B Lead/Customer
- Subscription Service
- Content Platform
properties: {
customer_type: "returning",
membership_level: "platinum",
preferred_category: ["electronics", "fashion"],
last_purchase_date: "2024-12-15",
average_order_value: "350.00",
payment_method_preference: "card",
registration_date: "2023-06-15"
}
properties: {
company_size: "enterprise",
industry: "fintech",
job_title: "marketing_director",
decision_maker: "true",
budget_range: "50000-100000",
lead_source: ["linkedin", "webinar"],
qualification_status: "qualified",
sales_stage: "proposal"
}
properties: {
subscription_tier: "premium",
billing_cycle: "annual",
feature_usage: ["analytics", "reporting", "api"],
trial_user: "false",
renewal_date: "2025-06-30",
support_level: "priority",
usage_frequency: "daily"
}
properties: {
content_preferences: ["technology", "business"],
engagement_level: "high",
newsletter_subscriber: "true",
social_media_follower: "true",
content_consumption: "premium",
device_preference: ["mobile", "desktop"],
timezone: "Europe/Bucharest"
}
Examples
- Complete
- Lead
- Minimal
{
"id": "CUST_12345",
"email": "[email protected]",
"phone": "+40712345678",
"first_name": "Alexandru",
"last_name": "Popescu",
"country": "RO",
"region": "Brasov",
"city": "Brasov",
"street": "Strada Republicii 45",
"postal_code": "500030",
"orders_total_number": 8,
"orders_canceled_number": 1,
"orders_total_value": 2156.75,
"orders_refunded_value": 299.99,
"predicted_value": 3500.00,
"created_at": 1640995200000,
"properties": {
"customer_segment": "loyal",
"acquisition_channel": "paid_search",
"loyalty_tier": "gold"
}
}
{
"email": "[email protected]",
"phone": "+1555234567",
"first_name": "David",
"last_name": "Smith",
"country": "US",
"region": "New York",
"city": "New York",
"predicted_value": 15000.00,
"created_at": 1704067200000,
"properties": {
"company": "TechCorp Solutions",
"job_title": "IT Director",
"lead_source": "webinar"
}
}
{
"email": "[email protected]"
}
Even a single email enables audience matching across most advertising platforms.
Order History Fields
The order history fields provide lifetime metrics for customer value analysis and segmentation:
- orders_total_number — cumulative number of orders placed
- orders_canceled_number — cumulative number of canceled orders
- orders_total_value — cumulative lifetime order value
- orders_refunded_value — cumulative refunded value
- predicted_value — predicted lifetime value for your business
- created_at — timestamp (milliseconds) when the user was first recorded
These values should reflect the user's complete history, not just the current event.
Custom Properties
The properties object allows you to attach any custom key-value data for segmentation:
{
"properties": {
"customer_segment": "loyal",
"acquisition_channel": "paid_search",
"loyalty_tier": "gold",
"preferred_categories": ["electronics", "home_garden"]
}
}
Use properties that enable meaningful audience segmentation in your advertising destinations.
Best Practices
- Consistent IDs — use stable user IDs across all events and sessions
- Multiple contact methods — provide both email and phone when available for better audience matching
- Accurate order history — keep lifetime metrics up to date for proper customer value segmentation
- Plaintext only — send email and phone as plaintext; DATA Reshape normalizes and hashes automatically before sending to destinations
- Focused properties — include only properties that enable actionable segmentation in your destinations
- Privacy compliance — respect user consent preferences; omit personal data when consent is not granted