Articles in this section

See more

Integrate ChurnZero using HTTP API

Avatar
Peter Watt
  • Updated
Follow

This article covers the HTTP API, which allows our customers to PUSH data to ChurnZero.
If you are looking for information on the REST API, which allows our customers to PULL data from ChurnZero, you can find the Developer's Reference here. 

 

For some attributes and events, it is easier to integrate on the server instead of Javascript.

Javascript code snippet required for certain features
Please note, that if you decided to set attributes and log events exclusively via the API, the Javascript Code Snippet is still required if you wish to use the success panel to communicate to your client directly inside your application.

Quick Links

Track Events
Set Attribute for Account or Contact
Increment Attribute for Account or Contact
 Time In App

HTTP API Overview

To simplify integration, all calls are done via an HTTP GET or POST(x-www-form-urlencoded or application/json) request and always respond with HTTP 200 Response code and a 1x1 transparent GIF image. Every request must include your appKey which can be found on the Admin > AppKey Page.

Both events and attribute updates can be sent via the HTTP API.

All calls must include the appKey, account identifier and contact identifier. See this page (Tell ChurnZero Who You and the User Are) to understand what these values should be.

 

Looking for advanced security verification?
Checkout our documentation on configuring Enhanced Identity Verification!

 

EXAMPLES

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.


HTTP GET

https:///i?appKey={appkey}&accountExternalId={accountExternalId}&contactExternalId={contactExternalId}&action=...


HTTP POST (x-www-form-urlencoded)

POST /i HTTP/1.1
Host: https:///i
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

appKey={appKey}&accountExternalId={accountExternalId}&contactExternalId={contactExternalId}&action=....

 

HTTP POST (applicaton/json)

POST /i HTTP/1.1
Host: https:///i
Content-Type: application/json
Cache-Control: no-cache


{
  "appKey": "{appKey}", 
  "accountExternalId": "{accountExternalId}",
  "contactExternalId": "{contactExternalId}",
  "action": "...",
}



HTTP POST (application/json)

POST /i HTTP/1.1
Host: https:///i
Content-Type: application/json
Cache-Control: no-cache

[
  {
    "appKey": "{appKey}", 
    "accountExternalId": "{accountExternalId}",
    "contactExternalId": "{contactExternalId}",
    "action": "...",
  },
  {
    "appKey": "{appKey}", 
    "accountExternalId": "{accountExternalId}",
    "contactExternalId": "{contactExternalId}",
    "action": "...",
  }
]

_________________________________________________________________________________________________________________

Track Events

To track an event, call the HTTP Get "trackEvent" action Api with the additional parameters:

  • action (required) - Must be 'trackEvent'.
  • eventName (required) - This is the unique name of the event (ie. "Sent Blog Post"). If the Event Name is not found it will be created.
  • eventDate (optional) - 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)
  • allowDupes (optional) - By default ChurnZero ignores duplicate events (same Date, Account, Contact and Description). Set this parameter to "true" to allow duplicate events.
  • cf_XXXX (optional) - The custom field to be updated prefixed by "cf_". You must create this custom field in Admin > Custom Fields > Events  BEFORE you begin sending data for this field, or it will end up in the Description field of the Event

EXAMPLE

This example tracks the event "Email Sent" with a description of "Email Subject", quantity of 5 and custom field "field1" to "fieldValue1".
HTTP

https:///i?appKey=123&accountExternalId=456&contactExternalId=789&action=trackEvent&eventName=Email+Sent&description=Email+Subject&quantity=5&cf_field1=fieldValue1

_________________________________________________________________________________________________________________

Set Attribute for Account or Contact

To set a value for a single attribute, call the HTTP Get 'setAttribute' with the following additional parameters:

  • action (required) - Must be 'setAttribute'
  • entity (required) - Can be either 'contact' or 'account'.
  • name (required) - Name of attribute to be updated.
  • value (required) - New value of attribute.

EXAMPLE

This example sets the Account attribute "Total Email Sent" to a value of 5.

HTTP

https:///i?appKey=123&accountExternalId=456&action=setAttribute&entity=account&name=Total+Email+Sent&value=5
To set a value for multiple attributes, call the HTTP Get "setAttribute" with the following additional parameters:
  • action (required) - Must be 'setAttribute'.
  • entity (required) - Can be either 'contact' or 'account'.
  • attr_XXXX (required) - Name of attribute to be updated prefixed by "attr_".

