Skip to main content
GainTrace reads ChurnZero through its REST API with an API username and key. This page covers what you need in ChurnZero, what comes over and what stays behind. For how the whole switch works, see Switch from another tool.

​
Before you start

ChurnZero’s REST API is a paid add-on. Your ChurnZero admin needs to set up three things:
  • The ChurnZero REST API add-on. It must be enabled on your ChurnZero account. If you aren’t sure, ask your ChurnZero CSM.
  • An API user with the Developer Tools permission. The API key belongs to this user, and the user needs ChurnZero’s Developer Tools user permission.
  • Bulk Read permissions. Bulk Read is set per object on the API user’s permission group. Grant Notes, Meetings, Messages and Tasks together: if only some of them are granted, the import stops when it reaches a missing one and names the permission. Any other permission you leave off just leaves that data behind.
You also need to be a workspace owner or admin in GainTrace. See Before you start.

​
Connect ChurnZero

1

Create an API key

In ChurnZero’s Admin area, open API Keys (under Data) and create a key for the API user. Copy the key.
2

Open the import

In GainTrace, go to Setup > Switch from another tool and choose ChurnZero.
3

Enter your details

  • ChurnZero URL: the address in your browser once you’re signed in to ChurnZero, such as https://acme.us1app.churnzero.net. The query link that Generate Query creates on ChurnZero’s API Keys page starts with it too.
  • API username: the ChurnZero user that owns the API key.
  • API key: the key you copied.
4

Check access

Choose Check access. GainTrace signs in and confirms the add-on and the Developer Tools permission. The scan then lists any object missing its Bulk Read permission by name.
GainTrace stores the key encrypted, uses it only to read, and deletes it when you switch over or stop the import.

​
What comes over

ChurnZero tasks carry no risk or escalation flag, so nothing from ChurnZero goes to Triage. Responses to custom survey types don’t come over, because ChurnZero scores every custom response as “completed” rather than with a rating.

​
ChurnScore history

GainTrace imports up to the last two years of each Company’s primary ChurnScore, as far back as ChurnZero has kept it, one point per week (the latest score that week). The points stay in ChurnZero’s own scale, on a separate Before GainTrace card, and are never mixed with GainTrace’s health score. From the import onward, GainTrace scores every Company with its own engine. Some ChurnZero instances keep only the current ChurnScore for each Account. In that case there’s no history to import, and Review lists Health score history under what stays.

​
Contract values and currency

ChurnZero doesn’t say which currency its amounts are in. In Review, under Contract values, confirm the currency, with your workspace currency suggested. Once you confirm it, each Company’s total contract amount becomes its ARR, with MRR set to ARR divided by 12, and its next renewal date becomes its renewal date. A value you changed in GainTrace is kept. Until you confirm a currency, the import can’t start. To start without one, untick Bring over contract values and renewal dates. Both values then stay in ChurnZero.

​
What stays in ChurnZero

These appear in Review under What stays in ChurnZero, and on the rebuild checklist once the scan finishes:

​
If something goes wrong

For every other message, see If something goes wrong.

​
Good to know

  • Only reads. GainTrace never writes to ChurnZero.
  • Shared rate limit. ChurnZero applies one per-minute limit to your ChurnZero instance, shared by every tool that reads through ChurnZero’s REST API, such as Power BI. GainTrace paces its reads to stay under it, but other tools reading at the same time can slow the import or be slowed by it.
  • Quiet import. Nothing imported from ChurnZero triggers flows, webhooks or signal detection. See Imports are quiet.
Last modified on October 21, 2026