How to configure one-way or bi-directional contact sync between HubSpot and Cotonity so agents always have up-to-date CRM data.
Choosing a sync strategy
Cotonity supports three contact sync modes: on-demand, scheduled, and real-time. On-demand sync fetches a contact record only when an agent workflow needs it, keeping API usage low. Scheduled sync runs a full or incremental pull at a configurable interval — as often as every 15 minutes on the Business plan. Real-time sync uses HubSpot webhooks to push changes to Cotonity the moment a property is updated in HubSpot. For most event-booking and customer-engagement use cases, real-time sync is recommended because it ensures agents always act on the freshest data.
Configuring sync filters
Navigate to Settings → HubSpot → Contact Sync and define which contacts to include. You can filter by list membership, lifecycle stage, owner, or any custom property. For example, you might sync only contacts whose Lifecycle Stage is Marketing Qualified Lead or Customer, avoiding unnecessary API calls for unqualified records. Filters are evaluated at the time of each sync run, so contacts that later meet the criteria are automatically included in the next cycle without manual intervention.
Field mapping
During the first sync setup, Cotonity automatically maps standard HubSpot contact properties — First Name, Last Name, Email, Phone, Company, and Lifecycle Stage — to the corresponding Cotonity contact fields. For custom properties, open the Field Mapping tab and drag HubSpot properties onto Cotonity fields or create new custom fields on the fly. Mappings support simple value pass-through as well as transformation functions such as date formatting, string concatenation, and conditional value replacement. Save the mapping configuration before running the initial sync.
Monitoring sync health
The Sync Dashboard shows the last run time, number of records processed, and any errors encountered. Common errors include records with invalid email formats, contacts exceeding the maximum number of custom properties, and API rate limit pauses. Each error links to the affected record and provides a suggested fix. You can set up Slack or email alerts for sync failures via Settings → Notifications. A full audit log of every sync operation is retained for 90 days and is exportable as CSV for compliance purposes.