> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ChurnZero

> Fight customer churn with fresh customer data in ChurnZero

## Supported syncing

| Type | Description | Supported Sync Modes | API Reference |
| - | - | - | - |
| **Events** | Sync records as events to Churnzero. This is often in the form of a track call | Insert | [Event schema](https://app.churnzero.net/developers#schemas-event) |
| **Enrichment** | Sync records to a Churnzero custom table | All | [Batch import API](https://support.churnzero.com/hc/en-us/articles/360004339852-Batch-Imports-via-CSV) |
| **Objects** | Sync records to objects such as accounts and contacts in Churnzero | Upsert | [Account schema](https://app.churnzero.net/developers#schemas-account) and [contact schema](https://app.churnzero.net/developers#schemas-contact) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to ChurnZero

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-churnzero-setup-key.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1d7d19ed35795b324d69fe8f864882b6)

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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-churnzero-setup-url.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=af86e0d2cb2e62b8245f9568b7c523a8)

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](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) 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.

> [!WARNING]
>
> To ensure syncs send each event, your event model must use a truly unique [primary key](https://docs.hightouch.com/getting-started/concepts.md#unique-primary-key-requirement). See the [events syncs](https://docs.hightouch.com/syncs/types-and-modes.md#event-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](https://www.iso.org/iso-8601-date-and-time-format.html) format.

#### Field mapping

Hightouch lets you sync default and custom event properties via [field mapping](https://docs.hightouch.com/syncs/mapping-data.md).
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](https://support.churnzero.com/hc/en-us/articles/360004339852-Batch-Imports-via-CSV).
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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-churnzero-custom-table.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=cc086d5e995b829392167c0bb1c7b85d)

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](https://docs.hightouch.com/syncs/record-matching.md) for more information.

#### Field mapping

Hightouch lets you sync custom table columns via [field mapping](https://docs.hightouch.com/syncs/mapping-data.md).
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.

> [!WARNING]
>
> 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 accounts 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.

> [!NOTE]
>
> 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](https://docs.hightouch.com/syncs/mapping-data.md).
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](https://app.churnzero.net/developers#schemas) to see objects' default fields.

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

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

> [!WARNING]
>
> 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.

## Common errors

### 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.