Batch Accounts
Batch Contacts
Batch Events
Batch Custom Tables
IMPORTANT: The endpoint for sending data to ChurnZero is personalized to your specific instance. The examples below include a general URL to show the syntax. To find your exact endpoint, please login to your ChurnZero tenant and visit the Application Key Page in Admin.
Batch Accounts via CSV
In order to support the loading of batch accounts, ChurnZero allows the ability to upload an Account csv file. The csv file must have a header; you can download a template containing all supported headers by going to Admin > Imports, selecting the Account entity, and hitting Export.
ChurnZero supports the following fields:
Required
- accountExternalId (string) - The accountExternalId is your unique record to identify your account. This ID should also be in your CRM.
Optional
- name (string)
- nextRenewalDate (date)
- totalContractAmount (double)
- isActive (Boolean)
- billingAddressLine1 (string)
- billingAddressLine2 (string)
- billingAddressCity (string)
- billingAddressState (string)
- billingAddressZip (string)
- billingAddressCountry (string)
- startDate (datetime)
- endDate (datetime)
- LicenseCount (int)
- OwnerUserAccount (string - matches on UserName)
- ParentAccountExternalId (string)
- cf_XXXX The custom field to be updated prefixed by "cf_".
Note: A custom field must already exist in ChurnZero in order for attributes to be sent to it via CSV. ChurnZero cannot create a new field via CSV -- but this can be done by sending attributes via HTTP API or JavaScript.
If you need help getting a field added, ask support@churnzero.net for help!
cURL
curl -i -X POST -H 'Content-Type: multipart/form-data' -F 'data=@accountsUpload.csv' 'https://yourvanitydomain.app.churnzero.net/batchAccountsCsv?appKey=123'
Batch Contacts via CSV
In order to support the loading of batch contacts, ChurnZero allows the ability to upload a Contact csv file. The csv file must have a header; you can download a template containing all supported headers by going to Admin > Imports, selecting the Contact entity, and hitting Export.
ChurnZero supports the following fields:
Required
- accountExternalId (string) - The accountExternalId is your unique record to identify your account. This ID should also be in your CRM.
- contactExternalId (string) - The contactExternalId must be unique within the account. This could be a email address, a unique record that is also contained in your CRM, or the ID of the contact record of your CRM.
Optional
- firstName (string)
- lastName (string)
- email (string)
- cf_XXXX The custom field to be updated prefixed by "cf_".
cURL
curl -i -X POST -H 'Content-Type: multipart/form-data' -F 'data=@ContactsUpload.csv' 'https://yourvanitydomain.app.churnzero.net/batchContactsCsv?appKey=123'
Historical/Batch Track Events via CSV
In order to support the loading of historical or a large set of events, ChurnZero allows the ability to upload an Event csv file. The csv file must have a header; you can download a template containing all supported headers by going to Admin > Imports, selecting the Event entity, and hitting Export.
ChurnZero supports the following fields:
- accountExternalId (required) - The accountExternalId is your unique record to identify your account. This ID should also be in your CRM.
- contactExternalId (required) - The contactExternalId must be unique within the account. This could be a email address, a unique record that is also contained in your CRM, or the ID of the contact record of your CRM.
- eventName (required) - This is the unique name of the event (ie. "Sent Blog Post"). If theEvent Name is not found it will be created.
- eventDate (required) - The date of the event (defaults to time of API call) in format ISO-8601 ("2012-03-19T07:22Z")
-
description (optional) - A description of this particular event (ie. blog title).
- Note: There is a 255 character limit on this field. If there are more than 255 characters included we will still process the event, the value will just be truncated to be within the limit.
- quantity (optional) - The number related to this event. (ie. Commonly used to track things like email sent, etc)
- cf_XXXX (optional) - The custom field to be updated prefixed by "cf_"
NOTE: By default, ChurnZero ignores duplicate events (same Date, Account, Contact and Description). The intent of this setting is to prevent duplicates from being created against existing data, so it does not impact duplicates within the same file unless the file is large enough to be broken up into batches. You can allow duplicates by adding '&allowDupes=true' at the end of your cURL.
EXAMPLE
cURL
curl -i -X POST -H 'Content-Type: multipart/form-data' -F 'data=@BatchEventUpload.csv' 'https://yourvanitydomain.app.churnzero.net/batchEventsCsv?appKey=123'
CSV Sample
Text
accountExternalId,contactExternalId,eventName,eventDate,quantity,description,cf_field1 2503568,2503466,Login,2017-01-19T15:10:30.1947888Z,,,fieldValue1-1 2503568,2503466,Send Email,2017-01-19T15:13:30.1947888Z,1,Email Sent,fieldValue1-2
Batch Custom Table Imports via CSV
A Custom Table is anything that appears on the Custom Tables tab of an Account within ChurnZero. These Custom Tables can be connected to your CRM (such as Opportunities or Deals), secondary integrations (such as Zendesk tickets, Intercom chats, financial details), or even Custom Tables that live solely in ChurnZero. If you are executing an import to a Custom Table that has edit access back to its source, this imported data will push back into those systems. If you have any questions about how to execute these imports or what it will look like with your current integration workflow, feel free to reach out to your ChurnZero Customer Success Manager or Implementation Specialist.
The csv file must have a header; you can download a template containing all supported headers by going to Admin > Imports, selecting your desired Custom Table entity, and hitting Export.
ChurnZero will support the following Custom Fields on your Custom Table:
Required Fields:
- accountExternalId (string) - The accountExternalId is your unique record to identify your account. This ID should also be in your CRM. This will allow the Custom Table to show on the correct account within ChurnZero
- Identifier- Each record in your Custom Table should have an identifier associated with it. The Identifier can be anything that your team chooses, as long as it's unique per record on the Custom Table. This identifier will allow the record on the Custom Table to be updated with future imports, rather than creating a new record on the Custom Table. You will need to let your Customer Success Manager or Implementation Specialist know what you have chosen as your Identifier field, so that the field can be configured appropriately.
Optional Fields:
To see a list of the Custom Fields with their corresponding CSV Column Header label on your Custom Tables, click on Admin > Imports > Select the Custom Table from the Entity drop-down. Make sure that your .csv file contains the exact naming convention that is shown in CSV Column Header.
cURL
curl -i -X POST -H 'Content-Type: multipart/form-data' -F 'data=@CustomTableupload.csv' 'https://yourvanitydomain.app.churnzero.net/batchCustomTableCsv?customTableId=X&appKey=XXX'
Where do I find my custom table ID and app key?
You can locate the Custom Table ID in ChurnZero by going to Admin > Imports > Change the Entity drop-down to be the Custom Table that you are importing to > Use the Api URL given.
You can locate the App Key of your ChurnZero Account by going to Admin > Application Keys.
Batch Import FAQs:
- The API Supports a Maximum File Size of 500 MB. You may have to break your information down into multiple files
- If you would like to receive an email letting you know the status of your import, just append an email address onto the parameter of the URL, for example:
- https://yourvanitydomain.app.churnzero.net/batchAccountsCsv?appKey=123&email=janedoe@churnzero.net
- If the column header exists in the import file, the value will be updated accordingly. This means that if you include a header with blank values underneath it, the values will be wiped to Null.
- We have a limit of 10 requests in 1 minute.
- If you have questions about the data formats for different field types, you can find more info on those in this article.
Comments
0 comments
Article is closed for comments.