---
title: CRM Sync
subtitle: Understand how CRM connections, workflow sync steps, and provider-specific lead updates work in OrcaPulse
slug: documentation/crm-sync
---

# CRM Sync

This page documents the current CRM sync implementation in OrcaPulse: connected CRM discovery, fetch-versus-send configuration, workflow-level CRM sync, provider-specific create-or-update behavior, Zoho token refresh handling, and timeline visibility for sync success or failure.

## What CRM Sync covers

CRM Sync is already a real part of the current OrcaPulse project. It appears in the UI as a workflow integration option, exists in the integration service layer, and has a full execution path in the backend workflow engine.

This means CRM behavior here is not just roadmap language. The product can already identify connected CRMs, import or sync data, and run CRM update steps while a lead is moving through a workflow.

## Connected CRMs and setup flow

The app exposes connected CRM systems through the integrations layer. On the front end, CRM connections are loaded for workflow configuration and action selection, and the UI presents CRM providers using human-readable names such as HubSpot, Salesforce, Zoho CRM, and Pipedrive.

In workflow settings, the user can open CRM actions, see connected systems, and choose whether they want to fetch leads into a workflow or enable sync back out to the CRM.

- Connected CRM list: the integration service can query active CRM integrations by category.
- Workflow UI support: workflow screens already surface CRM connections and actions to operators.
- Provider display names: the product normalizes provider IDs like `hubspot` and `salesforce` into readable CRM names.

## Fetch versus send model

CRM behavior in the current project has two directions. One direction is fetching leads from a CRM into OrcaPulse during workflow configuration. The other is sending lead data back to a CRM as part of ongoing workflow execution.

The front-end workflow CRM modal already reflects this split directly by offering a fetch path and a sync path instead of treating CRM as one generic toggle.

- Fetch mode: the UI can call an integrations endpoint to import leads from the selected CRM into a workflow context.
- Send mode: workflows can be configured so lead updates are synced back out to a CRM integration.
- Workflow linkage: CRM sync can be enabled as part of workflow configuration rather than only as a one-off action.

## Workflow CRM sync step

CRM sync is one of the real workflow step types supported by the backend execution engine. During execution, the service checks for a configured CRM integration, validates that the integration is active, decrypts stored credentials, prepares sync data, and then sends the lead to the selected provider.

The runtime also supports field mapping through `syncFields`, so workflow configuration can inject lead values such as name, email, phone, call status, duration, and success evaluation into CRM-specific fields.

- Step type support: `crm_sync` is a concrete step in workflow execution, not a placeholder.
- Credential handling: encrypted CRM tokens are decrypted at runtime before a sync attempt.
- Field templating: sync field values can be built from placeholders like `{{name}}`, `{{email}}`, and `{{successEvaluation}}`.
- Direction guard: the execution path only sends data when the step is configured for outbound CRM sync.

## Provider-specific sync behavior

The backend has separate implementations for HubSpot, Salesforce, Zoho, and Pipedrive. Each provider path follows a similar pattern: try to locate an existing record using CRM IDs or contact details such as phone and email, then update the record if found or create a new one if not.

Zoho also includes token refresh handling before sync when the access token is near expiry, which makes this part of the integration layer notably more mature than a basic fire-and-forget API call.

- HubSpot: searches contacts by phone or email and then patches or creates contact records.
- Salesforce: searches lead records, then updates or creates a lead through the Salesforce API.
- Zoho: searches Zoho leads, refreshes tokens when needed, then updates or creates lead records.
- Pipedrive: searches for related people or leads, then updates or creates lead entries using the configured API domain.

## Visibility and failure handling

CRM sync activity is visible through lead timeline events. When a sync starts, OrcaPulse records a pending timeline event. If the sync succeeds, it records a success event, and if it fails, the lead receives a failure event explaining what went wrong.

This is important operationally because CRM sync is not hidden background behavior. Teams can inspect whether a lead was sent, skipped because a token expired, or failed due to a provider-side error.

- Pending event: the timeline can show that a lead is currently being synced to a CRM.
- Success event: completed syncs are recorded with the provider name.
- Failure visibility: missing integrations, expired tokens, or provider errors generate failure events instead of silently disappearing.

## Next steps

After CRM Sync, the next useful integration page is usually Webhook Events, because it documents the other major outbound system-to-system path in the workflow engine.