JavaScript API

The Drip client library has a number of API methods for performing tasks right from your website, such as manually subscribing users and tracking conversions. This document details everything you can do via our JavaScript API.

Installing Your JavaScript Snippet

To interact with the JavaScript API, you'll need to have your Drip snippet installed on your website. Each Drip account has a unique snippet that can be found under Settings → Site Setup.

How to Send an API Request

All requests follow the same conventions. If you've ever worked with the Google Analytics API, the sematics should look familiar. This is the basis structure of an API request:

_dcq.push(["methodName", { key: "value", ... }]);
API requests are executed asynchronously, so you may safely place then anywhere on the page (even above the Drip snippet).

Methods

Attach Identifying Data to Visitors

The identify method pushes subscriber data into Drip. If the subscriber is not yet in your account, we will create a new record for them; otherwise, we update their record with the information you pass in. To update a subscriber's email address, use the new_email property.

Example Request

_dcq.push(["identify", {
  email: "john@acme.com",
  first_name: "John",
  tags: ["Customer"]
}]);

Properties

The following are treated as special properties. All other data passed in will be added to the subscriber's custom fields. Keys should be lowercase, with words separated by underscores.

Key Description
email Optional. The subscriber's email address.
new_email Optional. Use this to update an existing subscriber's email address
user_id Optional. A unique identifier for the user in your database, such as a primary key.
tags Optional. An Array of tags to apply.
remove_tags Optional. An Array of tags to remove.
prospect Optional. A Boolean specifiying whether we should attach a lead score to the subscriber (when lead scoring is enabled). Defaults to true. Note: This flag used to be called potential_lead, which we will continue to accept for backwards compatibility.
success Optional. A callback function that is executed upon successful completion of the request.
failure Optional. A callback function that is executed if the request fails.

Response

The identify request will pass a response object to the success or failure callback functions (if provided) once the call completes.

Key Description
success Boolean. True if the call to Drip succeeded.
visitor_uuid The unique id for the visitor identified.
anonymous Boolean. False if the visitor is associated with a subscriber.
email Included only if the visitor is not anonymous. The associated subscriber's email address.
custom_fields An Object containing custom fields that are marked as public in your settings (see Subscribers > Custom Fields). Custom fields containing sensitive information should not be marked as public, for security purposes.
tags An array of the subscriber's tags.
lead_score Included if the subscriber is a prospect.
error String. Contains an error message if the request failed.

Example response

{
  success: true,
  visitor_uuid: "f627ee608adb01315d1022000ab2058a",
  anonymous: false,
  email: "john@acme.com",
  custom_fields: { "name": "John" },
  tags: ["Customer"],
  lead_score: 35
}

Apply a tag via the query string

You can also tag visitors by appending a dst query string parameter to the URL of a page that has the Drip JavaScript installed. For example, the following url will tag vistitors with Customer:

http://www.mysite.com?dst=Customer

Track an Event or Conversion

The track method is appropriate when you cannot trigger conversions by URL or you simply wish to record an particular action that the user has taken. The second argument is the name of the action to be recorded. If the action matches the name of a goal, then we will trigger a conversion.

Example Request

_dcq.push(["track", "Signed up for a trial", { value: 2000 }]);

Properties

The following are treated as special properties. All other data passed in will be saved as custom event properties.

Key Description
value Optional. An Integer value (in cents). If the event triggers a conversion, this will be used as the conversion value. Must be within the range of 0 to 2,147,483,648.
occurred_at Optional. The String time at which the event occurred in ISO-8601 format. Defaults to the current time.
success Optional. A callback function that is executed upon successful completion of the request.
failure Optional. A callback function that is executed if the request fails.

Response

The track request will return a response object that can be passed into the callback functions.

Key Description
success Boolean. True if the call to Drip succeeded.
visitor_uuid The unique id for the visitor identified.
anonymous Boolean. False if the visitor is associated with a subscriber.
error String. Contains an error message if the request failed.

Example response

{
  success: true,
  visitor_uuid: "f627ee608adb01315d1022000ab2058a",
  anonymous: false
}

Subscribe to a Campaign

This method will add a subscriber directly to campaign. If you would like to add a subscriber to your account without subscribing them to a campaign, use an identify call instead.

Example Request

_dcq.push(["subscribe", { campaign_id: "9999999", fields: { email: "john@acme.com" }}]);

Arguments

Key Description
campaign_id Required. The String campaign ID, which can be found on the campaign settings page.
fields Required. An Object containing the user's data. At minimum, this object must contain an email attribute. If there are any required custom fields, these attributes must also be present.
double_optin Optional. If true, the double opt-in confirmation email is sent; if false, the confirmation email is skipped. Defaults to the value set on the campaign.
success Optional. A callback function that is executed upon successful completion of the request.
failure Optional. A callback function that is executed if the request fails.

Unsubscribe a Subscriber

Use this method to unsubscribe a subscriber from one or all of your campaigns.

Example Request

_dcq.push(["unsubscribe", { campaign_id: "9999999", email: "john@acme.com" }]);

Arguments

Key Description
email Required. The String email address of the subscriber you wish to unsubscribe.
campaign_id Optional. The String campaign ID, which can be found on the campaign settings page. If not included, the subscriber will be unsubscribed from all campaigns.
success Optional. A callback function that is executed upon successful completion of the request.
failure Optional. A callback function that is executed if the request fails.

Open & Close a Form Widget

Example Request

_dcq.push(["showForm", { id: "9999999" }]);
_dcq.push(["hideForm", { id: "9999999" }]);

Arguments

Key Description
id Required. The String form ID, which can be found on the form settings page.
showTab Optional. If true, the teaser tab will show when the form is closed. Defaults to true.

Events

Form Submission Events

If jQuery is available on your page, the following events are triggered as the widget is submitted:

Event Fired when...
submitting.drip a form submit button is clicked.
submitFailed.drip a form submission fails.
submitted.drip a form submission succeeds.

By listening for these events, you can hook your own javascript onto the widget's actions. Each of the above events carries a data Object with the form's information.

Example Listener

$(document).on("submitted.drip", function(ev, data){
  console.log(data);
})

Example Event Data

{
  "account_id": "999999",
  "fields[email]": "john@acme.com",
  "fields[first_name]": "John",
  "form_id": "999999",
  "page_title": "Drip :: Email Marketing Automation for Visitors, Trials and Customers",
  "submit": "Let's do it!",
  "time_zone": "America/Los_Angeles",
  "url": "https://www.getdrip.com/",
  "visitor_uuid": "f627ee608adb01315d1022000ab2058a"
}