This example sets the Account attribute "Total Email Sent" to a value of 5 and sets the attribute "Email Enabled" to true.

HTTP

https:///i?appKey=123&accountExternalId=456&contactExternalId=789&action=setAttribute&entity=account&attr_Total+Email+Sent=5&attr_Email+Enabled=true

If you want to set the attribute to NULL this can be done by passing "null" as value. For example:

HTTP

https:///i?appKey=123&accountExternalId=456&contactExternalId=789&action=setAttribute&entity=account&name=Total+Email+Sent&value=null
Note: For account attributes, you can set 'contactExternalId' to null.

 

Updatable Standard Fields (Account and Contact)

For both forms of the setAttribute method, only the following standard fields (in addition to the custom fields) can be updated.

Note: Custom Tables cannot be updated with the setAttribute call. You can use Batch Imports to update Custom Table records

IMPORTANT:

  If your company's ChurnZero instance will be connected to your company's CRM (Salesforce, HubSpot, Pipedrive, etc.), by default that ALL of these standard account and contact attributes will be populated by your CRM. If your CRM is not the best source of accurate data for these fields, you can provide these values through the API instead. But please coordinate with your ChurnZero CSM to make sure that your CRM sync will not update fields you will be updating via the API. The same field in ChurnZero should not have two sources of data. 

Standard Account Fields   attr_xxxx

  • Name (string)
  • NextRenewalDate (date)
  • TotalContractAmount (double)
  • IsActive (Boolean)
  • BillingAddressLine1 (string)
  • BillingAddressLine2 (string)
  • BillingAddressCity (string)
  • BillingAddressState (string)
  • BillingAddressZip (string)
  • StartDate (datetime)
  • EndDate (datetime)
  • LicenseCount (int)
  • OwnerUserAccount (string - matches on UserName)
  • ParentAccountExternalId (string)

Standard Contact Fields

  • FirstName (string)
  • LastName (string)
  • Email (string)
_________________________________________________________________________________________________________________

Increment Attribute for Account or Contact

To increment an attribute by a certain amount (numbers only), call the HTTP Get 'incrementAttribute' with the following additional parameters.

  • action (required) - Must be 'incrementAttribute'.
  • entity (required) - Can be either 'contact' or 'account'.
  • name (required) - Name of attibute to be updated.
  • value (required) - Value to add to current value (can be positive or negative).

EXAMPLE

This example increments the Account attribute "Total Email Sent" by 3.

HTTP

https:///i?appKey=123&accountExternalId=456&action=incrementAttribute&entity=account&name=Total+Email+Sent&value=3

 

To increment multiple attributes by a certain amount (numbers only), call the HTTP Get 'incrementAttribute' with the following additional parameters.

  • action (required) - Must be 'incrementAttribute'.
  • entity (required) - Can be either 'contact' or 'account'.
  • attr_XXXX (required) - Name of attribute to be updated prefixed by "attr_" with a value to add to the current value (can be positive or negative).

This example increments the Account attribute "Total Email Sent" by 3 and increments the attribute "Total Tweets" by 10.

HTTP

https:///i?appKey=123&accountExternalId=456&contactExternalId=789&action=incrementAttribute&entity=account&attr_Total+Email+Sent=3&attr_Total+Tweets=10
_________________________________________________________________________________________________________________

Time In App

To track Contact Time In App, call the HTTP Get 'trackTimeInApp' with the following additional parameters:

  • action (required) - Must be 'trackTimeInApp'.
  • startDate(required) - The start date of the time in app in format ISO-8601 ("2012-03-19T07:22Z")
  • endDate(required) - The end date of the time in app in format ISO-8601 ("2012-03-19T07:22Z")
  • module (optional) - Name of the module the contact used (if not specific uses 'Default')

cURL

https:///i?appKey=123&accountExternalId=456&contactExternalId=789&action=trackTimeInApp&startDate=2018-01-11T12:41:54.1938202Z&endDate=2018-01-11T12:49:54.1938202Z&module=Test

Related articles

Comments

0 comments

Article is closed for comments.