CRM sync and troubleshooting

Importing contacts brings a selected audience into your workflow and can create or match CRM records. Ongoing sync sends supported record changes and activities to your connected CRM according to your organization's setup.

Organization administrators manage CRM sync mappings and investigate CRM sync logs. These settings are separate from connecting a personal email account, adding Salesforce search filters, or choosing the fields displayed on a contact card.

Supported entities and sync behavior depend on the CRM connection. The activity-mapping editor includes Salesforce object settings; do not assume those settings configure every other CRM in the same way. For Salesforce, HubSpot, or a custom connection that needs setup, chat with us.

1. Open Org settings → CRM sync mappings and choose Contact or Account.
2. Review Use custom contact/account mappings. This one switch applies to both tabs: when it is on, Salesforce Contacts and Accounts use the mappings you configure here; when it is off, they use Athean's default mappings and continue to sync.
3. Use Add Contact mapping or Add Account mapping to pair an Athean field with a CRM field. Choose Constant Value when the destination should receive a fixed value.
4. Review Update mode for the record type.
5. Resolve any field validation messages, then select Save changes.

• Never update (immutable after creation): use the mapping to create records without updating them afterward.
• Update all fields: allow updates to the mapped fields.
• Update selected fields only: choose Fields to update on sync. The selection limits updates to existing records; creation still sends all mapped fields.

For example, you may want to populate several fields when a contact is first created but update only selected enrichment fields afterward. Confirm the destination field names and your CRM's required fields before saving. Salesforce Lead updates use separate behavior from the Contact mappings shown here.

The mapping tabs also include Emails, Calendar, Calls, LinkedIn, and Transcripts. Open the relevant tab to review its configured destination and fields. Salesforce activity mappings apply separately when configured; turning off Use custom contact/account mappings does not disable activity mappings.

Each activity tab has its own Writebacks enabled switch, so you can roll out Salesforce writebacks one activity type at a time. Turn it off and select Save changes to pause writebacks for that type only; the other types keep syncing. You can still edit the tab's mappings while writebacks are paused, and removing a mapping does not turn them back on.

For Salesforce activity mappings, select the destination object, map its fields, and use the available template variables to include information from the activity. Review the update mode separately for each activity type.

Calendar mappings also provide an owner choice: Creator (default) or Organizer. This determines which attendee is used as the Salesforce event owner when multiple internal users attend.

Saving mappings configures subsequent sync behavior. Check a relevant sync result afterward rather than assuming a mapping change has resent all historical activity.

The same applies when you turn writebacks back on: activity from the paused period is not sent. While a type is paused, its activity is skipped, and Retry sync in CRM sync logs does not work for that type until you turn writebacks back on.

These steps investigate changes or activities expected to sync from Athean to your CRM. If CRM data is missing from Athean, start by checking the shared CRM connection and your current account or contact filters. Chat with us if the expected record is still missing.

1. Open Org settings → CRM sync logs.
2. Filter by Entity type, Date, and, when known, Entity ID. Add Status or CRM operation to narrow the results.
3. Review the Entity, CRM Operation, and CRM ID to confirm the record and destination.
4. Read Skip Reason for a skipped sync or Error for a failed sync. Open Request Body when you need to inspect the fields sent in that attempt.

Success, Failed, and Skipped describe different outcomes. A skipped record may reflect the configured rules or a missing prerequisite; read its reason before changing mappings.

No matching log? Widen the date range and clear Status or CRM operation filters, then confirm the record or activity exists in Athean and that you are looking for the correct entity. No matching row does not establish that a sync succeeded. If there is still no result, contact support with the Athean record or activity, the time, the destination CRM record when known, and the change you expected. Retry sync is available on a failed row; it cannot retry an attempt you have not found.

Time records the sync attempt. Activity Time, when available, records when the underlying activity happened. Use both when investigating older activity that synced later.

After correcting the reported cause, select Retry sync on a failed row. This makes another CRM sync attempt using the current entity and applicable settings; it is an action that can create or update a CRM record.

Review the latest result and CRM ID after the retry. If it fails again, use the new error to identify what still needs attention. A missing connection, invalid destination field, or record relationship may require a different fix from changing an update mode.

Use Export CSV to download the filtered log results across pages. If the export reports a size limit, narrow the date range or other filters.

When asking support for help, include the affected account or contact, which system the change should move from and to, the relevant time, any log status or error, and what you expected to appear.