Push API

Example Message Format

The Push API sends messages about events that occur in our system to one or more endpoints you specify. Theses messages contain data describing what kind of event occurred and what object it happened to.

Messages are sent via HTTPS POST requests. The body of the request is a JSON encoded array of message objects. A sample request body is shown below.

Name Data Type Description
data Object Data about the resource. The structure of this object depends on the resource. See resource type documentation below.
event String The event that occurred. Either 'created', 'updated', or 'deleted'.
resource String The type of resource the message is about.
time DateTime The time that the event occurred.

Example

[
  {
    "resource": "contact",
    "event": "updated",
    "time": "2015-02-26T19:39:18+00:00",
    "data": {
      "name": "John Doe",
      "company": "Compnay Name",
      "salutation": "Mr",
      "address1": "7 Mellor Ave",
      "address2": "",
      "country": "Canada",
      "city": "Dartmouth",
      "state": "Nova Scotia",
      "zip": "B3B 0E8",
      "email": "john.doe@example.com",
      "fax": "",
      "phone": "+19028358974",
      "mobile": "",
      "twitter": "",
      "email_unlimited": false,
      "title": "Developer",
      "Website": "",
      "id": 70225,
      "lists": [4, 8]
    }
  },
  {
    "resource": "note",
    "event": "created",
    "time": "2015-02-26T19:41:00+00:00",
    "data": {
      "id": 133,
      "text": "This is a note about a contact.",
      "contact": "70225",
      "author": "AccountLogin#8000188",
      "created": "2015-02-27T00:40:58+00:00",
      "modified": "2015-02-27T00:40:58+00:00"
    }
  }
]

HMAC Signature

To help you verify that messages your endpoint receives are authentic all requests we send are signed with a HMAC signature. You can view and reset the secret key associated with each of your endpoints in your account settings. Every request has a 'Content-MD5' header which is a base 64 encoded MD5 hash of the request body. Requests also have 'Date' header which specifies when the message was sent. Finally, requests have an 'Authorization' header which contains a SHA1 HMAC signature. The signature is formed by combining the encoded MD5 of the body and the Date header. These two fields are separated by a new line.

Below are example headers:


Content-MD5: MGE4OGY5OGFjNTBkNjE4OTk5OTM3YTJjYTFhMblmZmQ= 
Date: Mon, 02 Mar 2015, 10:44:17 EST
Authorization: HMAC OTM2ZTQ1NzVjNGU4NTY4YjRjM2EzYjg1YjY1MzZjYjUzNWFlN2FhYg==
  


In the above example, the HMAC signature could be generated with:


$hmac = base64_encode(hash_hmac(
  'sha1',
  "MGE4OGY5OGFjNTBkNjE4OTk5OTM3YTJjYTFhMblmZmQ=\nMon, 02 Mar 2015, 10:44:17 EST",
  'my secret key'
));
    

We sugget checking this signature on each request your endpoint receives. The below PHP code shows how to do this.


$body = file_get_contents("php://input");
$headers = getallheaders();

$md5 = $headers['Content-MD5'];
$date = $headers['Date'];
list($authType, $encodedHMAC) = split(' ', $headers['Authorization']);

if (md5($body) != base64_decode($md5)) {
  die('MD5 does not match.');
}

$secretKey = 'bd414df87bba5770e19b47e119b28588ac12ca92';
$dataToHash = "$md5\n$date";
$expectedHMAC = base64_encode(hash_hmac('sha1', $dataToHash, $secretKey));

if (!hash_equals($expectedHMAC, $encodedHMAC)) { 
  die('HMAC signature incorrect.');
}
  


Failed Requests

Messages are assumed to have been successfully delivered if your endpoint returns a status code of 200. If your endpoint does not return a status code of 200 we will attempt to send you the message again after some time. We will stop trying to resend the message after several failed send attempts.



Resource Types

contact

Contact messages provide information about events that happened to contacts. In addition to the properties listed below, the data object will also include custom columns you have created.

Note that 'updated' events indicate that a value of a contact column was modified, while 'listsChanged' events indicate that there was a change in the lists that the contact is on.

The table below shows the fields that will be present in the 'data' property of the message.

Name Data Type Description
Website String Website of the contact.
address1 String First line of the contact's address.
address2 String Second line of the contact's address
city String City associated with the contact.
company String Company the contact is associated with.
country String Country the associated with the contact.
email String Email address of the contact.
id String ID of the contact.
lists Collection<Integer> The IDs of the lists the contact is on.
mobile String Mobile number of the contact.
name String Name of the contact.
phone String Phone number of the contact.
state String State associated with the contact.
title String Job title of the contact.
twitter String Twitter handle of the contact.
zip String ZIP code associated with the contact.
Events: created, updated, deleted, listsChanged

Example

[
  {
    "resource": "contact",
    "event": "updated",
    "time": "2015-02-26T19:39:18+00:00",
    "data": {
      "name": "John Doe",
      "company": "Company",
      "salutation": "Mr",
      "address1": "7 Mellor Ave",
      "address2": "",
      "country": "Canada",
      "city": "Dartmouth",
      "state": "Nova Scotia",
      "zip": "B3B 0E8",
      "email": "john.doe@example.com",
      "fax": "",
      "phone": "+19028358974",
      "mobile": "",
      "twitter": "",
      "title": "Developer",
      "Website": "",
      "lists": [3, 8, 13]
      "id": 70225
    }
  }
]

