REST API

This document outlines the official specification for the Drip RESTful API. This API communicates exclusively in JSON over SSL (HTTPS). All endpoint URLs begin with https://api.getdrip.com/v2/. Parameters must be serialized in JSON and passed in the request body (not in the query string or form parameters). This API is modeled after earlier versions of the JSON API specification. It is recommended that you use the media type designation of application/vnd.api+json with your API requests, although the API will accept a media type designation of application/json.

Authentication

We offer both token-based authentication (intended for private integrations), and full OAuth 2 authentication (for public integrations).

Token-Based

For private integrations with Drip, you may use the API token linked to your user account. Token authentication occurs via HTTP Basic Auth. Simply pass your API token in for the basic auth username (the -u flag in curl):

curl -H 'User-Agent: Your App Name (www.yourapp.com)' \
  -u f4ff6a200e850131dca1040cce1ee51a: \
  -d status=active \
  https://api.getdrip.com/v2/9999999/campaigns

OAuth

For public integrations with Drip, you must use OAuth based authentication. Here's a quick overview of how to get going.

  1. Get your favorite OAuth library
  2. Register your application with us under your user settings. We will then supply you with an client id and client secret. Please be aware that you must also enter a valid callback url before you will be able to activate your application.
  3. Configure your OAuth client with the credentials supplied to you when you created your application. Request authorization at:

    https://www.getdrip.com/oauth/authorize
    You should only have to do this once, as tokens do not expire.
  4. Activate your application and you're on your way!

If you're not going to use a library and will be rolling your own OAuth 2 client, here's the long form of how you can get going.

  1. First and foremost remember to register your app with us as outlined above.
  2. Once you have registered your app, it will then need to request authorization by redirecting your user to the following url:

    https://www.getdrip.com/oauth/authorize?response_type=code&client_id=<your_client_id>&redirect_uri=<your_redirect_uri>
  3. We will then authenticate their Drip account and ask if it's ok to give access to your app.
  4. The user will then be redirected back to your app with a verification code that will expire in 10 minutes.
  5. Your app will then need to make a request to trade that verification code for an access token:

    POST https://www.getdrip.com/oauth/token?response_type=token&client_id=<your_client_id>&client_secret=<your_client_secret>&code=<your_verification_code>&redirect_uri=<your_redirect_uri>&grant_type=authorization_code
  6. We will then authenticate your app and issue you an access token:

    {
      "access_token":"822bbf7cd12243df...",
      "token_type":"bearer",
      "scope":"public"
    }
    
  7. You can now use that access token in the header of your API requests as follows:

    Authorization: Bearer 822bbf7cd12243df...

Errors

Drip responds to invalid requests in a number of different ways. Exceptions to these rules will be noted for any applicable endpoints. Assume authentication is required on all endpoints unless otherwise noted.

If you attempt to anonymously access a resource that requires authentication, you will receive a 401 Unauthorized response:

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=utf-8
WWW-Authenticate: Basic realm="Application"
HTTP Basic: Access denied.

If you are authenticated but attempt to access a resource for which you do not have sufficient permissions, you will receive a 403 Forbidden response.

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.api+json
{
  "errors": [{
    "code": "authorization_error",
    "message": "You are not authorized to access this resource"
  }]
}

If the resource is not found, you will receive a 404 Not Found response:

HTTP/1.1 404 Not Found
Content-Type: application/vnd.api+json
{
  "errors": [{
    "code": "not_found_error",
    "message": "The resource you requested was not found"
  }]
}

Validation Errors

If validation errors occur while attempting to create or update a resource, you will receive a 422 Unprocessable Entity response with an errors object detailing which attributes are invalid. One of the following codes will assigned to each error object:

Code Description
presence_error The attribute is required.
length_error The length of the attribute is out of bounds.
uniqueness_error The attribute must be unique.
email_error The attribute must be a valid email address.
url_error The attribute must be a valid URL.
domain_error The attribute must be a valid domain name.
time_error The attribute must be a valid time in ISO-8601 format.
email_address_list_error The attribute must be a valid comma-separated list of email addresses.
days_of_the_week_error The attribute must be a valid days of the week mask of the format
/\A(0|1){7}\z/ (excluding 0000000).
unavailable_error A resource has been disabled or deleted.
format_error A resource identifier or object is not formatted correctly.
range_error A numeric value is out of range.

Example Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json
{
  "errors": [
    {
      "code": "presence_error",
      "attribute": "email",
      "message": "Email is required"
    },
    {
      "code": "length_error",
      "attribute": "name",
      "message": "Name must be between 2 and 20 characters"
    }
  ]
}

