Search documentation...

K
ChangelogBook a demoSign up

ChurnZero

Fight customer churn with fresh customer data in ChurnZero

Supported syncing

TypeDescriptionSupported Sync ModesAPI Reference
EventsSync records as events to Churnzero. This is often in the form of a track callInsertEvent schema
EnrichmentSync records to a Churnzero custom tableAllBatch import API
ObjectsSync records to objects such as accounts and contacts in ChurnzeroUpsertAccount schema and contact schema

For more information about sync modes, refer to the sync modes docs.

Connect to ChurnZero

Go to the Destinations overview page and click the Add destination button. Select ChurnZero and click Continue. You can then authenticate Hightouch to ChurnZero by entering a ChurnZero App Key.

To find your app key, go to Admin > Application Keys > New App Key in ChurnZero. Create a new key with a descriptive name, for example, "Hightouch Integration".

ChurnZero API Key

Though optional, it's best to enter your App URL into Hightouch. You can find it below the Application Keys in ChurnZero. Do not include the /i in the URL you enter into Hightouch.

ChurnZero App URL

If you don't provide your App URL, Hightouch defaults to https://analytics.churnzero.net/.

Sync configuration

Once you've set up your ChurnZero destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the ChurnZero destination you want to sync to.

Syncing events

ChurnZero's events API requires the following event parameters:

  • eventDate: The date/time the event occurred. ISO 8601 formatted string.
  • AccountId: The ID of the Account associated with the event
  • ContactId: The ID of the Contact associated with the event

The sync configuration form ensures all these are set and provides some additional options.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Event name

Providing an event name is best practice while event tracking. You can either provide a static value or select to use a column from your model. Hightouch syncs the static or column value as the eventName parameter.

Event timestamp

You can optionally select a column that contains timestamps of when events occurred. If this field is empty, Hightouch uses the time the event arrives at the server. Hightouch syncs the timestamp as the eventTime parameter the events API requires.

If you select a column, it should be in ISO 8601 format.

Field mapping

Hightouch lets you sync default and custom event properties via field mapping. You must include the Account External ID and Contact External ID of the account and contact associated with the event.

Syncing enrichments

Hightouch lets you sync data to custom tables through ChurnZero's batch import API. To use this API, you must first create the custom table within ChurnZero. You can create custom tables by going to the admin tab in ChurnZero and selecting Custom Fields.

Custom Table creation in ChurnZero

To locate the custom table to update, Hightouch requires these two fields in your sync configuration:

  • Custom table ID: You can find the table ID by going into Admin/Imports and selecting the custom table name from the dropdown there.
  • Account ID: This is the user account the custom table is associated with. You can find it by clicking on your name at the top of the ChurnZero dashboard and selecting My Account. Your ID is at the end of the URL.

Record matching

You can match rows from your model to enrichment in ChurnZero on any column in your model and any field in ChurnZero. Ensure the data types of the model column and ChurnZero field you select match. Refer to the record matching docs for more information.

Field mapping

Hightouch lets you sync custom table columns via field mapping. You can map data from any of your model columns to the columns you've already created in your custom table. Ensure your model columns' data types match the data types of the fields you want to sync to.

Hightouch can only sync data to fields you've already created in your custom table in ChurnZero on the Custom Fields page.

Syncing objects

Hightouch supports syncing to the following ChurnZero objects:

  • Contacts
  • Accounts

Record matching

To match rows from your model to contacts in ChurnZero, you need to select the model column that contains values that match the Contact External ID field. To match rows from your model to contacts in ChurnZero, you need to select the model column that contains values that match the Account External ID field. You can find these identifiers in the top left of your contact or account page.

External identifiers are not the same as the ID in the URL of a contact or account page.

Field mapping

Hightouch lets you sync account and contact fields via field mapping. You can map data from any of your model columns to default and custom fields. Ensure your model columns data types match the data types of the fields you want to sync to.

You can find the custom fields for your ChurnZero workspace in Admin > Custom Fields. Go to either the contact or account table to see the custom fields for that object type. When syncing custom fields, use the CZ API Name as the destination field name in the Hightouch mapper.

ChurnZero requires that you map at least one default field. If you use primarily custom fields, make sure to also map at least one default field. Visit the ChurnZero's API documentation to see objects' default fields.

When syncing contacts, you must map a field to the contact's Acount Exernal ID. Please make sure that the contact's associated account exists in ChurnZero before attempting to sync contact information.

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

404 - "null"

You may receive a 404 - "null" error because there is a trailing / at the end of the App URL within the Destination configurations. Remove the trailing / from the App URL to clear the error.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

ChurnZero's API doesn't return detailed error messages. For example, it doesn't state whether an account ID or a custom field you are attempting to sync to exists. Therefore, Hightouch is unable to display this type of information in the debugger.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Sep 14, 2023

On this page

Supported syncingConnect to ChurnZeroSync configurationSyncing eventsSyncing enrichmentsSyncing objectsTips and troubleshootingCommon errorsLive debuggerSync alerts

Was this page helpful?