contactMetadata

Contact metadata messages provide information about changes to the metadata associated with contacts. Metadata includes all of the data associated with contacts that is not stored as list columns. This may include fields that are not documented here.

The table below shows the fields that may be in the 'data' property of the message.

Name Data Type Description
account_manager Integer ID of account manager.
acquisition_cost Integer The cost to acquire the lead.
ad_content Collection<String> The content of the ads.
ad_medium Collection<String> The mediums of the ads.
ad_source Collection<String> The sources of the ads.
email_sends Integer Number of email sends.
hotness Integer How hot the lead is.
id Integer The ID of the contact.
link_clicks Integer Number of tracking link clicks.
mobile_deliveries Integer Number of SMS deliveries.
mobile_sends Integer Number of SMS sends.
potential_value Integer The potential value of the lead.
purchase_amount Integer The amount purchased by the lead.
score Integer The score of a lead.
search_term Collection<String> Search terms associated with lead.
site_category Collection<String> Categories for the site.
tags Collection<String> Tags on the contact.
voice_deliveries Integer Number of voice deliveries.
voice_sends Integer Number of voice sends.
Events: updated

Example

[
  {
    "resource": "contactMetadata",
    "event": "updated",
    "time": "2015-02-27T17:17:32+00:00",
    "data": {
      "id": 70206,
      "link_clicks": 0,
      "email_sends": 0,
      "email_opens": 0,
      "email_link_clicks": 0,
      "voice_sends": 0,
      "voice_deliveries": 0,
      "fax_sends": 0,
      "fax_deliveries": 0,
      "mobile_sends": 0,
      "mobile_deliveries": 0,
      "tags": [],
      "score": 0,
      "hotness": 0,
      "account_manager": 8000188,
      "ad_source": [],
      "ad_medium": [],
      "ad_campaign": [],
      "ad_content": [],
      "search_term": [],
      "acquisition_cost": 0,
      "potential_value": 0,
      "purchase_amount": 0,
      "site_category": []
    }
  }
]

timelineEntry

Messages about timeline events indicate changes to timeline events. Timeline events may be events that happened to contacts or other resources.

The table below shows the fields that will be present in the 'data' property of the message.

Name Data Type Description
browser String Web browser related to the event.
id Integer ID of the timeline event.
ip String IP address related to the event.
latitude String Latitude the event occurred at.
longitude String Longitude the event occurred at.
metadata Object Metadata about the event.
os String Operating system related to the event.
ownerId Integer ID of the owner of the event.
ownerType String Type of resource the timeline event is about.
time DateTime Time the event occurred at.
Events: created

Example

[
  {
    "resource": "timelineEntry",
    "event": "created",
    "time": "2015-02-27T17:17:32+00:00",
    "data": {
      "id": "271",
      "ownerType": "contact",
      "ownerId": "70206",
      "time": "2015-02-27T22:17:30+00:00",
      "ip": null,
      "latitude": null,
      "longitude": null,
      "os": null,
      "browser": null,
      "metadata": {
        "action": "metadata set",
        "column": null,
        "new": "8000188",
        "login": "8000188"
      }
    }
  }
]

note

Note messages provide information about changes to notes.

The table below shows the fields that will be present in the 'data' property of the message.

Name Data Type Description
author Integer The ID of the account login that created the note.
created DateTime The date the note was created.
id Integer The ID of the note.
modified DateTime The date the note was last modified.
text String The text contents of the note.
Events: created, deleted

Example

[
  {
    "resource": "note",
    "event": "created",
    "time": "2015-02-27T17:32:33+00:00",
    "data": {
      "id": 134,
      "text": "This is a note",
      "contact": "70206",
      "author": "AccountLogin#8000188",
      "created": "2015-02-27T22:32:31+00:00",
      "modified": "2015-02-27T22:32:32+00:00"
    }
  }
]

task

Task messages provide information about changes to tasks.

The table below shows the fields that will be present in the 'data' property of the message.

Name Data Type Description
created DateTime The date the task was created.
due DateTime The date the task is due.
id Integer The ID of the task.
modified DateTime The date the task was last modified.
owner Integer The ID of the contact that the task is related to.
priority Integer The priority of the task. May be 1, 2, or 3.
status String May be 'new', 'in-progress', or 'completed'.
text String A description of the task.
title String The title of the task.
Events: created, updated, deleted

Example

[
  {
    "resource": "task",
    "event": "updated",
    "time": "2015-02-27T17:38:34+00:00",
    "data": {
      "id": "135",
      "title": "My New Task",
      "status": "in-progress",
      "priority": 1,
      "text": "Here are some details about my task.",
      "owner": "70206",
      "created": "2015-02-27T22:37:49+00:00",
      "due": "2015-02-28T18:37:55+00:00",
      "modified": "2015-02-27T22:37:49+00:00"
    }
  }
]

list

List messages provide information about changes to lists. This includes when a list is created, a list is renamed, and a list is deleted.

The table below shows the fields that will be present in the 'data' property of the message.

Name Data Type Description
created DateTime The date the list was created.
id Integer The ID of the list.
name String The name of the list.
Events: created, updated, deleted

Example

[
  {
    "resource": "list",
    "event": "created",
    "time": "2015-02-27T17:38:34+00:00",
    "data": {
      "id": "135",
      "name": "My New List",
      "created": "2015-02-27T22:37:49+00:00",
    }
  }
]