Transition Errors

State transition endpoints will respond with a 403 Forbidden and an errors object if the transition is not allowed:

Example Response

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.api+json
{
  "errors": [
    {
      "code": "no_postal_address_error"
    }
  ]
}

Rate Limiting

You can make up to 50 requests per hour for batch endpoints and 3600 requests per hour for other API endpoints. All API requests subject to rate limiting contain information regarding your current rate limit status in the response headers:

$ curl -u YOUR_API_TOKEN: -i https://api.getdrip.com/v2/accounts

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 3597

If you exceed your rate limit, the API will returns a 429 status:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
  "message": "API rate limit exceeded. Please try again in an hour.",
  "documentation": "https://www.getdrip.com/docs/rest-api#rate-limting"
}

To minimize your API requests, check out our batch endpoints for subscribers and events.

Pagination

Some endpoints that return collections are paginated. For these endpoints, the meta object will tell you the current page, count, total number of pages, and total count of the collection:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "meta": {
    "page": 1,
    "count": 100,
    "total_pages": 3,
    "total_count": 300
  },
  ...
}

By default, the API will return the first page of results. Each page contains a maximum of 100 items, unless otherwise noted below. To fetch a particular page, use the page query parameter:

$ curl -u YOUR_API_TOKEN: -i https://api.getdrip.com/v2/accounts?page=2

{
  "meta": {
    "page": 2,
    "count": 5,
    "total_pages": 2,
    "total_count": 105
  },
  ...
}

Page numbers start at 1. If a page number less than 1 is requested, the first page of results will be returned.

Subscribers

Subscribers are represented as follows:

{
  "id": "z1togz2hcjrkpp5treip",
  "status": "active",
  "email": "john@acme.com",
  "time_zone": "America/Los_Angeles",
  "utc_offset": -440,
  "visitor_uuid": "sa8f7sdf78sdsdahf788d7asf8sd",
  "custom_fields": {
    "name": "John Doe"
  },
  "tags": ["Customer", "SEO"],
  "ip_address": "111.111.111.11",
  "user_agent": "Chrome/36.0.1985.143",
  "original_referrer": "http://www.getdrip.com",
  "landing_url": "https://www.getdrip.com/docs/rest-api",
  "prospect": true,
  "lead_score": 72,
  "lifetime_value": 10000,
  "created_at": "2013-06-21T10:31:58Z",
  "href": "https://api.getdrip.com/v2/9999999/subscribers/12345",
  "user_id" "12345",
  "base_lead_score": 30,
  "links": {
    "account": "9999999"
  }
}

All responses containing subscriber data also include the following top-level link data:

{
  "links": {
    "subscribers.account": "https://api.getdrip.com/v2/accounts/{subscribers.account}"
  }
}

Create or update a subscriber

POST /:account_id/subscribers

If you need to create or update a collection of subscribers at once, use our batch API instead.

Arguments

Key Description
email Optional. The subscriber's email address. Either email or id must be included.
id Optional. The subscriber's Drip id. Either email or id must be included.
new_email Optional. A new email address for the subscriber. If provided and a subscriber with the email above does not exist, this address will be used to create a new subscriber.
user_id Optional. A unique identifier for the user in your database, such as a primary key.
time_zone Optional. The subscriber's time zone (in Olson format). Defaults to Etc/UTC
lifetime_value Optional. The lifetime value of the subscriber (in cents).
ip_address Optional. The subscriber's ip address E.g. "111.111.111.11"
custom_fields Optional. An Object containing custom field data. E.g. { "name": "John Doe" }.
tags Optional. An Array containing one or more tags. E.g. ["Customer", "SEO"].
remove_tags Optional. An Array containing one or more tags to be removed from the subscriber. E.g. ["Customer", "SEO"].
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.
base_lead_score Optional. An Integer specifying the starting value for lead score calculation for this subscriber. Defaults to 30.

Example Request

POST /9999999/subscribers
Content-Type: application/vnd.api+json
{
  "subscribers": [{
    "email": "john@acme.com",
    "time_zone": "America/Los_Angeles",
    "custom_fields": {
      "name": "John Doe"
    }
  }]
}

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Location: https://api.getdrip.com/v2/9999999/subscribers/123
{
  "links": { ... },
  "subscribers": [{ ... }]
}

List all subscribers

GET /:account_id/subscribers

Arguments

