Mapping Configuration Guide

Mappings tell Zoody how to turn your product events into HubSpot properties. This guide walks through creating mappings, choosing aggregation types, and using templates.

How mappings work

A mapping connects one event name to one HubSpot property. When Zoody receives events, it looks up all matching mappings, computes an aggregated value (like a count or sum), and writes that value to the HubSpot property on the matched contact or company record.

Example

You send feature_used events with an email address. You create a mapping that counts those events over 30 days and writes to a HubSpot contact property called zo_feature_usage_30d. Now every contact in HubSpot has a number showing how many times they used your product in the last 30 days - usable in lead scoring, workflows, and reports.

Mapping fields

Each mapping has these components:

Field	Required	Description
event_name	Yes	The event name to match (e.g., "feature_used", "login", "payment_completed")
hubspot_object	Yes	Which HubSpot record type to update: contact or company
hubspot_property	Yes	The HubSpot property to write to. Pick an existing property or enter a custom name - Zoody auto-creates it on first sync.
aggregation	Yes	How to compute the value: count, sum, last_value, or last_timestamp
source_field	Conditional	Required for sum and last_value. The event property to extract (e.g., "amount", "feature_name").
time_window	Yes	Rolling (7d, 30d, 90d, all time, custom) or calendar-based (this week, this month, this quarter)

Aggregation types

The aggregation type determines what value Zoody writes to HubSpot.

count

Count of matching events

Counts how many times the event occurred for each contact or company. No source field needed.

Use case: Track login frequency, feature usage count, page views. "How many times did this user log in over the last 30 days?"

sum

Sum of a numeric property

Adds up a numeric value from the event's properties field. Requires a source_field (e.g., "amount").

Use case: Total revenue per contact, cumulative usage minutes, total API calls. "What is this customer's total spend?"

last_value

Most recent value of a property

Returns the value of a specific property from the most recent event. Requires a source_field (e.g., "feature_name", "plan").

Use case: Last feature used, current plan tier, most recent action. "What feature is this user currently focused on?"

last_timestamp

Timestamp of the most recent event

Stores when the event last occurred. Written as a HubSpot date property. No source field needed.

Use case: Last active date, last login, last purchase date. "When was this contact last seen in the product?" Great for churn risk scoring.

Time windows

Time windows control the date range Zoody looks at when computing aggregations.

Rolling windows

A rolling window always looks back a fixed number of days from today. Presets: 7 days, 30 days, 90 days, or all time (no window). You can also set a custom number of days.

Calendar windows

Calendar windows reset at the start of each period:

This week - resets every Monday
This month - resets on the 1st
This quarter - resets Jan 1, Apr 1, Jul 1, Oct 1

Tip: Use multi-window mappings to create several time windows at once. For example, track feature usage across 7d, 30d, and all time with a single template. Each window gets its own HubSpot property (e.g., zo_feature_used_7d, zo_feature_used_30d, zo_feature_used_total).

Templates

Templates are pre-configured mappings for common use cases. Click "Use Template" in the dashboard to browse and apply them.

Engagement

Feature Usage Counter

Counts events per contact. Identifies power users.

feature_used > zo_feature_usage_count (contact, count)

Counts logins in the last 30 days. Shows engagement trends.

Multi-Window Counter

Creates 3 mappings at once: 7d, 30d, and all time.

feature_used > zo_feature_used_7d, _30d, _total (contact, count)

Lifecycle

Last Active Timestamp

Tracks the most recent activity time. Useful for churn risk scoring.

page_view > zo_last_active_at (contact, last_timestamp)

Adoption

Company Event Volume

Counts events per company (not contact). Identifies most active accounts.

feature_used > zo_event_volume (company, count)

Last Feature Used

Stores the name of the most recent feature accessed.

feature_used > zo_last_feature (contact, last_value, source: feature_name)

Revenue

Revenue Total

Sums payment amounts per contact. Tracks total revenue.

payment_completed > zo_total_revenue (contact, sum, source: amount)

Customizing templates: You can change the event name when applying a template. For example, if your app uses "user_login" instead of "login", just override it before applying. The HubSpot property name and aggregation settings stay the same.

Creating a mapping step by step

In the Zoody dashboard, go to Mappings and click Create Mapping.

1
Enter the event name
Type the exact event name your app sends (e.g., feature_used). This must match what you pass as eventName in your API calls.
2
Choose the HubSpot object type
Select Contact to update individual user records (matched by email) or Company to update account-level records (matched by domain).
3
Pick a HubSpot property
Search your existing HubSpot properties or type a new custom name. If you use a custom name, Zoody auto-creates the property in HubSpot on the first sync with the correct type (number for count/sum/last_timestamp, text for last_value).
4
Select the aggregation type
Choose count, sum, last_value, or last_timestamp. If you pick sum or last_value, you will also need to enter the source field (the key from your event properties).
5
Set the time window
Pick a rolling window (7d, 30d, 90d, all time, or custom) or a calendar window (this week, month, or quarter). Use multi-window mode to create several at once.
6
Preview and create
Click Preview to see how many records would be affected and sample computed values. When it looks right, click Create. Zoody starts syncing on the next processing cycle.

Mapping limits by plan

Plan	Mappings	Events / month	Sync frequency
Free	3	1,000	Every 24 hours
Pro	25	50,000	Real-time
Growth	Unlimited	500,000	Real-time

Common mapping patterns

Here are proven patterns for getting value from Zoody quickly:

Lead scoring by product engagement

Create a 30-day feature usage count on contacts. In HubSpot, add that property to your lead scoring model. Contacts who use your product more get higher scores and surface to sales faster.

feature_used > zo_feature_usage_30d (contact, count, 30d)

Churn risk alerts

Map last_timestamp for logins. In HubSpot, create a workflow that triggers when zo_last_active_at is more than 14 days ago. Auto-enroll inactive contacts in a re-engagement sequence.

Account-level expansion signals

Count events per company and track the last feature used at the company level. When a company's event volume spikes or they start using an advanced feature, that is an expansion opportunity your account team can act on.

feature_used > zo_event_volume (company, count, 30d)
feature_used > zo_last_feature (company, last_value, source: feature_name)

Next steps

Send your first event if you haven't already
API Reference for full endpoint details
Security & Data Flow for your security team
Contact us if you need help setting up mappings for your use case