Skip to main content

​
CDP to CRM object sync

Object sync activates a CDP segment into your CRM or martech app as native object writes — Salesforce Contacts, Leads, or Accounts; HubSpot contacts or companies; Braze, Iterable, Customer.io, or Klaviyo profiles. Records are upserted on an identifier field you choose, on the cadence you set. This is the reverse-ETL path: the segment you build in the CDP becomes the source, and the CRM object becomes the destination.

​
1. Object sync vs per-event destination dispatch

The integrations destinations panel routes CDP events to your connected SaaS apps one event at a time. That is the right shape for streaming new sign-ups and single contact updates. Object sync exists for the segment-level batch case:
  • You define a mapping once (which segment, which object type, which fields).
  • You run it on demand, or on a schedule you configure.
  • Profiles are chunked into upsert batches of 100 records each and dispatched through your connected integration.
Choose object sync when the unit of work is “this segment, into that CRM object,” not “this event, into that app.”
Connect the destination first from the destinations page — object sync can only run against a destination your organization has connected. No credentials are accepted on the object-sync surface; the connected account stays the only path.

​
2. Destinations and object types

Object sync supports six destinations, each with a closed list of native object types you may target: The object_type you set is validated against this list when you PATCH your config, so a target the destination cannot accept fails fast at config time, not at run time.

​
3. Configure a mapping

Read the config for every destination with GET /api/v1/cdp/crm-sync/config. It returns one entry per destination with its current mapping, the object types it accepts, and the last sync outcome. To create or update a mapping, PATCH the destination with only the keys you want to change — the merge is scoped to that destination, so every other destination’s config is preserved:
The identifier_field must appear as one of the values in your field_map. The config is rejected otherwise, because without a mapped key every record would be blind-inserted as a duplicate in your CRM.

​
4. Field-map and identifier rules

Two rules guard the mapping, at config time and again at run time:
  1. The identifier must be a mapped destination field. A profile can only be upserted if its record carries the upsert key.
  2. No two source traits may write to the same destination field. A duplicate would silently clobber one of your traits.
At run time, every profile is projected through your field map. A profile whose mapped record has a missing or empty identifier value is skipped — never blind-inserted — and counted in the run’s skipped total.

​
5. Run a sync

Trigger an on-demand run with POST /api/v1/cdp/crm-sync/run/{destination}:
  • segment_id (required, up to 200 chars) labels which segment the profiles belong to; it is recorded on the run.
  • profiles is the batch of profiles to project through the stored field map (1 to 5000 per request).
The response is the recorded run object:
Records are grouped into batches of 100 and upserted through your connected integration. status reads:
  • ok — every batch upserted.
  • partial — some batches upserted, some failed.
  • failed — every batch failed.
  • skipped — nothing to dispatch (no matched records, or no connected account wired yet).
A run against a destination with no connected account is still recorded — every batch reports as dispatch_skipped — so you can validate the mapping end to end before you wire the integration.

​
6. Read the run history

GET /api/v1/cdp/crm-sync/runs returns the most recent runs, newest first. The history is capped at the last 50 runs per organization; older runs roll off as new ones land. Use it in a sync-run-log style loop: shape the run, check rows.rejected (profiles skipped for a missing upsert key) and dispatch_failures (per-batch provider errors, with record counts — never the profile data) to find the leg that needs a fix. Object sync activates a segment you defined, through a connection you authorized. The decision to sync, and the cadence, are entirely your organization’s controls:
  • Config changes and runs are written to the audit log with the destination and the operation counts — never the profile records themselves.
  • Runs record counts (matched, skipped, batches, dispatch outcomes), not profile payloads. Failed batches keep the provider error message and the batch’s record count only.
If you operate under a consent regime, the segment’s membership is the filter that decides whose data reaches the CRM — keep the segment definition aligned with your subscribers’ consent, as you would for any other activation surface (erasure propagation covers the delete path).