Key Description
status Optional. Filter by one of the following statuses: active, or unsubscribed, or undeliverable. Defaults to all.
tags Optional. A comma separated list of tags. When included, returns only subscribers who have at least one of the listed tags.
per_page Optional. The number of records to be returned on each page. Defaults to 100. Maximum 1000.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "count": 5,
    "total_pages": 1,
    "total_count": 5
  },
  "subscribers": [{ ... }]
}

Fetch a subscriber

GET /:account_id/subscribers/:id_or_email

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "subscribers": [{ ... }]
}

Remove from one or all campaigns

POST /:account_id/subscribers/:id_or_email/remove

This endpoint was previously labeled unsubscribe.

Arguments

Key Description
campaign_id Optional. The campaign from which to remove the subscriber. Defaults to all.

Example Request

POST /9999999/subscribers/8888888/remove?campaign_id=2222222

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "subscribers": [{ ... }]
}

Unsubscribe from all mailings

POST /:account_id/subscribers/:id_or_email/unsubscribe_all

Arguments

Key Description
None

Example Request

POST /9999999/subscribers/8888888/unsubscribe_all

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "subscribers": [{ ... }]
}

Delete a subscriber

DELETE /:account_id/subscribers/:id_or_email

Arguments

Key Description
None

Example Request

DELETE /9999999/subscribers/8888888/

Response

HTTP/1.1 204 No Content

Create or update a batch of subscribers

POST /:account_id/subscribers/batches

We recommend using this API endpoint when you need to create or update a collection of subscribers at once. Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in user interface.

Key Description
subscribers Required. An Array with between 1 and 1000 objects containing subscriber data.

Example Request

POST /9999999/subscribers/batches
Content-Type: application/vnd.api+json
{
  "batches": [{
    "subscribers": [
      {
        "email": "john@acme.com",
        "time_zone": "America/Los_Angeles",
        "tags": ["Customer", "SEO"],
        "custom_fields": {
          "name": "John Doe"
        }
      },
      {
        "email": "joe@acme.com",
        "time_zone": "America/Los_Angeles",
        "tags": ["Prospect"],
        "custom_fields": {
          "name": "Joe"
        }
      }
    ]
  }]
}

Response

HTTP/1.1 201 Created
Location: https://api.getdrip.com/v2/9999999/subscribers
Content-Type: application/json; charset=utf-8
{}

Unsubscribe batch of subscribers

POST /:account_id/unsubscribes/batches

Key Description
subscribers Required. An Array with between 1 and 1000 objects containing subscriber data.

Example Request

POST /9999999/subscribers/unsubscribe_batches
Content-Type: application/vnd.api+json
{
  "batches": [{
    "subscribers": [
      {
        "email": "john@acme.com",
      },
      {
        "email": "joe@acme.com",
      }
    ]
  }]
}

Response

HTTP/1.1 204 No Content

Campaigns

Campaigns are represented as follows:

{
  "id": "123456",
  "status": "active",
  "name": "SEO Email Course",
  "from_name": "John Doe",
  "from_email": "john@example.com",
  "postal_address": "123 Anywhere St\nFresno, CA 99999",
  "minutes_from_midnight": 440,
  "localize_sending_time": true,
  "days_of_the_week_mask": "0111110",
  "start_immediately": true,
  "double_optin": true,
  "send_to_confirmation_page": false,
  "use_custom_confirmation_page": false,
  "confirmation_url": null,
  "notify_subscribe_email": "derrick@getdrip.com",
  "notify_unsubscribe_email": "derrick@getdrip.com",
  "bcc": null,
  "email_count": 10,
  "active_subscriber_count": 320,
  "unsubscribed_subscriber_count": 5,
  "email_open_rate": 0.15531,
  "email_click_rate": 0.68232,
  "created_at": "2013-06-21T10:31:58Z",
  "updated_at": "2013-06-21T10:31:58Z",
  "href": "https://api.getdrip.com/v2/9999999/campaigns/123456",
  "links": {
    "account": "9999999",
    "forms": ["888"]
  }
}

All responses containing campaign data also include the following top-level link data:

{
  "links": {
    "campaigns.account": "https://api.getdrip.com/v2/accounts/{campaigns.account}",
    "campaigns.form": "https://api.getdrip.com/v2/{campaigns.account}/forms/{campaigns.forms}",
    "campaigns.subscribers": "https://api.getdrip.com/v2/{campaigns.account}/campaigns/{campaigns.id}/subscribers"
  }
}

List all campaigns

GET /:account_id/campaigns

Arguments

