Heap POST/JSON WebHook

Heap CRM supports a universal JSON, POST or GET (not recommended) request to the webhook url (available under the help section) that creates a person, prospect or message. Most programming languages have built in functions for creating JSON payloads (e.g. PHP, Ruby, Java).

A typical JSON payload might look like this (this should be placed in the POST variable “json” – you can also send data directly to the POST variables):

Code:

{
    "name": "John Doe - ACME",
    "title": "Owner",
    "email": "john@doe.com",
    "phone": "000.000.0000",
    "mobile": "000.000.0000",
    "fax": "000.000.0000",
    "address": "123 Main St.",
    "city": "Any Town",
    "state": "WA",
    "zip": "00000",
    "country": "USA",
    "website": "http://www.doe.com",
    "notes": "Notes",
    "categories": ["Category One", "Category Two"],
    "customvalue": "My Custom Response"
}

Heap is smart enough to just add new people and ignore duplicates (though it updates contact info and person level custom values if possible).

By adding a value, probability and more info field, Heap realizes this is a lead (once Heap is creating a prospect you can also post into transaction level custom values):

Code:

{
    "name": "John Doe - ACME",
    "title": "Owner",
    "email": "john@doe.com",
    "phone": "000.000.0000",
    "mobile": "000.000.0000",
    "fax": "000.000.0000",
    "address": "123 Main St.",
    "city": "Any Town",
    "state": "WA",
    "zip": "00000",
    "country": "USA",
    "website": "http://www.doe.com",
    "notes": "Notes",
    "categories": ["Category One", "Category Two"],
    "value": "100",
    "probability": ".5",
    "moreinfo": "",
    "type": "lead",
    "template": "New Lead"
}

A message payload might look like this:

Code:

{
    "title": "Talked to the Client",
    "body": "Spent time with client nn[category:Meetings]n[event:+1 Week:Follow-up with client]",
    "files": ["http://example.com/file.pdf", "http://example.com/file2.pdf"]
}

The body variable will be parsed for advanced e-mail operators as described in this document (it will also be parsed for “[association:Name of Prospect]” despite that not being a normal message operator). In addition to the optional “files” array containing urls, you can also simply POST files as part of the webhook url request.

If you want to run a series of advanced e-mail commands without actually creating a message, you can do that as well. Just send the variable “simulate” with a value of “true”.

You can also retrieve prospect data in JSON format by adding the GET or POST variable “search” with a search phrase. A typical JSON response might look like this:

Code:

[{
    "name": "Mandie Customer - ACME",
    "title": "",
    "email": "mandie@acme.com",
    "phone": "(000) 000-0000",
    "mobile": "",
    "address": "",
    "city": "",
    "state": "",
    "zip": "",
    "country": "",
    "probability": "0.6500",
    "value": "600.0000",
    "expectedvalue": "390",
    "website": "",
    "moreinfo": "Need a new ad campaign designed for ACME"
},
{
    "name": "New Person - ACME",
    "title": "",
    "email": "",
    "phone": "",
    "mobile": "",
    "address": "",
    "city": "",
    "state": "",
    "zip": "",
    "country": "",
    "probability": "0.0000",
    "value": "0.0000",
    "expectedvalue": "0",
    "website": "",
    "moreinfo": "Description of Transaction"
}]

The webhook uses the same advanced search system that you use within Heap. You can retrieve people data instead of prospect data if you set the GET or POST variable “searchpeople” to “true”.

Retreive prospect activity statistics or history if you set the GET or POST variable “stats” or “history” to “true”:

Code:

{
    "history": "7",
    "messages": "4",
    "events": "1"
}

Code:

