Skip to main content

Authorization

Follow this guide to create a new ChurnZero credential that will allow Nexla to authenticate to and exchange data with your ChurnZero account.
churnzero_api_auth.png

ChurnZero

Prerequisites​

The ChurnZero REST API is an OData implementation that lets you read your customer success data, and a companion analytics endpoint lets you write account, contact, attribute, and event data back into ChurnZero. Authentication uses HTTP Basic Authentication, where your ChurnZero username is paired with an API key associated with that user. Before creating a credential in Nexla, complete the following in your ChurnZero account.

Obtain Your ChurnZero Subdomain​

Your subdomain identifies your specific ChurnZero instance and region, and it forms the base of every API request URL.

  1. Sign in to your ChurnZero account in a web browser.

  2. Note the host portion of your ChurnZero URL. For example, if your URL is https://fivetran.us1app.churnzero.net, your subdomain is fivetran.us1app.

    The subdomain includes the region segment (for example, us1app or eu1app). Enter the full host prefix exactly as it appears in your browser, excluding the .churnzero.net portion.

Create a ChurnZero API Key​

API keys are tied to a specific ChurnZero user, and API requests inherit that user's permissions.

  1. In ChurnZero, navigate to Admin > API Keys.

  2. Click the option to create a new API key, and copy the generated key.

  3. Store the API key securely. This key functions as the password for API requests and should be treated as a secret credential.

    Important

    Copy the API key when it is created and store it in a secure location. Anyone with your username and API key can access your ChurnZero data.

Confirm Bulk Read Permissions​

Because the REST API can return large volumes of data, ChurnZero gates access to readable entities behind Bulk Read Permissions. These permissions are configured per User Permission Group and apply to all users in that group.

  1. Confirm that the user associated with your API key belongs to a User Permission Group that has the appropriate Bulk Read Permissions enabled for the entities you plan to ingest (for example, Accounts, Contacts, Events, or Surveys).

  2. If an entity returns no data or an authorization error during testing, verify that the corresponding Bulk Read Permission is enabled for that group.

For complete details, refer to the ChurnZero REST API reference and the ChurnZero REST API overview.

Create a ChurnZero Credential​

  • To create a new ChurnZero credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Authentication Settings​

ChurnZero authenticates using your account subdomain, your login username, and an API key. Nexla uses these values to construct the API request URL and to authenticate each call via HTTP Basic Authentication.

  1. Enter your ChurnZero login username in the Username field. This is the email address you use to sign in to ChurnZero, and it serves as the username portion of the Basic Authentication credential.

  2. Enter your ChurnZero API key in the API Key field. This key was generated under Admin > API Keys and serves as the password portion of the Basic Authentication credential. This value is stored securely and should be kept confidential.

  3. Enter your ChurnZero subdomain in the Subdomain field. This is the host prefix from your ChurnZero URL—for example, if your URL is https://fivetran.us1app.churnzero.net, enter fivetran.us1app.

    Nexla validates the credential by making a test request to your ChurnZero account. A successful test confirms that the subdomain, username, and API key are correct and that the associated user has the required permissions.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.