Key Description
status Optional. Filter by one of the following statuses: draft, active, or paused. Defaults to all.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "sort": "created_at",
    "direction": "asc",
    "count": 5,
    "total_pages": 1,
    "total_count": 5,
    "status": "all"
  },
  "campaigns": [ ... ]
}

Fetch a campaign

GET /:account_id/campaigns/:campaign_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "campaigns": [{ ... }],
  "linked": {
    "forms": [{ ... }]
  }
}

Activate a campaign

POST /:account_id/campaigns/:campaign_id/activate

Arguments

Key Description
None

Response

HTTP/1.1 204 No Content

If the campaign cannot be activated, returns a 422 Unprocessable Entity response.

Pause a campaign

POST /:account_id/campaigns/:campaign_id/pause

Arguments

Key Description
None

Response

HTTP/1.1 204 No Content

If the campaign cannot be paused, returns a 422 Unprocessable Entity response.

List everyone subscribed to a campaign

GET /:account_id/campaigns/:campaign_id/subscribers

Arguments

Key Description
status Optional. The status to filter by: active, unsubscribed, or removed. Defaults to active.
page Optional. The page number. Defaults to 1.
sort Optional. The attribute by which to sort the results: id or created_at. Defaults to created_at.
direction Optional. The direction to sort the results: asc or desc. Defaults to desc.
per_page Optional. The number of records to be returned on each page. Defaults to 100. Maximum 1000.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "sort": "created_at",
    "direction": "desc",
    "count": 20,
    "total_pages": 1,
    "total_count": 20
  },
  "subscribers": [ ... ]
}

Subscribe someone to a campaign

POST /:account_id/campaigns/:campaign_id/subscribers

Arguments

Key Description
email Required. The subscriber's email address.
user_id Optional. A unique identifier for the user in your database, such as a primary key.
time_zone Optional. The subscriber's time zone (in Olson format). Defaults to Etc/UTC
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.
starting_email_index Optional. The index (zero-based) of the email to send first. Defaults to 0.
custom_fields Optional. An Object containing custom field data. E.g. { "name": "John Doe" }.
tags Optional. An Array containing one or more tags. E.g. ["Customer", "SEO"].
reactivate_if_removed Optional. If true, re-subscribe the subscriber to the campaign if there is a removed subscriber in Drip with the same email address; otherwise, respond with 422 Unprocessable Entity. Defaults to true.
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.
base_lead_score Optional. An Integer specifying the starting value for lead score calculation for this subscriber. Defaults to 30.

Example Request

POST /9999999/campaigns/99999/subscribers
Content-Type: application/vnd.api+json
{
  "subscribers": [{
    "email": "john@acme.com",
    "utc_offset": 660,
    "double_optin": true,
    "starting_email_index": 0,
    "reactivate_if_removed": true,
    "custom_fields": {
      "name": "John Doe"
    }
  }]
}

Response

HTTP/1.1 201 Created
Location: https://api.getdrip.com/v2/9999999/subscribers/123
{
  "links": { ... },
  "subscribers": [{ ... }]
}

Campaign Subscriptions

Campaign subscriptions are represented as follows:

{
  "id": "123456",
  "campaign_id": "999999",
  "status": "active",
  "is_complete": false,
  "lap": 1,
  "last_sent_email_index": 0,
  "last_sent_email_at": "2016-03-25T11:00:00Z",
  "links": {
    "account": "9999999",
    "subscriber": "z1togz2hcjrkpp5treip"
  }
}

All responses containing campaign subscription data also include the following top-level link data:

{
  "links": {
    "campaign_subscriptions.account": "https://api.getdrip.com/v2/accounts/{campaign_subscriptions.account}",
    "campaign_subscriptions.subscriber": "https://api.getdrip.com/v2/subscribers/{campaign_subscriptions.subscriber}"
  }
}

List all of a subscriber's campaign subscriptions

GET /:account_id/subscribers/:subscriber_id/campaign_subscriptions

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "count": 5,
    "total_pages": 1,
    "total_count": 5
  },
  "campaign_subscriptions": [ ... ]
}

Events

Record an event

POST /:account_id/events

If you need to create or update a collection of events at once, user our batch API instead.

Arguments

Key Description
email Optional. The subscriber's email address. Either email or id must be included.
id Optional. The subscriber's Drip id. Either email or id must be included.
action Required. The name of the action taken. E.g. "Logged in"
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.
properties Optional. A Object containing custom event properties. If this event is a conversion, include the value (in cents) in the in the properties with a value key.
occurred_at Optional. The String time at which the event occurred in ISO-8601 format. Defaults to the current time.

Example Request