[{
    "date": "September 15th, 2010",
    "type": "lead",
    "probability": "0.4000",
    "value": "100.0000",
    "expectedvalue": "40.0000"
},
{
    "date": "September 15th, 2010",
    "type": "archive",
    "probability": "0.4000",
    "value": "100.0000",
    "expectedvalue": "40.0000"
},
{
    "date": "September 15th, 2010",
    "type": "customer",
    "probability": "0.4000",
    "value": "100.0000",
    "expectedvalue": "40.0000"
},
{
    "date": "June 29th, 2010",
    "type": "lead",
    "probability": "0.4000",
    "value": "100.0000",
    "expectedvalue": "40.0000"
},
{
    "date": "June 29th, 2010",
    "type": "lead",
    "probability": "0.3500",
    "value": "100.0000",
    "expectedvalue": "35.0000"
},
{
    "date": "June 29th, 2010",
    "type": "customer",
    "probability": "0.3500",
    "value": "100.0000",
    "expectedvalue": "35.0000"
},
{
    "date": "June 29th, 2010",
    "type": "opportunity",
    "probability": "0.3500",
    "value": "100.0000",
    "expectedvalue": "35.0000"
}]

You can retrieve e-mail templates by setting the GET or POST variable “list” to “emailtemplates”:

Code:

[{
    "subject": "[event name] [event location]",
    "body": "[event description]nnSome more textnn[convert to: lead]"
},
{
    "subject": "Hello Friends!",
    "body": "Just wanted to say hi, and let you know we really appreciate your business!"
}]

You could also limit the list of email templates by specifiying the template subject line. For instance you could set the variable “list” to “emailtemplates Hello”:

Code:

[{
    "subject": "Hello Friends!",
    "body": "Just wanted to say hi, and let you know we really appreciate your business!"
}]

You can also list events. Specifically, you will get any uncompleted events that you own and any uncompleted events that are associated to a prospect where you are a managing user. If I set the the variable “list” to “events”, I would get:

Code:

[{
    'description': '',
    'title': 'Holiday Follow-up',
    'location': '',
    'key': '425617',
    'date': 'Feb 1st, 2011',
},
{
    'description': 'See John about WebSite',
    'title': 'My Breakfast Meeting at 08:30 AM to 09:30 AM',
    'location': 'The Teahouse',
    'key': '385722',
    'calendar': 'Tasks',
    'date': 'Feb 6th, 2011',
    'association': 'John Doe - ACME'
}]

Just like email templates, you can filter events. Just specify the prospect that the event is associated to. If I set the variable “list” to “events John” I get:

Code:

[{
    'description': 'See John about WebSite',
    'title': 'My Breakfast Meeting at 08:30 AM to 09:30 AM',
    'location': 'The Teahouse',
    'key': '385722',
    'calendar': 'Tasks',
    'date': 'Feb 6th, 2011',
    'association': 'John Doe - ACME'
}]

Additionally, you can create email templates by sending the variables “subject” and “body” to the webhook.

You can also list messages. If I set the variable “list” to “messages ” I get:

Code:

[{
    'body': 'We were referred by [custom=friend], they thought you ...',
    'edited': 'Jun 22nd, 2011',
    'emailfrom': '"Ben Smith" <ben@wbpsystems.com>',
    'user': 'Ben Smith',
    'key': '538824',
    'subject': 'Hi Matthew!',
    'emailto': '"Matthew Mullenweg - Automatic" <matt@automatic.com>',
    'emaildate': 'June 22nd, 2011',
    'association': 'Matthew Mullenweg - Automatic',
    'posted': 'Jun 22nd, 2011'
}]  

Report activity and the pipeline can also be listed. If I set the variable “list” to “pipeline expected value” (value and count work in a similar way), I get:

Code:

{
    "lead": "2000",
    "opportunity": "1000",
    "customer": "100"
}

To filter the report value on category, user or label use the variables:

  1. category
  2. user
  3. mylabel
  4. label

Listing activity reports works similar to the pipeline. Instead of setting the list variable to “pipeline count” (or value/expected value), set it to “activity count”. You may filter the report using the same category, user and label variables as the pipeline. Additionally, you can use “range” and “date” to specify the date and range of activity.

There is some Google Apps Scripts sample code retrieving data in this method available here.