WBP SYSTEMS / Developer Central / Heap Simple API

Heap Simple API

If you want to send information or retrieve information from Heap programmatically, you've come to the right place. Now, while we have made every effort to make Heap's API (application programming interface) as simple as possible, the reality is you need to have some knowledge of how websites work.

Creating Leads, Opportunities, Customers and Archives

Let's say I need to create a lead named Jane Doe who works at ACME Ltd. Ok so first I have to let Heap know who I am so I send the following variables (using POST):

login_email
login_password

Then I need to tell Heap that I want to create content, so I send the POST variable "create" with the value of "lead". I also could put any of the following in the create variable:

lead
opportunity
customer
archive
people
event
message

Ok, now I have to send the info about the new lead to Heap, I can use any of the following variables:

name
phone
fax
mobile
email
address
city
state
zip
title
country
url
probability
value
moreinfo
category
notes

If Heap can add the entry it will return the word "Success", otherwise it will return an error.

Creating People

Just like leads, opportunities, customers and archives, people are created with the same basic method. First I have to send login_email and login_password over POST. Then send the variable "create" with a value of "person". Ok, now I have to send info about the new person:

name
phone
fax
mobile
email
address
city
state
zip
title
country
url
category
notes

If Heap can add the entry it will return the word "Success", otherwise it will return an error.

Note about category:
On Leads, Opportunities, Customers, Archives and People, multiple categories can be specified by adding a unix new line between each category.

Note about duplicates:
The Leads, Opportunities, Customers, Archives and People, have three modes of duplicate checking:

"Replace duplicate" which will replace duplicates with the specified data (POST variable "replaceduplicate" should be set to "yes")
"Ignore duplicate" which will ignore duplicates (POST variable "ignoreduplicate" should be set to "yes")
Default, which will allow the creation of duplicates (based on name variable)

Creating Events

Ok let's create an event. First I have to send login_email and login_password over POST. Then send the variable "create" with a value of "event". Ok, now let's send the info about the event:

year
month
day
title
location
description
association
calendar
emailtemplate
complete

If Heap can add the event it will return the word "Success", otherwise it will return an error.

Creating Messages

Messages are the simplest items to create through the API. Just send login_email and login_password over POST. Then send the variable "create" with a value of "message". Then just create the message using the following variables:

title
body
association
category

If Heap can add the message it will return the word "Success", otherwise it will return an error.

Retrieving Leads, Opportunities, Customers and Archives

Ok, just like when you create content, you have to send login_email and login_password over POST when you retrieve information. But instead of "create" you send the POST variable "get" with one of the following values:

lead
opportunity
customer
archive
people
event
message

In this case we will send "lead". Now we need to tell Heap what we are looking for. There is a search variable name (creatively) "search", just POST the info that you are looking for to that variable. In this case I'm going to send "IBM".

Code:


<?xml version="1.0"?>
<result>
    <lead>
        <name>Josh Taylor - IBM</name>
        <title/>
        <phone>(000) 000-0000</phone>
        <mobile>(000) 000-0000</mobile>
        <fax/>
        <email>josh.taylor@ibm.com</email>
        <url/>
        <address>1 IBM Way</address>
        <city>Los Angeles</city>
        <state>CA</state>
        <zip>85012</zip>
        <country>United States</country>
        <update>May 25th</update>
        <probability>0.2500</probability>
        <value>5000.0000</value>
        <moreinfo/>
    </lead>
</result>

Retrieving People

Alright let's search for a person, just like before you send login_email and login_password over POST and send the variable "get" over POST with the value "people". This time I'm going to search for "bigfish.com" using the "search" variable (again sent over POST).

Code:


<?xml version="1.0"?>
<result>
    <person>
        <name>Jeff Martel - Big Fish Real Estate</name>
        <title/>
        <phone>000-000-0000</phone>
        <mobile>111-111-0000</mobile>
        <fax/>
        <email>jeff@bigfish.com</email>
        <url/>
        <address>123 Main ST
</address>
        <city/>
        <state/>
        <zip/>
        <country/>
        <notes/>
        <update>April 19th</update>
    </person>
    <person>
        <name>Laura Marceline - Big Fish Real Estate</name>
        <title/>
        <phone>000-000-0000</phone>
        <mobile>111-111-0000</mobile>
        <fax/>
        <email>laura@bigfish.com</email>
        <url/>
        <address>123 Main ST
</address>
        <city/>
        <state/>
        <zip/>
        <country/>
        <notes/>
        <update>April 19th</update>
    </person>
</result>

Retrieving Events

Ok, I want to retrieve any event associated to "Josh Taylor", so I am going to send login_email and login_password over POST and send the variable "get" over POST with the value "event" and search value of "Josh Taylor". Please note that the search variable also searches title of events, descriptions and locations. Ok here is what I get:

Code:


<?xml version="1.0"?> 
<result>
    <event>
        <date>May 8th</date>
        <title>Opera with Josh at 06:15 PM to 10:30 PM</title>
        <date>May 8th</date>
        <location/>
        <description/>
        <complete/>
        <association>Josh Taylor - IBM</association>
    </event>
    <event>
        <date>May 10th</date>
        <title>Create new proposal for Josh</title>
        <date>May 10th</date>
        <location/>
        <description/>
        <complete>1</complete>
        <association>Josh Taylor - IBM</association>
    </event>
</result>

Retrieving Messages

Ok, I want to retrieve any message associated to "Josh Taylor", so I am going to send login_email and login_password over POST and send the variable "get" over POST with the value "message" and search value of "Josh Taylor". Please note that the search variable also searches title of messages, poster of the message and message body. Ok here is what I get:

Code:


<?xml version="1.0"?> 
<result>
    <message>
        <title>Requirement Files</title>
        <body/>
        <creator>Ben Smith</creator>
        <emailedfrom/>
        <emailedto/>
        <update>May 8th</update>
        <association>Josh Taylor - IBM</association>
    </message>
</result>

Where do I post all this data?

http://SUBDOMAIN.crmondemand.biz/api.php

Your subdomain is the first part (before the first period) of the web address you use to login to your Heap account. So, for instance, the company above would sign in to their Heap account at http://creativearc.crmondemand.biz/. Thus their subdomain would be creativearc.