POST /9999999/events
Content-Type: application/vnd.api+json
{
  "events": [{
    "email": "john@acme.com",
    "action": "Logged in",
    "properties": {
      "affiliate_code": "XYZ"
    },
    "occurred_at": "2014-03-22T03:00:00Z"
  }]
}

Response

HTTP/1.1 204 No Content

Record a batch of events

POST /:account_id/events/batches

We recommend using this API endpoint when you need to record a collection of events at once. Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in user interface.

Key Description
events Required. An Array with between 1 and 1000 objects containing event data.

Example Request

POST /9999999/events/batches
Content-Type: application/vnd.api+json
{
  "batches": [{
    "events": [
      {
        "email": "john@acme.com",
        "action": "Opened a door"
      },
      {
        "email": "joe@acme.com",
        "action": "Closed a door"
      }
    ]
  }]
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{}

List all custom events actions used in an account

GET /:account_id/event_actions

Arguments

Key Description
page Optional. The page number. Defaults to 1.
per_page Optional. The number of records to be returned on each page. Defaults to 100. Maximum 1000.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "meta": {
    "count": 2,
    "page": 1,
    "total_count": 2,
    "total_pages": 1
  },
  "event_actions": [
    "Ate a sandwich",
    "Started a trial"
  ]
}

Tags

List all tags used in an account

GET /:account_id/tags

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json; charset=utf-8
{
  "tags": [
    "Customer",
    "SEO"
  ]
}

Tag a subscriber

POST /:account_id/tags

Arguments

Key Description
email The subscriber's email address.
tag The String tag to apply. E.g. "Customer"

Example Request

POST /9999999/tags
Content-Type: application/vnd.api+json
{
  "tags": [{
    "email": "john@acme.com",
    "tag": "Customer"
  }]
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{}

Remove a subscriber tag

DELETE /:account_id/subscribers/:email/tags/:tag

Example Request

DELETE /9999999/subscribers/john@example.com/tags/Customer
Content-Type: application/vnd.api+json

Response

HTTP/1.1 204 No Content

Custom Fields

Drip custom fields allow you to store subscriber data organized by an identifier. Retrieve them via the the Subscriber list or fetch endpoints. Set them using the Create or Update Subscriber endpoint. Both the identifier and contents are represented as JSON strings.

List all custom field identifiers used in an account

GET /:account_id/custom_field_identifiers

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "custom_field_identifiers": [ "first_name", "last_name", ... ]
}

Workflows

Workflows are represented as follows:

{
  "id": "123456",
  "href": "https://api.getdrip.com/v2/9999999/workflows/123456",
  "name": "Main Funnel",
  "status": "active",
  "created_at": "2016-07-01T10:00:00Z",
  "links": {
    "account": "9999999"
  }
}

All responses containing workflow data also include the following top-level link data:

{
  "links": {
    "workflows.account": "https://api.getdrip.com/v2/accounts/{workflows.account}"
  }
}

List all workflows

GET /:account_id/workflows

Arguments

Key Description
status Optional. Filter by one of the following statuses: draft, active, or paused. Defaults to all.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "sort": "sort_order",
    "direction": "desc",
    "count": 5,
    "total_pages": 1,
    "total_count": 5,
    "status": "all"
  },
  "workflows": [ ... ]
}

Fetch a workflow

GET /:account_id/workflows/:workflow_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "workflows": [{ ... }],
}

Activate a workflow

POST /:account_id/workflows/:workflow_id/activate

Arguments

Key Description
None

Response

HTTP/1.1 204 No Content

If the workflow cannot be activated, returns a 422 Unprocessable Entity response.

Pause a workflow

POST /:account_id/workflows/:workflow_id/pause

Arguments

Key Description
None

Response

HTTP/1.1 204 No Content

If the workflow cannot be paused, returns a 422 Unprocessable Entity response.

Start someone on a workflow

POST /:account_id/workflows/:workflow_id/subscribers

Arguments

Key Description
email Optional. The subscriber's email address. Either email or id must be included.
id Optional. The subscriber's Drip id. Either email or id must be included.
user_id Optional. A unique identifier for the user in your database, such as a primary key.
time_zone Optional. The subscriber's time zone (in Olson format). Defaults to Etc/UTC
custom_fields Optional. An Object containing custom field data. E.g. { "name": "John Doe" }.
tags Optional. An Array containing one or more tags. E.g. ["Customer", "SEO"].
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.

Example Request

POST /9999999/workflow/99999/subscribers
Content-Type: application/vnd.api+json
{
  "subscribers": [{
    "email": "john@acme.com",
    "time_zone": "America/Los_Angeles",
    "custom_fields": {
      "name": "John Doe"
    }
  }]
}

Response

HTTP/1.1 201 Created
Location: https://api.getdrip.com/v2/9999999/subscribers/123
{
  "links": { ... },
  "subscribers": [{ ... }]
}

Note: If the workflow is not active, the subscriber will not be added to the workflow.

Remove someone from a workflow

DELETE /:account_id/workflows/:workflow_id/subscribers/:id_or_email

Arguments

Key Description
None

Example Request

DELETE /9999999/workflows/8888888/subscribers/66666666

Response

HTTP/1.1 204 No Content

Note: If the subscriber is not already on the workflow, nothing will happen.

Workflow Triggers

List all workflow triggers

GET /:account_id/workflows/:workflow_id/triggers

Arguments

Key Description
None

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "triggers": [
    {
      "id": "f7gysdf7gyd7",
      "type": "trigger",
      "trigger_type": "submitted_landing_page",
      "provider": "leadpages",
      "properties": {
        "landing_page": "My Landing Page"
      },
      "actions_required": [
        {
          "code": "configure_provider",
          "message": "Configure your LeadPages connection"
        }
      ]
    }
  ]
}

Create a workflow trigger

POST /:account_id/workflows/:workflow_id/triggers

Arguments

Key Description
provider Required. A String indicating a provider.
trigger_type Required. A String indicating the automation trigger type.
properties Optional. An Object containing properties for the given trigger.

Example Request

{
  "triggers": [
    {
      "provider": "leadpages",
      "trigger_type": "submitted_landing_page",
      "properties": {
        "landing_page": "My Landing Page"
      }
    }
  ]
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "triggers": [
    {
      "id": "f7gysdf7gyd7",
      "type": "trigger",
      "provider": "leadpages",
      "trigger_type": "submitted_landing_page",
      "properties": {
        "landing_page": "My Landing Page"
      },
      "actions_required": [
        {
          "code": "configure_provider",
          "message": "Configure your LeadPages connection"
        }
      ]
    }
  ]
}

Update a workflow trigger

PUT /:account_id/workflows/:workflow_id/triggers/:trigger_id

Arguments

Key Description
provider Required. A String indicating a provider.
trigger_type Required. A String indicating the automation trigger type.
properties Optional. An Object containing properties for the given trigger.

Example Request

{
  "triggers": [
    {
      "provider": "leadpages",
      "trigger_type": "submitted_landing_page",
      "properties": {
        "landing_page": "My Landing Page"
      }
    }
  ]
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "triggers": [
    {
      "id": "f7gysdf7gyd7",
      "type": "trigger",
      "provider": "leadpages",
      "trigger_type": "submitted_landing_page",
      "properties": {
        "landing_page": "My Landing Page"
      },
      "actions_required": [
        {
          "code": "configure_provider",
          "message": "Configure your LeadPages connection"
        }
      ]
    }
  ]
}

Accounts

Accounts are represented as follows:

{
  "id": "9999999",
  "name": "Acme, Inc.",
  "url": "www.acme.com",
  "default_from_name": "John Doe",
  "default_from_email": "john@acme.com",
  "default_postal_address": "123 Anywhere St\nFresno, CA 99999",
  "primary_email": "john@acme.com",
  "enable_third_party_cookies": false,
  "phone_number": "999-999-9999",
  "created_at": "2013-06-21T10:31:58Z",
  "href": "https://api.getdrip.com/v2/accounts/9999999"
}

All responses containing account data also include the following top-level link data:

{
  "links": {
    "accounts.broadcasts": "https://api.getdrip.com/v2/{accounts.id}/broadcasts",
    "accounts.campaigns": "https://api.getdrip.com/v2/{accounts.id}/campaigns",
    "accounts.goals": "https://api.getdrip.com/v2/{accounts.id}/goals"
  }
}

List all accounts

GET /accounts

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "accounts": [ ... ]
}

Fetch an account

GET /accounts/:account_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "accounts": [{ ... }]
}

Forms

Forms are represented as follows:

{
  "id": "77777",
  "href": "https://api.getdrip.com/v2/9999999/forms/77777",
  "headline": "Long Tail SEO Course",
  "description": "Get our FREE email course",
  "button_text": "Sign Up!",
  "confirmation_heading": "Thank you for subscribing",
  "confirmation_text": "Please click the link in your email",
  "send_ga_event": true,
  "seconds_before_popup": 5,
  "days_between_popup": 5,
  "days_between_popup_after_close": 10,
  "orientation": "bottom_right_tab",
  "opacity": 0.8,
  "show_labels": false,
  "primary_color": "#333333",
  "secondary_color": "#d8ab93",
  "is_widget_enabled": true,
  "whitelist": [ "/landing", "/public" ],
  "blacklist": [],
  "is_whitelist_enabled": true,
  "is_blacklist_enabled": false,
  "hide_on_mobile": false,
  "is_embeddable": true,
  "created_at": "2013-06-21T10:31:58Z",
  "links": {
    "account": "9999999"
  }
}

All responses containing form data also include the following top-level link data:

{
  "links": {
    "forms.account": "https://api.getdrip.com/v2/accounts/{forms.account}"
  }
}

Fetch list of forms

GET /:account_id/forms/

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "forms": [ ... ]
}

Fetch a form

GET /:account_id/forms/:form_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "forms": [ ... ]
}

Conversions

Conversions are represented as follows:

{
  "id": "99999",
  "status": "active",
  "name": "Trial Signup",
  "url": "/receipt",
  "default_value": 2000,
  "counting_method": "one_per_visitor",
  "created_at": "2013-06-21T10:31:58Z",
  "href": "https://api.getdrip.com/v2/9999999/goals/99999",
  "links": {
    "account": "9999999"
  }
}

All responses containing conversion data also include the following top-level link data:

{
  "links": {
    "goals.account": "https://api.getdrip.com/v2/accounts/{goals.account}"
  }
}

See the Events API for recording conversion events.

List all conversions

GET /:account_id/goals

Arguments

Key Description
status Optional. The status to filter by: active, disabled, or all. Defaults to all.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "goals": [ ... ]
}

Fetch a conversion

GET /:account_id/goals/:conversion_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "goals": [{ ... }]
}

Webhooks

Webhooks are represented as follows:

{
  "id": "77777",
  "href": "https://api.getdrip.com/v2/9999999/webhooks/77777",
  "post_url": "http://www.mysite.com/my-webhook-endpoint",
  "version": "1",
  "include_received_email": false,
  "events": [
    "subscriber.created",
    "subscriber.subscribed_to_campaign"
  ],
  "created_at": "2013-06-21T10:31:58Z",
  "links": {
    "account": "9999999",
  }
}

All responses containing webhook data also include the following top-level link data:

{
  "links": {
    "webhooks.account": "https://api.getdrip.com/v2/accounts/{webhooks.account}"
  }
}

List all webhooks

GET /:account_id/webhooks

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "webhooks": [ ... ]
}

Fetch a webhook

GET /:account_id/webhooks/:webhook_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "webhooks": [{ ... }]
}

Create a new webhook

POST /:account_id/webhooks

Arguments

Key Description
post_url The url that the webhook will post to.
include_received_email Optional. A Boolean specifying whether we should send a notification whenever a subscriber receives an email. Defaults to false.
events Optional. An Array specifiying which events we should send notifications for. Eligible events can be found in the webhooks documentation. By default, we will send notifications for all events except subscrber.received_email.

Example Request

POST /9999999/webhooks
Content-Type: application/vnd.api+json
{
  "webhooks": [{
    "post_url": "http://www.mysite.com/my-webhook-endpoint",
    "events": [
      "subscriber.created",
      "subscriber.subscribed_to_campaign"
    ]
  }]
}

Response

HTTP/1.1 201 Created
Location: https://api.getdrip.com/v2/9999999/webhooks/77777
{
  "links": { ... },
  "webhooks": [{
    "id": "77777",
    "href": "https://api.getdrip.com/v2/9999999/webhooks/77777",
    "post_url": "http://www.example.com/api/v2/form",
    "version": "1",
    "include_received_email": false,
    "events": [
      "subscriber.created",
      "subscriber.subscribed_to_campaign"
    ],
    "created_at": "2013-06-21T10:31:58Z",
    "links": {
      "account": "9999999",
    }
  }]
}

Destroy a webhook

DELETE /:account_id/webhooks/:webhook_id

Arguments

Key Description
None

Response

HTTP/1.1 204 No Content

Broadcasts

Broadcasts are represented as follows:

{
  "id": "123456",
  "status": "sent",
  "name": "4 Marketing Automation Trends for 2015",
  "from_name": "John Doe",
  "from_email": "john@example.com",
  "postal_address": "123 Anywhere St\nFresno, CA 99999",
  "localize_sending_time": true,
  "send_at": "2015-07-01T10:00:00Z",
  "bcc": null,
  "created_at": "2015-06-21T10:31:58Z",
  "href": "https://api.getdrip.com/v2/9999999/broadcast/123456",
  "subject": "4 Marketing Automation Trends for 2015",
  "html_body": "HTML body",
  "text_body": "Text body",
  "links": {
    "account": "9999999"
  }
}

All responses containing broadcast data also include the following top-level link data:

{
  "links": {
    "broadcasts.account": "https://api.getdrip.com/v2/accounts/{broadcasts.account}",
  }
}

List all broadcasts

GET /:account_id/broadcasts

Arguments

Key Description
status Optional. Filter by one of the following statuses: draft, scheduled, or sent. Defaults to all.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "sort": "created_at",
    "direction": "asc",
    "count": 5,
    "total_pages": 1,
    "total_count": 5,
    "status": "all"
  },
  "broadcasts": [ ... ]
}

Fetch a broadcast

GET /:account_id/broadcasts/:broadcast_id

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "broadcast": [{ ... }]
}

Users

Users are represented as follows:

{
  "email": "john@acme.com",
  "name": "John Doe",
  "time_zone": "America/Los_Angeles"
}

Fetch the authenticated user

GET /user

Arguments

Key Description
None

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "users":[{ ... }]
}

Purchases (Beta)

Purchases are represented as follows:

{
  "id": "9999999",
  "provider": "gumroad",
  "order_id": "123456",
  "amount": 4900,
  "permalink": "http://myorders.com/orders/123456",
  "properties": {
    "address": "123 Anywhere St"
  },
  "occurred_at": "2013-06-21T10:31:58Z",
  "items": [
    {
      "id": "8888888",
      "product_id": "765432",
      "sku": "4444",
      "amount": 4900,
      "name": "Canoe",
      "quantity": 1,
      "properties": {
        "color": "black"
      }
    }
  ],
  "links": {
    "account": "9999999",
    "subscriber": "98asdh9f8asd88d"
  }
}

All responses containing purchase data also include the following top-level link data:

{
  "links": {
    "purchases.account": "https://api.getdrip.com/v2/accounts/{purchases.account}"
    "purchases.subscriber": "https://api.getdrip.com/v2/subscribers/{purchases.subscriber}"
  }
}

Create a purchase

POST /:account_id/subscribers/:id_or_email/purchases

When a purchase is created, the subscriber's lifetime_value attribute will be automatically incremented by the total amount of the purchase.

Arguments

Key Description
amount Required. The total amount of the purchase in cents (e.g. if the order was $49.99, set the amount to 4999).
provider Optional. The identifier for the provider from which the purchase data was received (e.g. gumroad).
order_id Optional. A unique identifier for the order (generally the primary key generated by the order management system).
permalink Optional. A URL for the human-readable interface to view the order details.
properties Optional. An Object containing properties about the order. E.g. { "address": "123 Anywhere St" }
items Optional. An Array of objects containing information about specific order items.

Key Description
name Required. The product name
amount Required. The line total (in cents).
quantity Optional. The quantity of the item purchased (if omitted, defaults to 1).
product_id Optional. A unique identifier for the specific product.
sku Optional. The product SKU number.
properties Optional. An Object containing properties about the line item.
occurred_at Optional. The String time at which the event occurred in ISO-8601 format. Defaults to the current time.

Example Request

POST /9999999/subscribers/john@acme.com/purchases
Content-Type: application/vnd.api+json
{
  "purchases": [{
    "provider": "gumroad",
    "order_id": "123456",
    "amount": 4900,
    "permalink": "http://myorders.com/orders/123456",
    "properties": {
      "address": "123 Anywhere St"
    },
    "occurred_at": "2013-06-21T10:31:58Z",
    "items": [
      {
        "id": "8888888",
        "product_id": "765432",
        "sku": "4444",
        "amount": 4900,
        "name": "Canoe",
        "quantity": 1,
        "properties": {
          "color": "black"
        }
      }
    ]
  }]
}

Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.getdrip.com/v2/9999999/subscribers/a8s9fy9as8dyf/purchases/7777777
{}

List purchases for a subscriber

GET /:account_id/subscribers/:id_or_email/purchases

Arguments

Key Description
None.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "meta": {
    "page": 1,
    "count": 5,
    "total_pages": 1,
    "total_count": 5
  },
  "purchases": [{ ... }]
}

Fetch a purchase

GET /:account_id/subscribers/:id_or_email/purchases/:purchase_id

Arguments

Key Description
None.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "links": { ... },
  "purchases": [{ ... }]
}