ActiveCampaign

The ActiveCampaign Developer Hub

Welcome to the ActiveCampaign developer hub. You'll find comprehensive guides and documentation to help you start working with ActiveCampaign as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
 

Version 3 of the ActiveCampaign API is structured around REST, HTTP, and JSON. API endpoint URLs are organized around resources, such as contacts or deals. It uses HTTP methods for indicating the action to take on a resource, and HTTP status codes for expressing error states. Resources are represented in JSON following a conventional schema.

 

The API is accessed using a base URL that is specific to your account. Your API URL can be found in your account on the My Settings page under the "Developer" tab. In addition, URL paths should begin with /api/3 to specify version 3 of the API. Generally, the URL will be in the form https://<your-account>.api-us1.com/api/3/<resource>. All API calls should be made over HTTPS.

Suggest Edits

Authentication

 

All requests to the API are authenticated by providing your API key. There are two ways to provide your API key, either as an HTTP header named Api-Token, or query parameter named api_key.

curl -H "Api-Token: YOUR_TOKEN" https://account.api-us1.com/api/3/
curl https://account.api-us1.com/api/3/?api_key=YOUR_TOKEN

Your API key can be found in your account on the My Settings page under the "Developer" tab.

Remember to keep your API key secret. Do not share it and take care not to expose it publicly in client-side code.

Suggest Edits

HTTP Methods

 

The v3 API uses standard HTTP methods for indicating the action to take on a resource.

Method
Action

GET

Retrieve a resource.

POST

Create a new resource.

PUT

Update a resource (including partial updates).

DELETE

Remove a resource.

All request and response data is sent and received as JSON adhering to the same basic document structure. The JSON document always includes a top-level member named after the resource type. All property names are camelCased. Here's an example of a single item resource:

{
    "contact": {
        "email": "jsmith@example.com",
        "firstName": "John",
        "lastName": "Smith"
    }
}

A document containing a collection of items will include a top-level member named after the resource in a pluralized form as an array. Collection responses will also include a top-level meta object that contains any related meta-data for the processed request. The most common use for this is to provide a total count of items.

{
    "contacts": [
        {
            "email": "jsmith@example.com",
            "firstName": "John",
            "lastName": "Smith"
        },
        {
            "email": "alice@example.com",
            "firstName": "Alice",
            "lastName": "Jones"
        }
    ],
    "meta": {
        "total": "2"
    }
}

The API uses HTTP status codes to indicate an error has occurred while processing a request. There are three main error status codes used by the API:

Code
Description

403

The request could not be authenticated or the authenticated user is not authorized to access the requested resource.

404

The requested resource does not exist.

422

The request could not be processed, usually due to a missing or invalid parameter.

In the case of 422 errors the response will also include an error object with an explanation of fields that are missing or invalid. Here is an example:

HTTP/1.1 422 Unprocessable Entity

{
  "errors": [
    {
      "title": "The connection service was not provided.",
      "source": {
        "pointer": "/data/attributes/service"
      }
    },
    {
      "title": "The connection externalid was not provided.",
      "source": {
        "pointer": "/data/attributes/externalid"
      }
    }
  ]
}
Suggest Edits

Pagination

 

API endpoints that return a collection of items are always paginated. Use the limit and offset parameters to control pagination.

Parameter
Description

limit

The number of results to display in each page (default = 20; max = 100).

offset

The starting point for the result set of a page. This is a zero-based index. For example, if there are 39 total records and the limit is the default of 20, use offset=20 to get the second page of results.

The total number of results in a collection can be found in the meta.total property of the response.

Suggest Edits

Create a user

Create a new user

 
posthttps://:account.api-us1.com/api/3/users
curl --request POST \
  --url https:///:account.api-us1.com/api/3/users
var request = require("request");

var options = { method: 'POST',
  url: 'https:///:account.api-us1.com/api/3/users' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https:///:account.api-us1.com/api/3/users");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "user": {
    "username": "nartem",
    "email": "nartem@activecampaign.com",
    "firstName": "Nahor",
    "lastName": "Artem",
    "links": {
      "lists": "http://localhost/hosted/api/3/users/2/lists",
      "userGroup": "http://localhost/hosted/api/3/users/2/userGroup",
      "dealGroupTotals": "http://localhost/hosted/api/3/users/2/dealGroupTotals",
      "dealGroupUsers": "http://localhost/hosted/api/3/users/2/dealGroupUsers",
      "configs": "http://localhost/hosted/api/3/users/2/configs"
    },
    "id": "2"
  }
}

Body Params

user
object
user.username
string

Username

user.email
string

Email address

user.firstName
string

First name

user.lastName
string

Last name

user.group
int32

Group ID

user.password
string

Plain text password

 
Suggest Edits

Retrieve a user

Retrieve an existing user

 
gethttps://:account.api-us1.com/api/3/users/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/users/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/users/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/users/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "user": {
    "username": "admin",
    "firstName": "Steven",
    "lastName": "Evans",
    "email": "pevans@activecampaign.com",
    "phone": "",
    "signature": null,
    "links": {
      "lists": "http://localhost/hosted/api/3/users/1/lists",
      "userGroup": "http://localhost/hosted/api/3/users/1/userGroup",
      "dealGroupTotals": "http://localhost/hosted/api/3/users/1/dealGroupTotals",
      "dealGroupUsers": "http://localhost/hosted/api/3/users/1/dealGroupUsers",
      "configs": "http://localhost/hosted/api/3/users/1/configs"
    },
    "id": "1"
  }
}

Path Params

id
int32
required

ID of the user you want to view

 
Suggest Edits

Retrieve a user by email

Retrieve an existing user by looking up their email address

 
gethttps://:account.api-us1.com/api/3/users/email/:email
curl --request GET \
  --url https:///:account.api-us1.com/api/3/users/email/:email
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/users/email/:email' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users/email/:email")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/users/email/:email");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users/email/:email"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "user": {
    "username": "somebody",
    "firstName": "Peter",
    "lastName": "Evans",
    "email": "somebody@activecampaign.com",
    "phone": "",
    "signature": null,
    "links": {
      "lists": "http://localhost/hosted/api/3/users/1/lists",
      "userGroup": "http://localhost/hosted/api/3/users/1/userGroup",
      "dealGroupTotals": "http://localhost/hosted/api/3/users/1/dealGroupTotals",
      "dealGroupUsers": "http://localhost/hosted/api/3/users/1/dealGroupUsers",
      "configs": "http://localhost/hosted/api/3/users/1/configs"
    },
    "id": "1"
  }
}

Path Params

:email
string
required

Email address of the user you want to view

 
Suggest Edits

Retrieve a user by username

Retrieve an existing user by looking up their username

 
gethttps://:account.api-us1.com/api/3/users/username/:username
curl --request GET \
  --url https:///:account.api-us1.com/api/3/users/username/:username
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/users/username/:username' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users/username/:username")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/users/username/:username");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users/username/:username"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "user": {
    "username": "admin",
    "firstName": "Gretchen",
    "lastName": "Smithfield",
    "email": "gsmithfield@activecampaign.com",
    "phone": "",
    "signature": null,
    "links": {
      "lists": "http://localhost/hosted/api/3/users/1/lists",
      "userGroup": "http://localhost/hosted/api/3/users/1/userGroup",
      "dealGroupTotals": "http://localhost/hosted/api/3/users/1/dealGroupTotals",
      "dealGroupUsers": "http://localhost/hosted/api/3/users/1/dealGroupUsers",
      "configs": "http://localhost/hosted/api/3/users/1/configs"
    },
    "id": "1"
  }
}

Path Params

:username
string
required

Username of the user you want to view

 
Suggest Edits

Retrieve logged-in user

Retrieve the logged-in user

 
gethttps://:account.api-us1.com/api/3/users/me
curl --request GET \
  --url https:///:account.api-us1.com/api/3/users/me
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/users/me' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users/me")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/users/me");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users/me"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "user": {
    "username": "somebody",
    "firstName": "Sunil",
    "lastName": "Svend",
    "email": "somebody@activecampaign.com",
    "phone": "",
    "signature": null,
    "links": {
      "lists": "http://localhost/hosted/api/3/users/1/lists",
      "userGroup": "http://localhost/hosted/api/3/users/1/userGroup",
      "dealGroupTotals": "http://localhost/hosted/api/3/users/1/dealGroupTotals",
      "dealGroupUsers": "http://localhost/hosted/api/3/users/1/dealGroupUsers",
      "configs": "http://localhost/hosted/api/3/users/1/configs"
    },
    "id": "1"
  }
}
 
Suggest Edits

Update a user

Update an existing user

 
puthttps://:account.api-us1.com/api/3/users/:id
curl --request PUT \
  --url https:///:account.api-us1.com/api/3/users/:id
var request = require("request");

var options = { method: 'PUT',
  url: 'https:///:account.api-us1.com/api/3/users/:id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users/:id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https:///:account.api-us1.com/api/3/users/:id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users/:id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "userGroups": [
    {
      "userid": "3",
      "groupid": "3",
      "links": {
        "group": "http://localhost/hosted/api/3/userGroups/3/group",
        "user": "http://localhost/hosted/api/3/userGroups/3/user"
      },
      "id": "3",
      "group": "3",
      "user": "3"
    }
  ],
  "user": {
    "username": "user",
    "firstName": "Trisha",
    "lastName": "Ogilvey",
    "email": "togilvey@activecampaign.com",
    "phone": "",
    "signature": "",
    "userGroup": "3",
    "links": {
      "lists": "http://localhost/hosted/api/3/users/3/lists",
      "userGroup": "http://localhost/hosted/api/3/users/3/userGroup",
      "dealGroupTotals": "http://localhost/hosted/api/3/users/3/dealGroupTotals",
      "dealGroupUsers": "http://localhost/hosted/api/3/users/3/dealGroupUsers",
      "configs": "http://localhost/hosted/api/3/users/3/configs"
    },
    "id": "3"
  }
}

Path Params

:id
int32
required

ID of the user

Body Params

user
object
user.username
string

Username. Username cannot be changed!

user.password
string

Password. Example: 'newpassword'

user.email
string

Email address of the user. Example: 'test@example.com'

user.firstName
string

First name of the user. Example: 'FirstName'

user.lastName
string

Last name of the user. Example: 'LastName'

user.group
int32

Assign to Groups

 
Suggest Edits

Delete a user

Delete an existing user

 
deletehttps://:account.api-us1.com/api/3/users/:id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/users/:id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/users/:id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users/:id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/users/:id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users/:id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

:id
int32
required

ID of the user you wish to delete

 
Suggest Edits

List all users

List all existing users

 
gethttps://:account.api-us1.com/api/3/users
curl --request GET \
  --url https:///:account.api-us1.com/api/3/users
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/users' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/users");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/users"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "users": [
    {
      "username": "admin",
      "firstName": "Ahti",
      "lastName": "Gaizka",
      "email": "agaizka@activecampaign.com",
      "phone": "",
      "signature": null,
      "links": {
        "lists": "http://localhost/hosted/api/3/users/1/lists",
        "userGroup": "http://localhost/hosted/api/3/users/1/userGroup",
        "dealGroupTotals": "http://localhost/hosted/api/3/users/1/dealGroupTotals",
        "dealGroupUsers": "http://localhost/hosted/api/3/users/1/dealGroupUsers",
        "configs": "http://localhost/hosted/api/3/users/1/configs"
      },
      "id": "1"
    },
    {
      "username": "user",
      "firstName": "Tendai",
      "lastName": "Romanus",
      "email": "tromanus@activecampaign.com",
      "phone": "",
      "signature": null,
      "links": {
        "lists": "http://localhost/hosted/api/3/users/5/lists",
        "userGroup": "http://localhost/hosted/api/3/users/5/userGroup",
        "dealGroupTotals": "http://localhost/hosted/api/3/users/5/dealGroupTotals",
        "dealGroupUsers": "http://localhost/hosted/api/3/users/5/dealGroupUsers",
        "configs": "http://localhost/hosted/api/3/users/5/configs"
      },
      "id": "5"
    }
  ],
  "meta": {
    "total": "2"
  }
}
 

In order to make requests to the Deals related API endpoints, the user should belong to a user group that has the Deals permission turned on.

Deals parameters available values

For following parameters:

  • search_field

Use following values:

Parameter value
Meaning

all

All three fields: title, contact, and org

title

Deal's title

contact

Deal's primary contact's first name and last name. If search parameter has more than one word, first word is used for matching first name of contacts and rest of the words are used for matching last name of contacts.

org

Deal's primary contact's organization name

For following parameters:

  • status
  • deal.status

Use following values:

Parameter value
Meaning

0

Open

1

Won

2

Lost

For following parameters:

  • nextdate_range

Use following values:

Parameter value
Meaning

upcoming

Deals with tasks that are due within 24 hours.

scheduled

Deals with tasks that are due in more than 24 hours

overdue

Deals with tasks that are past due dates.

no-task

Deals without any task.

For following parameters:

  • tag

Use following values:

Parameter value
Meaning

greater than 0

Deals with primary contacts that have the tag with given id

-1

Deals with primary contacts that have any tag

-2

Deals with primary contacts that have no tag

Suggest Edits

Create a deal

Create a new deal

 
posthttps://:account.api-us1.com/api/3/deals
{
  "deal": {
    "contact": "51",
    "currency": "usd",
    "group": "1",
    "owner": "1",
    "percent": null,
    "stage": "1",
    "status": 0,
    "title": "AC Deal",
    "value": 45600
  }
}
A binary file was returned

You couldn't be authenticated

{
  "contacts": [
    {
      "adate": "2017-02-06 15:50:11",
      "bounced_date": "0000-00-00",
      "bounced_hard": "0",
      "bounced_soft": "0",
      "cdate": "2017-02-03T11:26:41-06:00",
      "deleted": "0",
      "edate": "0000-00-00 00:00:00",
      "email": "abc@acb.com",
      "email_domain": "",
      "email_local": "",
      "firstName": "",
      "gravatar": "1",
      "hash": "e1705a92f24edf5313ed21df44d6ff5f",
      "id": "51",
      "ip": "0",
      "lastName": "",
      "links": {
        "bounceLogs": "/api/3/contacts/51/bounceLogs",
        "contactAutomations": "/api/3/contacts/51/contactAutomations",
        "contactData": "/api/3/contacts/51/contactData",
        "contactDeals": "/api/3/contacts/51/contactDeals",
        "contactGoals": "/api/3/contacts/51/contactGoals",
        "contactLists": "/api/3/contacts/51/contactLists",
        "contactLogs": "/api/3/contacts/51/contactLogs",
        "contactTags": "/api/3/contacts/51/contactTags",
        "deals": "/api/3/contacts/51/deals",
        "fieldValues": "/api/3/contacts/51/fieldValues",
        "geoIps": "/api/3/contacts/51/geoIps",
        "notes": "/api/3/contacts/51/notes",
        "organization": "/api/3/contacts/51/organization",
        "plusAppend": "/api/3/contacts/51/plusAppend",
        "scoreValues": "/api/3/contacts/51/scoreValues",
        "trackingLogs": "/api/3/contacts/51/trackingLogs"
      },
      "organization": null,
      "orgid": "0",
      "phone": "",
      "rating_tstamp": "0000-00-00",
      "segmentio_id": "",
      "sentcnt": "0",
      "socialdata_lastcheck": "0000-00-00 00:00:00",
      "ua": "",
      "udate": "2017-02-03T11:26:41-06:00"
    }
  ],
  "deal": {
    "cdate": "2017-03-31T11:28:26-05:00",
    "contact": "51",
    "currency": "usd",
    "group": "1",
    "hash": "acd136f3",
    "id": "7",
    "isDisabled": "",
    "links": {
      "activities": "/api/3/deals/7/activities",
      "contact": "/api/3/deals/7/contact",
      "contactDeals": "/api/3/deals/7/contactDeals",
      "group": "/api/3/deals/7/group",
      "nextTask": "/api/3/deals/7/nextTask",
      "notes": "/api/3/deals/7/notes",
      "organization": "/api/3/deals/7/organization",
      "owner": "/api/3/deals/7/owner",
      "scoreValues": "/api/3/deals/7/scoreValues",
      "stage": "/api/3/deals/7/stage",
      "tasks": "/api/3/deals/7/tasks"
    },
    "mdate": "2017-03-31T11:28:26-05:00",
    "nextTask": null,
    "organization": null,
    "owner": "1",
    "percent": null,
    "stage": "1",
    "status": 1,
    "title": "AC Deal",
    "value": 45600
  },
  "dealStages": [
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": "2017-01-20T09:27:32-06:00",
      "color": "C481DF",
      "dealOrder": "next-action DESC",
      "group": "1",
      "id": "1",
      "links": {
        "group": "/api/3/dealStages/1/group"
      },
      "order": "1",
      "title": "To Contact",
      "udate": "2017-01-20T09:27:32-06:00",
      "width": "280"
    }
  ]
}

Body Params

deal
object
deal.title
string
required

Deal's title.

deal.contact
string
required

Deal's primary contact's id.

deal.value
int32
required

Deal's value in cents. (i.e. $456.78 => 45678). Must be greater than or equal to zero.

deal.currency
string
required

Deal's currency in 3-digit ISO format, lowercased.

deal.group
string
required

Deal's pipeline id. Required if deal.stage is not provided. If deal.group is not provided, the stage's pipeline will be assigned to the deal automatically.

deal.stage
string
required

Deal's stage id. Required if deal.group is not provided. If deal.stage is not provided, the deal will be assigned with the first stage in the pipeline provided in deal.group.

deal.owner
string
required

Deal's owner id. Required if pipeline's auto-assign option is disabled.

deal.percent
int32

Deal's percentage.

deal.status
int32

Deal's status. See available values.

 

To create a deal, following permissions are required.

  • Deal permission: the user should have a permission to manage deals.
  • Pipeline-specific permission: the user should have a permission to manage the pipeline a new deal belongs to.

By default, primary contact and deal stage are also returned in the response.

Suggest Edits

Retrieve a deal

Retrieve an existing deal

 
gethttps://:account.api-us1.com/api/3/deals/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/deals/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/deals/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/deals/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/deals/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/deals/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "deal": {
    "hash": "b107ee7e",
    "owner": "1",
    "contact": "45",
    "organization": null,
    "group": "2",
    "stage": "3",
    "title": "Demo Requested",
    "percent": "0",
    "cdate": "2017-01-31T08:23:52-06:00",
    "mdate": "2017-02-28T16:11:29-06:00",
    "nextdate": "2017-03-01T12:00:00-06:00",
    "value": "34500",
    "currency": "usd",
    "status": "0",
    "activitycount": "12",
    "nextdealid": "1",
    "edate": "0000-00-00 00:00:00",
    "nexttaskid": "10",
    "links": {
      "activities": "/api/3/deals/2/activities",
      "contact": "/api/3/deals/2/contact",
      "contactDeals": "/api/3/deals/2/contactDeals",
      "group": "/api/3/deals/2/group",
      "nextTask": "/api/3/deals/2/nextTask",
      "notes": "/api/3/deals/2/notes",
      "organization": "/api/3/deals/2/organization",
      "owner": "/api/3/deals/2/owner",
      "scoreValues": "/api/3/deals/2/scoreValues",
      "stage": "/api/3/deals/2/stage",
      "tasks": "/api/3/deals/2/tasks"
    },
    "id": "2",
    "nextTask": "10"
  }
}
{
  "deal": {
    "id": "2",
    "isDisabled": 1,
    "title": "Demo Requested"
  }
}

Path Params

id
int32
required

Deal's id

 

To retrieve a deal, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the deal belongs to. If the user does not have the permission to manage the pipeline, limited deal data are returned with only id, title, and isDisabled set to 1.
Suggest Edits

Update a deal

Update an existing deal

 
puthttps://:account.api-us1.com/api/3/deals/id
{
  "deal": {
    "contact": "51",
    "currency": "usd",
    "group": "1",
    "owner": "3",
    "percent": 0,
    "stage": "1",
    "status": 1,
    "title": "New Deal",
    "value": 10000
  }
}
A binary file was returned

You couldn't be authenticated

{
  "contacts": [
    {
      "adate": "2017-02-06 15:50:11",
      "bounced_date": "0000-00-00",
      "bounced_hard": "0",
      "bounced_soft": "0",
      "cdate": "2017-02-03T11:26:41-06:00",
      "deleted": "0",
      "edate": "0000-00-00 00:00:00",
      "email": "abc@acb.com",
      "email_domain": "",
      "email_local": "",
      "firstName": "",
      "gravatar": "1",
      "hash": "e1705a92f24edf5313ed21df44d6ff5f",
      "id": "51",
      "ip": "0",
      "lastName": "",
      "links": {
        "bounceLogs": "/api/3/contacts/51/bounceLogs",
        "contactAutomations": "/api/3/contacts/51/contactAutomations",
        "contactData": "/api/3/contacts/51/contactData",
        "contactDeals": "/api/3/contacts/51/contactDeals",
        "contactGoals": "/api/3/contacts/51/contactGoals",
        "contactLists": "/api/3/contacts/51/contactLists",
        "contactLogs": "/api/3/contacts/51/contactLogs",
        "contactTags": "/api/3/contacts/51/contactTags",
        "deals": "/api/3/contacts/51/deals",
        "fieldValues": "/api/3/contacts/51/fieldValues",
        "geoIps": "/api/3/contacts/51/geoIps",
        "notes": "/api/3/contacts/51/notes",
        "organization": "/api/3/contacts/51/organization",
        "plusAppend": "/api/3/contacts/51/plusAppend",
        "scoreValues": "/api/3/contacts/51/scoreValues",
        "trackingLogs": "/api/3/contacts/51/trackingLogs"
      },
      "organization": null,
      "orgid": "0",
      "phone": "",
      "rating_tstamp": "0000-00-00",
      "segmentio_id": "",
      "sentcnt": "0",
      "socialdata_lastcheck": "0000-00-00 00:00:00",
      "ua": "",
      "udate": "2017-02-03T11:26:41-06:00"
    }
  ],
  "deal": {
    "activitycount": "4",
    "cdate": "2017-03-31T11:28:26-05:00",
    "contact": "51",
    "currency": "usd",
    "edate": "0000-00-00 00:00:00",
    "group": "1",
    "hash": "acd136f3",
    "id": "7",
    "links": {
      "activities": "/api/3/deals/7/activities",
      "contact": "/api/3/deals/7/contact",
      "contactDeals": "/api/3/deals/7/contactDeals",
      "group": "/api/3/deals/7/group",
      "nextTask": "/api/3/deals/7/nextTask",
      "notes": "/api/3/deals/7/notes",
      "organization": "/api/3/deals/7/organization",
      "owner": "/api/3/deals/7/owner",
      "scoreValues": "/api/3/deals/7/scoreValues",
      "stage": "/api/3/deals/7/stage",
      "tasks": "/api/3/deals/7/tasks"
    },
    "mdate": "2017-03-31T11:52:02-05:00",
    "nextTask": null,
    "nextdealid": "6",
    "nexttaskid": "0",
    "organization": null,
    "owner": "3",
    "percent": 0,
    "stage": "1",
    "status": 1,
    "title": "New Deal",
    "value": 10000
  },
  "dealStages": [
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": "2017-01-20T09:27:32-06:00",
      "color": "C481DF",
      "dealOrder": "next-action DESC",
      "group": "1",
      "id": "1",
      "links": {
        "group": "/api/3/dealStages/1/group"
      },
      "order": "1",
      "title": "To Contact",
      "udate": "2017-01-20T09:27:32-06:00",
      "width": "280"
    }
  ]
}

Path Params

id
int32
required

Deal's id

Body Params

deal
object
deal.title
string

Deal's title.

deal.contact
string

Deal's primary contact id.

deal.value
int32

Deal's value in cents. (i.e. $456.78 => 45678). Must be greater than or equal to zero.

deal.currency
string

Deal's currency in 3-digit ISO format, lowercased.

deal.group
string

Deal's pipeline id. Deal's stage or deal.stage should belong to deal.group.

deal.stage
string

Deal's stage id. deal.stage should belong to Deal's pipeline or deal.group.

deal.owner
string

Deal's owner id.

deal.percent
int32

Deal's percentage.

deal.status
int32

Deal's status. See available values.

 

To update a deal, following permissions are required.

  • Deal permission: the user should have a permission to manage deals.
  • Pipeline-specific permission: the user should have a permission to manage the pipeline the updating deal belongs to.
  • Deal reassign permission: if assigning the deal to another user, this permission is required.

By default, the deal stage is also returned in the response. If deal.contact was provided in the request, the primary contact is also returned in the response.

Suggest Edits

Delete a deal

Delete an existing deal

 
deletehttps://:account.api-us1.com/api/3/deals/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/deals/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/deals/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/deals/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/deals/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/deals/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
int32
required

Deal's id

 

To delete a deal, the following permissions are required:

  • Deal permission: the user should have permission to manage deals.
  • Deal delete permission: the user should have permission to delete deals.
Suggest Edits

List all deals

Retrieve all existing deals

 
gethttps://:account.api-us1.com/api/3/deals
curl --request GET \
  --url https:///:account.api-us1.com/api/3/deals
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/deals' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/deals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/deals");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/deals"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "deals": [
    {
      "activitycount": "4",
      "cdate": "2017-02-06T12:25:20-06:00",
      "contact": "51",
      "currency": "usd",
      "edate": "0000-00-00 00:00:00",
      "group": "1",
      "hash": "4a5ba52d",
      "id": "3",
      "links": {
        "activities": "/api/3/deals/3/activities",
        "contact": "/api/3/deals/3/contact",
        "contactDeals": "/api/3/deals/3/contactDeals",
        "group": "/api/3/deals/3/group",
        "nextTask": "/api/3/deals/3/nextTask",
        "notes": "/api/3/deals/3/notes",
        "organization": "/api/3/deals/3/organization",
        "owner": "/api/3/deals/3/owner",
        "scoreValues": "/api/3/deals/3/scoreValues",
        "stage": "/api/3/deals/3/stage",
        "tasks": "/api/3/deals/3/tasks"
      },
      "mdate": "2017-03-01T09:15:53-06:00",
      "nextTask": "3",
      "nextdate": "2017-02-06T12:00:00-06:00",
      "nextdealid": "3",
      "nexttaskid": "3",
      "organization": null,
      "owner": "3",
      "percent": "0",
      "stage": "1",
      "status": "0",
      "title": "New Deal",
      "value": "10000"
    },
    {
      "activitycount": "62",
      "cdate": "2017-01-20T09:28:02-06:00",
      "contact": "44",
      "currency": "usd",
      "edate": "0000-00-00 00:00:00",
      "group": "2",
      "hash": "d6ca7d0b",
      "id": "1",
      "links": {
        "activities": "/api/3/deals/1/activities",
        "contact": "/api/3/deals/1/contact",
        "contactDeals": "/api/3/deals/1/contactDeals",
        "group": "/api/3/deals/1/group",
        "nextTask": "/api/3/deals/1/nextTask",
        "notes": "/api/3/deals/1/notes",
        "organization": "/api/3/deals/1/organization",
        "owner": "/api/3/deals/1/owner",
        "scoreValues": "/api/3/deals/1/scoreValues",
        "stage": "/api/3/deals/1/stage",
        "tasks": "/api/3/deals/1/tasks"
      },
      "mdate": "2017-02-06T12:21:12-06:00",
      "nextTask": "2",
      "nextdate": "2017-02-06T12:00:00-06:00",
      "nextdealid": "1",
      "nexttaskid": "2",
      "organization": null,
      "owner": "1",
      "percent": "0",
      "stage": "3",
      "status": "1",
      "title": "Test Deal",
      "value": "10000"
    },
    {
        "id": "2",
        "isDisabled": 1,
        "title": "Demo Requested"
    }
  ],
  "meta": {
    "currencies": {
      "USD": {
        "currency": "USD",
        "total": "3",
        "value": "30000"
      }
    },
    "total": 3
  }
}

Query Params

filters[search]
string

Search text to use with search_field parameter.

filters[search_field]
string

Field to search for. See available values.

filters[title]
string

Filter by deal's title

filters[stage]
int32

Filter by deal's stage

filters[group]
int32

Filter by deal's pipeline

filters[status]
int32

Filter by deal's status. See available values.

filters[owner]
int32

Filter by deal's owner

filters[nextdate_range]
string

Filter by deal's tasks due dates. See available values.

filters[tag]
string

Filter by tag names associated with deal's primary contact. See available values.

filters[tasktype]
string

Filter by deals that have tasks with given type

filters[created_before]
date

Returns deals that are created less than given date

filters[created_after]
date

Returns deals that are created greater than or equal to given date

filters[updated_before]
date

Returns deals that are updated less than given date

filters[updated_after]
date

Returns deals that are updated greater than or equal to given date

filters[organization]
int32

Filter by deal's primary contact's organization's id

filters[minimum_value]
int32

In USD with dollar portion. Returns deals whose values are greater than or equal to given value

filters[maximum_value]
int32

In USD with dollar portion. Returns deals whose values are less than or equal to given value

filters[score_greater_than]
string

In a format of <score_id>:<score_value>. Returns deals whose score value is greater than given value

filters[score_less_than]
string

In a format of <score_id>:<score_value>. Returns deals whose score value is less than given value

filters[score]
string

In a format of <score_id>:<score_value>. Returns deals whose score value is equal to given value

orders[title]
string

Order by deal's title.

orders[value]
string

Order by deal's value.

orders[cdate]
string

Order by deal's created date.

orders[contact_name]
string

Order by deal's primary contact's first name.

orders[contact_orgname]
string

Order by deal's primary contact's organization name.

orders[next-action]
string

Order by deal's next task's due date first. Then append deals with no next task. Lastly append deals with overdue tasks. If dates are the same, order by deal's id.

 

To list all deals, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the deals belong to. If the user does not have the permission to manage the pipeline, limited deal data are returned with only id, title, and isDisabled set to 1. If the response contains both permitted pipeline deals and non-permitted pipeline deals, full deal data are returned for deals belonging to permitted pipelines and limited data for deals belonging to non-permitted pipelines.
Suggest Edits

Create a deal note

Create a new note for a deal

 
posthttps://:account.api-us1.com/api/3/deals/id/notes
{
  "note": {
    "note": "Note for the deal"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "deals": [
    {
      "activitycount": "2",
      "cdate": "2017-05-25T12:01:01-05:00",
      "contact": "1",
      "currency": "usd",
      "edate": null,
      "group": "1",
      "hash": "e42436fc",
      "id": "1",
      "links": {
        "activities": "/api/3/deals/1/activities",
        "contact": "/api/3/deals/1/contact",
        "contactDeals": "/api/3/deals/1/contactDeals",
        "group": "/api/3/deals/1/group",
        "nextTask": "/api/3/deals/1/nextTask",
        "notes": "/api/3/deals/1/notes",
        "organization": "/api/3/deals/1/organization",
        "owner": "/api/3/deals/1/owner",
        "scoreValues": "/api/3/deals/1/scoreValues",
        "stage": "/api/3/deals/1/stage",
        "tasks": "/api/3/deals/1/tasks"
      },
      "mdate": "2017-05-25T12:17:23-05:00",
      "nextdate": null,
      "nextdealid": "1",
      "nexttaskid": null,
      "organization": null,
      "owner": "1",
      "percent": "0",
      "stage": "1",
      "status": "0",
      "title": "New Deal",
      "value": "10000"
    }
  ],
  "note": {
    "cdate": "2017-05-31T09:54:30-05:00",
    "id": "2",
    "links": {
      "activities": "/api/3/notes/2/activities",
      "mentions": "/api/3/notes/2/mentions",
      "notes": "/api/3/notes/2/notes",
      "owner": "/api/3/notes/2/owner",
      "user": "/api/3/notes/2/user"
    },
    "mdate": "2017-05-31T09:54:30-05:00",
    "note": "Note for the deal",
    "owner": {
      "id": "1",
      "type": "deal"
    },
    "relid": "1",
    "reltype": "Deal",
    "user": "1",
    "userid": "1"
  }
}

Path Params

id
string
required

Deal's id to assign new note to

Body Params

note
object
note.note
string
required

Deal note's content

 

To create a deal note, following permissions are required.

  • Deal permission: the user should have a permission to manage deals.
  • Pipeline-specific permission: the user should have a permission to manage the pipeline the deal belongs to.
Suggest Edits

Update a deal note

Update an existing note for a deal

 
puthttps://:account.api-us1.com/api/3/deals/id/notes/noteid
{
  "note": {
    "note": "Update with more info"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "deals": [
    {
      "activitycount": "3",
      "cdate": "2017-06-01T13:40:04-05:00",
      "contact": "1",
      "currency": "usd",
      "edate": "0000-00-00 00:00:00",
      "group": "1",
      "hash": "5604d5b5",
      "id": "1",
      "links": {
        "activities": "/api/3/deals/1/activities",
        "contact": "/api/3/deals/1/contact",
        "contactDeals": "/api/3/deals/1/contactDeals",
        "group": "/api/3/deals/1/group",
        "nextTask": "/api/3/deals/1/nextTask",
        "notes": "/api/3/deals/1/notes",
        "organization": "/api/3/deals/1/organization",
        "owner": "/api/3/deals/1/owner",
        "scoreValues": "/api/3/deals/1/scoreValues",
        "stage": "/api/3/deals/1/stage",
        "tasks": "/api/3/deals/1/tasks"
      },
      "mdate": "2017-06-01T13:41:57-05:00",
      "nextTask": "1",
      "nextdate": "2017-06-02T12:00:00-05:00",
      "nextdealid": "1",
      "nexttaskid": "1",
      "organization": null,
      "owner": "1",
      "percent": "0",
      "stage": "1",
      "status": "0",
      "title": "New deal",
      "value": "10000"
    }
  ],
  "note": {
    "cdate": "2017-06-01T13:42:13-05:00",
    "id": "2",
    "links": {
      "activities": "/api/3/notes/2/activities",
      "mentions": "/api/3/notes/2/mentions",
      "notes": "/api/3/notes/2/notes",
      "owner": "/api/3/notes/2/owner",
      "user": "/api/3/notes/2/user"
    },
    "mdate": "2017-06-01T13:42:13-05:00",
    "note": "Update with more info",
    "owner": {
      "id": "1",
      "type": "deal"
    },
    "relid": "1",
    "reltype": "Deal",
    "user": "1",
    "userid": "1"
  }
}

Path Params

id
string
required

Deal's id to assign new note to

noteid
string
required

Deal note's id to update

Body Params

note
object
note.note
string
required

Deal note's content

 

To update a deal note, following permissions are required.

  • Deal permission: the user should have a permission to manage deals.
  • Pipeline-specific permission: the user should have a permission to manage the pipeline the deal belongs to.
Suggest Edits

Pipelines

 

Deal Group is an alias of Pipeline. DealGroup is used in the request and response of pipeline API requests.

Suggest Edits

Create a pipeline

Create a new pipeline

 
posthttps://:account.api-us1.com/api/3/dealGroups
{
  "dealGroup": {
    "allgroups": 1,
    "allusers": 0,
    "autoassign": 1,
    "currency": "eur",
    "title": "Qualifications",
    "users": ["3", "4"]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealGroup": {
    "allgroups": 1,
    "allusers": 0,
    "autoassign": 1,
    "cdate": "2017-03-30T12:12:41-05:00",
    "currency": "eur",
    "dealGroupGroups": [],
    "dealGroupUsers": [
      "6",
      "7"
    ],
    "id": "5",
    "links": {
      "dealGroupGroups": "/api/3/dealGroups/5/dealGroupGroups",
      "dealGroupUsers": "/api/3/dealGroups/5/dealGroupUsers",
      "stages": "/api/3/dealGroups/5/stages"
    },
    "stages": [
      "12",
      "13",
      "14"
    ],
    "title": "Qualifications",
    "udate": "2017-03-30T12:12:41-05:00"
  },
  "dealGroupGroups": [],
  "dealGroupUsers": [
    {
      "cdate": null,
      "dealGroup": "5",
      "id": "6",
      "links": {
        "dealGroup": "/api/3/dealGroupUsers/6/dealGroup",
        "user": "/api/3/dealGroupUsers/6/user"
      },
      "user": "3"
    },
    {
      "cdate": null,
      "dealGroup": "5",
      "id": "7",
      "links": {
        "dealGroup": "/api/3/dealGroupUsers/7/dealGroup",
        "user": "/api/3/dealGroupUsers/7/user"
      },
      "user": "4"
    }
  ],
  "dealStages": [
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "18D499",
      "dealOrder": "next-action DESC",
      "group": "5",
      "id": "12",
      "links": {
        "group": "/api/3/dealStages/12/group"
      },
      "order": "1",
      "title": "To Contact",
      "udate": null,
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "32B0FC",
      "dealOrder": "next-action DESC",
      "group": "5",
      "id": "13",
      "links": {
        "group": "/api/3/dealStages/13/group"
      },
      "order": "2",
      "title": "In Contact",
      "udate": null,
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "E6CE4B",
      "dealOrder": "next-action DESC",
      "group": "5",
      "id": "14",
      "links": {
        "group": "/api/3/dealStages/14/group"
      },
      "order": "3",
      "title": "Follow Up",
      "udate": null,
      "width": "280"
    }
  ]
}

Body Params

dealGroup
object
dealGroup.title
string
required

Pipeline's title.

dealGroup.currency
string
required

Default currency to assign to new deals that belong to this deal group.

dealGroup.allgroups
int32

Whether all user groups have permission to manage this pipeline. Can be either 1 or 0. If 1, all user groups can manage this pipeline. If 0, only user groups in dealGroup.groups parameter can manage this pipeline.

dealGroup.allusers
int32

Whether new deals get auto-assigned to all users. Can be either 1 or 0. If 1, new deals are auto-assigned to all users unless auto-assign is disabled. If 0, new deals are auto-assigned to only the users in dealGroup.users parameter.

dealGroup.autoassign
int32

Deal auto-assign option. Can be one of 0, 1, and 2. If 0, auto-assign is disabled. If 1, Round Robin method is used to auto-assign new deals. If 2, deals are distributed based on deal values.

dealGroup.users
array of strings

List of user ids to auto-assign new deals to unless auto-assign option is disabled.

dealGroup.groups
array of strings

List of user group ids to allow managing this pipeline.

 

Creating a new pipeline will also create three default deal stages named "To Contact", "In Contact", and "Follow Up".
By providing user ids with dealGroup.users and enabling the auto-assign option with dealGroup.autoassign: 1, a new pipeline can control how new deals are assigned to the owners.
By providing user group ids with dealGroup.groups, a new pipeline can control which user groups are allowed to manage the pipeline.

Suggest Edits

Retrieve a pipeline

Retrieve an existing pipeline

 
gethttps://:account.api-us1.com/api/3/pipelines/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/pipelines/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/pipelines/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/pipelines/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/pipelines/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/pipelines/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealGroup": {
    "allgroups": "1",
    "allusers": "0",
    "autoassign": "1",
    "cdate": "2017-03-30T12:11:30-05:00",
    "currency": "eur",
    "id": "4",
    "links": {
      "dealGroupGroups": "/api/3/dealGroups/4/dealGroupGroups",
      "dealGroupUsers": "/api/3/dealGroups/4/dealGroupUsers",
      "stages": "/api/3/dealGroups/4/stages"
    },
    "stages": [
      "9",
      "10",
      "11"
    ],
    "title": "Qualifications",
    "udate": "2017-03-30T13:44:32-05:00"
  },
  "dealStages": [
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "18D499",
      "dealOrder": "next-action DESC",
      "group": "4",
      "id": "9",
      "links": {
        "group": "/api/3/dealStages/9/group"
      },
      "order": "1",
      "title": "To Contact",
      "udate": null,
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "32B0FC",
      "dealOrder": "next-action DESC",
      "group": "4",
      "id": "10",
      "links": {
        "group": "/api/3/dealStages/10/group"
      },
      "order": "2",
      "title": "In Contact",
      "udate": null,
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "E6CE4B",
      "dealOrder": "next-action DESC",
      "group": "4",
      "id": "11",
      "links": {
        "group": "/api/3/dealStages/11/group"
      },
      "order": "3",
      "title": "Follow Up",
      "udate": null,
      "width": "280"
    }
  ]
}

Path Params

id
string
required

Pipeline's id

 

By default, deal stages for the pipeline are also returned in the response.

Suggest Edits

Update a pipeline

Update an existing pipeline

 
puthttps://:account.api-us1.com/api/3/dealGroups/id
{
  "dealGroup": {
    "allgroups": 1,
    "allusers": 0,
    "autoassign": 1,
    "currency": "eur",
    "title": "Qualifications",
    "users": ["3"],
    "groups": []
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealGroup": {
    "allgroups": 1,
    "allusers": 0,
    "autoassign": 1,
    "cdate": "2017-03-30T12:11:30-05:00",
    "currency": "eur",
    "dealGroupGroups": [],
    "dealGroupUsers": [
      "4"
    ],
    "id": "4",
    "links": {
      "dealGroupGroups": "/api/3/dealGroups/4/dealGroupGroups",
      "dealGroupUsers": "/api/3/dealGroups/4/dealGroupUsers",
      "stages": "/api/3/dealGroups/4/stages"
    },
    "title": "Qualifications",
    "udate": "2017-03-30T13:44:32-05:00"
  },
  "dealGroupGroups": [],
  "dealGroupUsers": [
    {
      "cdate": null,
      "dealGroup": "4",
      "id": "4",
      "links": {
        "dealGroup": "/api/3/dealGroupUsers/4/dealGroup",
        "user": "/api/3/dealGroupUsers/4/user"
      },
      "user": "3"
    }
  ]
}

Path Params

id
int32
required

Pipeline's id

Body Params

dealGroup
object
dealGroup.title
string

Pipeline's title

dealGroup.currency
string

Default currency to assign to new deals that belong to this deal group.

dealGroup.allgroups
int32

Whether all user groups have permission to manage this pipeline. Can be either 1 or 0. If 1, all user groups can manage this pipeline. If 0, only user groups in dealGroup.groups parameter can manage this pipeline.

dealGroup.allusers
int32

Whether new deals get auto-assigned to all users. Can be either 1 or 0. If 1, new deals are auto-assigned to all users unless auto-assign is disabled. If 0, new deals are auto-assigned to only the users in dealGroup.users parameter.

dealGroup.autoassign
int32

Deal auto-assign option. Can be one of 0, 1, and 2. If 0, auto-assign is disabled. If 1, Round Robin method is used to auto-assign new deals. If 2, deals are distributed based on deal values.

dealGroup.users
array of strings

List of user ids to auto-assign new deals to unless auto-assign option is disabled.

dealGroup.groups
array of strings

List of user group ids to allow managing this pipeline.

 

By providing user ids with dealGroup.users and enabling the auto-assign option with dealGroup.autoassign: 1, the pipeline can control how new deals are assigned to the owners.
By providing user group ids with dealGroup.groups, the pipeline can control which user groups are allowed to manage the pipeline.

Suggest Edits

Delete a pipeline

Delete an existing pipeline

 
deletehttps://:account.api-us1.com/api/3/dealGroups/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/dealGroups/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/dealGroups/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealGroups/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/dealGroups/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealGroups/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "message": "Unable to delete dealGroup. You have deals belonging to dealGroup."
}
{
  "message": "Unable to delete dealGroup. You have stages belonging to dealGroup."
}

Path Params

id
int32
required

Pipeline's id

 

To delete a pipeline, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Pipeline-specific permission: the user should have permission to manage the pipeline.
  • Pipeline delete permission: the user should have permission to delete a pipeline.

If trying to delete a pipeline that still has existing deals and stages associated with it, the DELETE request is rejected and an error message is returned in the response.

Suggest Edits

List all pipelines

Retrieve all existing pipelines

 
gethttps://:account.api-us1.com/api/3/dealGroups
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealGroups
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealGroups' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealGroups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealGroups");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealGroups"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealGroups": [
    {
      "allgroups": "1",
      "allusers": "1",
      "autoassign": "1",
      "cdate": "2017-01-16T14:51:57-06:00",
      "currency": "usd",
      "id": "1",
      "links": {
        "dealGroupGroups": "/api/3/dealGroups/1/dealGroupGroups",
        "dealGroupUsers": "/api/3/dealGroups/1/dealGroupUsers",
        "stages": "/api/3/dealGroups/1/stages"
      },
      "stages": [
        "1",
        "2"
      ],
      "title": "Pipeline A",
      "udate": "2017-03-01T11:06:32-06:00"
    },
    {
      "allgroups": "1",
      "allusers": "1",
      "autoassign": "0",
      "cdate": "2017-03-01T14:45:16-06:00",
      "currency": "usd",
      "id": "5",
      "links": {
        "dealGroupGroups": "/api/3/dealGroups/5/dealGroupGroups",
        "dealGroupUsers": "/api/3/dealGroups/5/dealGroupUsers",
        "stages": "/api/3/dealGroups/5/stages"
      },
      "stages": [
        "12",
        "13",
        "14"
      ],
      "title": "Pipeline Yesterday",
      "udate": "2017-03-01T15:07:18-06:00"
    }
  ],
  "dealStages": [
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": "2017-01-20T09:27:32-06:00",
      "color": "C481DF",
      "dealOrder": "next-action DESC",
      "group": "1",
      "id": "1",
      "links": {
        "group": "/api/3/dealStages/1/group"
      },
      "order": "1",
      "title": "Stage 1",
      "udate": "2017-03-01T11:06:14-06:00",
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": "2017-01-20T09:27:34-06:00",
      "color": "00ECC5",
      "dealOrder": "next-action DESC",
      "group": "1",
      "id": "2",
      "links": {
        "group": "/api/3/dealStages/2/group"
      },
      "order": "2",
      "title": "Stage 2",
      "udate": "2017-03-01T11:06:20-06:00",
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "18D499",
      "dealOrder": "next-action DESC",
      "group": "5",
      "id": "12",
      "links": {
        "group": "/api/3/dealStages/12/group"
      },
      "order": "1",
      "title": "To Contact",
      "udate": null,
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "32B0FC",
      "dealOrder": "next-action DESC",
      "group": "5",
      "id": "13",
      "links": {
        "group": "/api/3/dealStages/13/group"
      },
      "order": "2",
      "title": "In Contact",
      "udate": null,
      "width": "280"
    },
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": null,
      "color": "E6CE4B",
      "dealOrder": "next-action DESC",
      "group": "5",
      "id": "14",
      "links": {
        "group": "/api/3/dealStages/14/group"
      },
      "order": "3",
      "title": "Follow Up",
      "udate": null,
      "width": "280"
    }
  ],
  "meta": {
    "total": "2"
  }
}

Query Params

filters[title]
string

Filter by pipeline's title. The filter matches any pipeline titles that contain the provided title (i.e. "Contact" matches all of "In Contact", "To Contact", and "Contact Pipeline").

filters[have_stages]
int32

Filter by whether pipelines have deal stages. Can be either 1 or 0. If 1, only pipelines with at least one stage will be returned.

orders[title]
string

Order by Pipeline's title

orders[popular]
string

Order by number of deals each pipeline has. If pipelines have same number of deals, pipelines' created dates are used to determine the order.

 

By default, deal stages for the pipelines are also returned in the response.

Suggest Edits

Deal Stages

 

Deal stage parameters available values

For following parameters:

  • dealStage.cardRegion1
  • dealStage.cardRegion2
  • dealStage.cardRegion4
  • dealStage.cardRegion5

Use following values:

Parameter value
Meaning

contact-fullname

Deal's primary contact's full name

contact-fullname-orgname

Deal's primary contact's full name and organization name

contact-orgname

Deal's primary contact's organization name

next-action

Deal's next task due date

title

Deal's title

value

Deal's value

hide

Do not show anything

For following parameters:

  • dealStage.dealOrder

Use following values:

Parameter value
Meaning

cdate

Deal's created date

contact-score

Deal's primary contact's score value

contact_name

Deal's primary contact's name

contact_orgname

Deal's primary contact's organization name

next-action

If the direction is "ASC", deals with overdue tasks will be displayed the first, deals with no tasks will be displayed the second, and deals with upcoming tasks will be displayed the last. If the direction is "DESC", this order will be reversed.

score

Deal's score

title

Deal's title

value

Deal's value

Suggest Edits

Create a deal stage

Create a new stage for a pipeline

 
posthttps://:account.api-us1.com/api/3/dealStages
{
  "dealStage": {
    "cardRegion1": "title",
    "cardRegion2": "next-action",
    "cardRegion3": "show-avatar",
    "cardRegion4": "contact-fullname-orgname",
    "cardRegion5": "value",
    "color": "32B0FC",
    "dealOrder": "next-action DESC",
    "group": "4",
    "order": 1,
    "title": "Initial Contact",
    "width": 360
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealStage": {
    "cardRegion1": "title",
    "cardRegion2": "next-action",
    "cardRegion3": "show-avatar",
    "cardRegion4": "contact-fullname-orgname",
    "cardRegion5": "value",
    "cdate": "2017-03-01T15:55:58-06:00",
    "color": "32B0FC",
    "dealOrder": "next-action DESC",
    "group": "4",
    "id": "16",
    "links": {
      "group": "/api/3/dealStages/16/group"
    },
    "order": 1,
    "title": "Initial Contact",
    "udate": "2017-03-01T15:55:58-06:00",
    "width": 280
  }
}

Query Params

reorder
int32

Whether to reorder stages within the pipeline after creating a new deal stage. Can be one of 0 and 1. If set to 1, new order values will be assigned to all stages within the same pipeline. If deal stages with the same order exists, the stage with the highest id will be assigned with the lowest order

Body Params

dealStage
object
dealStage.title
string
required

Deal stage's title

dealStage.group
string
required

Deal stage's pipeline id

dealStage.order
int32

Order of the deal stage. If more than one deal stage share the same order value, the order of those deal stages may not be always the same. If dealStage.order is not provided, the order is assigned with (the highest order of deal stages within the same pipeline) + 1

dealStage.dealOrder
string

Option and direction to be used to sort deals in the deal stage. The option and direction should be delimited by a space. Direction can be either "ASC" or "DESC". See available options

dealStage.cardRegion1
string

What to show in upper-left corner of Deal Cards. See available values

dealStage.cardRegion2
string

What to show in upper-right corner of Deal Cards. See available values

dealStage.cardRegion3
string

Whether to show the avatar in Deal Cards. Can be one of show-avatar and hide-avatar. If set to show-avatar, deal cards will show the avatars. If set to hide-avatar, deal cards will hide the avatars

dealStage.cardRegion4
string

What to show next to the avatar in Deal Cards. See available values

dealStage.cardRegion5
string

What to show in lower-right corner of Deal Cards. See available values

dealStage.color
string

Deal Stage's color. 6-character HEX color code without the hashtag. e.g. "434343" to assign the hex color value "#434343"

dealStage.width
int32

Deal stage's width in pixels, without px unit

 

To create a deal stage, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Edit Pipeline permission: the user should have permission to edit pipelines.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the stage belongs to.
Suggest Edits

Retrieve a deal stage

Retrieve an existing stage

 
gethttps://:account.api-us1.com/api/3/dealStages/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealStages/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealStages/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealStages/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealStages/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealStages/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealStage": {
    "cardRegion1": "title",
    "cardRegion2": "next-action",
    "cardRegion3": "show-avatar",
    "cardRegion4": "contact-fullname-orgname",
    "cardRegion5": "value",
    "cdate": "2017-01-20T09:27:32-06:00",
    "color": "C481DF",
    "dealOrder": "score DESC",
    "group": "1",
    "id": "1",
    "links": {
      "group": "/api/3/dealStages/1/group"
    },
    "order": "1",
    "title": "Stage 1",
    "udate": "2017-03-02T11:41:01-06:00",
    "width": "280"
  }
}

Path Params

id
int32
required

Deal stage's id

 

To retrieve a deal stage, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the stage belongs to.
Suggest Edits

Update a deal stage

Update an existing stage

 
puthttps://:account.api-us1.com/api/3/dealStages/id
{
  "dealStage": {
    "cardRegion1": "contact-orgname",
    "cardRegion2": "next-action",
    "cardRegion3": "hide-avatar",
    "cardRegion4": "contact-fullname-orgname",
    "cardRegion5": "value",
    "color": "696969",
    "dealOrder": "title ASC",
    "group": "4",
    "order": 1,
    "title": "Qualifications - Low",
    "width": 270
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealStage": {
    "cardRegion1": "contact-orgname",
    "cardRegion2": "next-action",
    "cardRegion3": "hide-avatar",
    "cardRegion4": "contact-fullname-orgname",
    "cardRegion5": "value",
    "cdate": "2017-03-01T15:55:58-06:00",
    "color": "696969",
    "dealOrder": "title ASC",
    "group": "4",
    "id": "16",
    "links": {
      "group": "/api/3/dealStages/16/group"
    },
    "order": 1,
    "title": "Qualifications - Low",
    "udate": "2017-03-01T16:03:57-06:00",
    "width": 270
  }
}

Path Params

id
int32
required

Deal stage's id

Query Params

reorder
int32

Whether to reorder stages within the pipeline after creating a new deal stage. Can be one of 0 and 1. If set to 1, new order values will be assigned to all stages within the same pipeline. If deal stages with the same order exists, the stage with the highest id will be assigned with the lowest order

Body Params

dealStage
object
dealStage.title
string

Deal stage's title

dealStage.group
string

Deal stage's pipeline id

dealStage.order
int32

Order of the deal stage. If more than one deal stage share the same order value, the order of those deal stages may not be always the same

dealStage.dealOrder
string

Option and direction to be used to sort deals in the deal stage. The option and direction should be delimited by a space. Direction can be either "ASC" or "DESC". See available options

dealStage.cardRegion1
string

What to show in upper-left corner of Deal Cards. See available values

dealStage.cardRegion2
string

What to show in upper-right corner of Deal Cards. See available values

dealStage.cardRegion3
string

Whether to show the avatar in Deal Cards. Can be one of show-avatar and hide-avatar. If set to show-avatar, deal cards will show the avatars. If set to hide-avatar, deal cards will hide the avatars

dealStage.cardRegion4
string

What to show next to the avatar in Deal Cards. See available values

dealStage.cardRegion5
string

What to show in lower-right corner of Deal Cards. See available values

dealStage.color
string

Deal Stage's color. 6-character HEX color code without the hashtag. e.g. "434343" to assign the hex color value "#434343"

dealStage.width
int32

Deal stage's width in pixels, without px unit

 

To update a deal stage, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Edit Pipeline permission: the user should have permission to edit pipelines.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the stage belongs to.
Suggest Edits

Delete a deal stage

Delete an existing stage

 
deletehttps://:account.api-us1.com/api/3/dealStages/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/dealStages/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/dealStages/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealStages/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/dealStages/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealStages/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "errors": [
    {
      "status": 409,
      "title": "Conflict",
      "detail": "The stage has existing deals. Please delete or move existing deals and try again."
    }
  ]
}

Path Params

id
int32
required

Deal stage's id

 

To delete a deal stage, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Edit Pipeline permission: the user should have permission to edit pipelines.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the stage belongs to.

If the deal stage has existing deals, the request will be rejected with a HTTP response code 409. Before this deal stage can be deleted, all deals under this deal stage must be either moved to another deal stage or deleted. To move deals under the deal stage to another deal stage, please see Move deals to another deal stage.

Suggest Edits

List all deal stages

Retrieve all existing stages

 
gethttps://:account.api-us1.com/api/3/dealStages
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealStages
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealStages' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealStages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealStages");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealStages"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealStages": [
    {
      "cardRegion1": "title",
      "cardRegion2": "next-action",
      "cardRegion3": "show-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": "2017-03-01T15:52:42-06:00",
      "color": "32B0FC",
      "dealOrder": "next-action DESC",
      "group": "4",
      "id": "15",
      "links": {
        "group": "/api/3/dealStages/15/group"
      },
      "order": "1",
      "title": "Initial Contact",
      "udate": "2017-03-01T15:52:42-06:00",
      "width": "280"
    },
    {
      "cardRegion1": "contact-orgname",
      "cardRegion2": "next-action",
      "cardRegion3": "hide-avatar",
      "cardRegion4": "contact-fullname-orgname",
      "cardRegion5": "value",
      "cdate": "2017-03-01T15:55:58-06:00",
      "color": "696969",
      "dealOrder": "title ASC",
      "group": "4",
      "id": "16",
      "links": {
        "group": "/api/3/dealStages/16/group"
      },
      "order": "1",
      "title": "Qualifications - Low",
      "udate": "2017-03-01T16:03:57-06:00",
      "width": "270"
    }
  ],
  "meta": {
    "total": "2"
  }
}

Query Params

filters[title]
string

Filter by deal stages' titles. Any stages whose titles partial-match the filter value are returned

filters[d_groupid]
string

Filter by pipeline's id

orders[title]
string

Order by deal stage's title

 

To list all deal stages, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Pipeline-specific permission: the user should have permission to manage the pipelines that the stages belong to. Stages that belong to pipelines that the user doesn't have permission to manage will not be returned in the response.
Suggest Edits

Move deals to another deal stage

Move all deals in one stage to another stage

 
puthttps://:account.api-us1.com/api/3/dealStages/id/deals
{
  "deal": {
    "stage": "3"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "deals": [
    {
      "activitycount": "1",
      "cdate": "2017-05-19T16:21:47-05:00",
      "contact": "1",
      "currency": "usd",
      "edate": "0000-00-00 00:00:00",
      "group": "1",
      "hash": "6faccb2d",
      "id": "1",
      "links": {
        "activities": "/api/3/deals/1/activities",
        "contact": "/api/3/deals/1/contact",
        "contactDeals": "/api/3/deals/1/contactDeals",
        "group": "/api/3/deals/1/group",
        "nextTask": "/api/3/deals/1/nextTask",
        "notes": "/api/3/deals/1/notes",
        "organization": "/api/3/deals/1/organization",
        "owner": "/api/3/deals/1/owner",
        "scoreValues": "/api/3/deals/1/scoreValues",
        "stage": "/api/3/deals/1/stage",
        "tasks": "/api/3/deals/1/tasks"
      },
      "mdate": "2017-05-19T16:21:47-05:00",
      "nextTask": null,
      "nextdealid": "2",
      "nexttaskid": "0",
      "organization": null,
      "owner": "1",
      "percent": "0",
      "stage": "3",
      "status": "0",
      "title": "Another Deal",
      "value": "10000"
    },
    {
      "activitycount": "1",
      "cdate": "2017-05-19T16:23:01-05:00",
      "contact": "2",
      "currency": "usd",
      "edate": "0000-00-00 00:00:00",
      "group": "1",
      "hash": "fe7cc4f3",
      "id": "2",
      "links": {
        "activities": "/api/3/deals/2/activities",
        "contact": "/api/3/deals/2/contact",
        "contactDeals": "/api/3/deals/2/contactDeals",
        "group": "/api/3/deals/2/group",
        "nextTask": "/api/3/deals/2/nextTask",
        "notes": "/api/3/deals/2/notes",
        "organization": "/api/3/deals/2/organization",
        "owner": "/api/3/deals/2/owner",
        "scoreValues": "/api/3/deals/2/scoreValues",
        "stage": "/api/3/deals/2/stage",
        "tasks": "/api/3/deals/2/tasks"
      },
      "mdate": "2017-05-19T16:23:01-05:00",
      "nextTask": null,
      "nextdealid": "1",
      "nexttaskid": "0",
      "organization": null,
      "owner": "1",
      "percent": "0",
      "stage": "3",
      "status": "0",
      "title": "Urgent Deal",
      "value": "10000"
    }
  ]
}
{
  "errors": [
    {
      "detail": "Target stage does not belong to same pipeline",
      "source": {
        "pointer": "/data/attributes/stage"
      },
      "status": 422,
      "title": "Invalid attribute"
    }
  ]
}

Path Params

id
int32
required

Deal stage's id whose deals are to be moved to another deal stage

Body Params

deal
object
deal.stage
string

Target deal stage's id to move deals to

 

To update a deal stage, the following permissions are required.

  • Deal permission: the user should have permission to manage deals.
  • Edit Pipeline permission: the user should have permission to edit pipelines.
  • Pipeline-specific permission: the user should have permission to manage the pipeline that the stage belongs to.

If the source stage's pipeline is different from target stage's pipeline, 422 Unprocessible Entity error code will be returned.

Suggest Edits

Deal Tasks

Create, retrieve, update, delete tasks.

 

The tasks endpoint can be used to read, update, create and delete tasks for an account. You can use it to retrieve tasks by different kinds of parameters such as due date, status, etc.

Tasks can belong to a contact, a deal, or neither. See the table below for more information on how to filter tasks based on the tasks relationship type.

Tasks can also be retrieved based on Task Types (see Deal Task Types). Task Types are configurable and can vary by account.

Relationships

Relationship
reltype
relid

Contact

Subscriber

subscriber.id

Deal

Deal

deal.id (see Retrieve a deal)

Neither

0

Suggest Edits

Create a new task

Create a new task

 
posthttps://:account.api-us1.com/api/3/dealTasks
{
  "dealTask": {
    "title":null,
    "reltype":"Subscriber",
    "relid":"7",
    "status":0,
    "note":"Testing Task",
    "duedate":"2017-02-25T12:00:00-06:00",
    "edate":"2017-02-25T12:15:00-06:00",
    "dealTasktype":"1",
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealTask": {
    "id":"1",
    "duedate":"2017-02-25T12:00:00-06:00",
    "edate":"2017-02-25T12:15:00-06:00",
    "status":0,
    "title":null,
    "note":"Testing Task",
    "relid":"7",
    "reltype":"Subscriber",
    "dealTasktype":"1",
    "cdate":"2017-02-24T13:21:56-06:00",
    "udate":"2017-02-24T13:21:56-06:00",
    "automation":null,
    "doneAutomation":null,
    "user":"1",
    "owner":{
      "type":"contact",
      "id":"7"
    },
    "links": {
      "activities":"/1/activities",
      "automation":"/1/automation",
      "dealTasktype":"/1/dealTasktype",
      "doneAutomation":"/1/doneAutomation",
      "notes":"/1/notes",
      "owner":"/1/owner",
      "taskNotifications":"/1/taskNotifications",
      "user":"/1/user"
    }
  }
}

Body Params

dealTask
object
dealTask.title
string

The title to be assigned to the task

dealTask.reltype
string

The name of the relating object (see relationships table)

dealTask.relid
int32
required

The id of the relational object for this task

dealTask.status
int32

The status to be assigned the task

dealTask.note
string

The content describing the task

dealTask.duedate
date
required

Due date of the task

dealTask.dealTasktype
int32
required

The type of the task based on the available Task Types in the account

 
Suggest Edits

Retrieve a task

Retrieve an existing task

 
gethttps://:account.api-us1.com/api/3/dealTasks/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealTasks/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealTasks/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealTasks/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealTasks/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealTasks/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealTask": {
    "relid":"5",
    "reltype":"Deal",
    "dealTasktype":"1",
    "user":"1",
    "automation":null,
    "cdate":"2017-02-24T15:01:37-06:00",
    "duedate":"2017-02-28T12:00:00-06:00",
    "edate":"2017-02-28T12:15:00-06:00",
    "duration":"0",
    "status":"0",
    "title":"",
    "note":"Deal task title!",
    "donedate":null,
    "doneAutomation":null,
    "udate":"2017-02-24T15:01:37-06:00",
    "owner":{
      "type":"deal",
      "id":"5"
    },
    "id":"1",
    "links": {
      "activities":"/1/activities",
      "automation":"/1/automation",
      "dealTasktype":"/1/dealTasktype",
      "doneAutomation":"/1/doneAutomation",
      "notes":"/1/notes",
      "owner":"/1/owner",
      "taskNotifications":"/1/taskNotifications",
      "user":"/1/user"
    }
  }
}

Path Params

id
int32
required

The ID of the task

 
Suggest Edits

Update a task

Update an existing task

 
puthttps://:account.api-us1.com/api/3/dealTasks/id
{
  "dealTask": {
    "title":null,
    "reltype":"Subscriber",
    "relid":"7",
    "status":0,
    "note":"Testing Task",
    "duedate":"2017-02-25T12:00:00-06:00",
    "edate":"2017-02-25T12:15:00-06:00",
    "dealTasktype":"1",
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealTask": {
    "id":"1",
    "duedate":"2017-02-25T12:00:00-06:00",
    "edate":"2017-02-25T12:15:00-06:00",
    "status":0,
    "title":null,
    "note":"Testing Task",
    "relid":"7",
    "reltype":"Subscriber",
    "dealTasktype":"1",
    "cdate":"2017-02-24T13:21:56-06:00",
    "udate":"2017-02-24T13:21:56-06:00",
    "automation":null,
    "doneAutomation":null,
    "user":"1",
    "owner":{
      "type":"contact",
      "id":"7"
    },
    "links": {
      "activities":"/1/activities",
      "automation":"/1/automation",
      "dealTasktype":"/1/dealTasktype",
      "doneAutomation":"/1/doneAutomation",
      "notes":"/1/notes",
      "owner":"/1/owner",
      "taskNotifications":"/1/taskNotifications",
      "user":"/1/user"
    }
  }
}

Path Params

id
int32
required

The ID of the task

Body Params

dealTask
object
dealTask.title
string

The title to be assigned to the task

dealTask.reltype
string

The name of the relating object (see relationships table)

dealTask.relid
int32

The id of the relational object for this task

dealTask.status
int32

The status to be assigned the task

dealTask.note
string

The content describing the task

dealTask.duedate
date

Due date of the task

dealTask.dealTasktype
int32

The type of the task based on the available Task Types in the account

 
Suggest Edits

Delete a task

Delete an existing task

 
deletehttps://:account.api-us1.com/api/3/dealTasks/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/dealTasks/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/dealTasks/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealTasks/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/dealTasks/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealTasks/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
int32
required

The task id

 
Suggest Edits

List all tasks

Retrieve a list of existing tasks

 
gethttps://:account.api-us1.com/api/3/dealTasks
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealTasks
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealTasks' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealTasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealTasks");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealTasks"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealTasks": [{
    "id":"1",
    "duedate":"2017-02-25T12:00:00-06:00",
    "edate":"2017-02-25T12:15:00-06:00",
    "status":0,
    "title":null,
    "note":"Testing Task",
    "relid":"7",
    "reltype":"Subscriber",
    "dealTasktype":"1",
    "cdate":"2017-02-24T13:21:56-06:00",
    "udate":"2017-02-24T13:21:56-06:00",
    "automation":null,
    "doneAutomation":null,
    "user":"1",
    "owner":{
      "type":"contact",
      "id":"7"
    },
    "links": {
      "activities":"/1/activities",
      "automation":"/1/automation",
      "dealTasktype":"/1/dealTasktype",
      "doneAutomation":"/1/doneAutomation",
      "notes":"/1/notes",
      "owner":"/1/owner",
      "taskNotifications":"/1/taskNotifications",
      "user":"/3/dealTasks/1/user"
    }
  },
  {
    "id":"2",
    "duedate":"2017-02-25T12:00:00-06:00",
    "edate":"2017-02-25T12:15:00-06:00",
    "status":0,
    "title":null,
    "note":"Testing Task 2",
    "relid":"8",
    "reltype":"Deal",
    "dealTasktype":"1",
    "cdate":"2017-02-24T13:21:56-06:00",
    "udate":"2017-02-24T13:21:56-06:00",
    "automation":null,
    "doneAutomation":null,
    "user":"1",
    "owner":{
      "type":"deal",
      "id":"5"
    },
    "links": {
      "activities":"/2/activities",
      "automation":"/2/automation",
      "dealTasktype":"/2/dealTasktype",
      "doneAutomation":"/2/doneAutomation",
      "notes":"/2/notes",
      "owner":"/2/owner",
      "taskNotifications":"/2/taskNotifications",
      "user":"/2/user"
    }
  }],
  "meta":{
    "total":"2"
  }
}

Query Params

filters[title]
string

The title to be assigned to the task

filters[reltype]
string

The name of the relating object (see relationships table)

filters[relid]
int32

The id of the relational object for this task

filters[status]
int32

The status to be assigned the task

filters[note]
string

The content describing the task

filters[duedate]
date

Due date of the task

filters[d_tasktypeid]
int32

The type of the task based on the available Task Types in the account

filters[userid]
int32

User ID this task belongs to

 
Suggest Edits

Deal Task Types

 
Suggest Edits

Create a deal task type

Create a new task type

 
posthttps://:account.api-us1.com/api/3/dealTasktypes
{
  "dealTasktype": {
    "title": "Skype"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealTasktype": {
    "cdate": "2017-03-02T14:28:53-06:00",
    "defduration": "0",
    "id": "7",
    "links": [],
    "status": "0",
    "title": "Skype",
    "udate": "2017-03-02T14:28:53-06:00"
  }
}

Body Params

dealTasktype
object
dealTasktype.title
string
required

Deal task type's title. The title should be unique among deal task types.

 
Suggest Edits

Retrieve a deal task type

Retrieve an existing task type

 
gethttps://:account.api-us1.com/api/3/dealTasktypes/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealTasktypes/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealTasktypes/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealTasktypes/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealTasktypes/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealTasktypes/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealTasktype": {
    "cdate": "2017-03-02T14:22:51-06:00",
    "defduration": "0",
    "id": "5",
    "links": [],
    "status": "0",
    "title": "Skype",
    "udate": "2017-03-02T14:22:51-06:00"
  }
}

Path Params

id
int32
required

Deal task type's id

 
Suggest Edits

Update a deal task type

Update an existing task type

 
puthttps://:account.api-us1.com/api/3/dealTasktypes/id
{
  "dealTasktype": {
    "title": "Meet in person"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealTasktype": {
    "cdate": "2017-03-02T14:28:53-06:00",
    "defduration": "0",
    "id": "7",
    "links": [],
    "status": "0",
    "title": "Meet in person",
    "udate": "2017-03-02T14:32:20-06:00"
  }
}

Path Params

id
int32
required

Deal task type's id

Body Params

dealTasktype
object
dealTasktype.title
string

Deal task type's title. The title should be unique among deal task types.

 
Suggest Edits

Delete a deal task type

Delete an existing task type

 
deletehttps://:account.api-us1.com/api/3/dealTasktypes/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/dealTasktypes/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/dealTasktypes/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealTasktypes/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/dealTasktypes/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealTasktypes/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
int32
required

Deal task type's id

 

If the deal task type has existing deal tasks, the request will be rejected with a HTTP response code 409. Before this deal task type can be deleted, all deal tasks under this deal task type must be either moved to another deal task type or deleted. To move deal tasks under the deal task type to another deal task type, please see Move deal tasks to another deal task type.

Suggest Edits

List all deal task types

Retrieve all existing task types

 
gethttps://:account.api-us1.com/api/3/dealTasktypes
curl --request GET \
  --url https:///:account.api-us1.com/api/3/dealTasktypes
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/dealTasktypes' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/dealTasktypes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/dealTasktypes");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/dealTasktypes"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "dealTasktypes": [
    {
      "cdate": null,
      "defduration": "0",
      "id": "1",
      "links": [],
      "status": "0",
      "title": "Call",
      "udate": null
    },
    {
      "cdate": null,
      "defduration": "0",
      "id": "2",
      "links": [],
      "status": "0",
      "title": "Email",
      "udate": null
    },
    {
      "cdate": null,
      "defduration": "0",
      "id": "3",
      "links": [],
      "status": "0",
      "title": "Lunch",
      "udate": null
    },
    {
      "cdate": null,
      "defduration": "0",
      "id": "4",
      "links": [],
      "status": "0",
      "title": "Meeting",
      "udate": null
    }
  ],
  "meta": {
    "total": "4"
  }
}
 
Suggest Edits

Move deal tasks to another deal task type

Move tasks to a different task type

 
puthttps://:account.api-us1.com/api/3/dealTasktypes/id/dealTasks
{
  "dealTask": {
    "dealTasktype": "2"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "dealTasks": [
    {
      "automation": null,
      "cdate": "2017-06-01T15:08:55-05:00",
      "dealTasktype": "2",
      "doneAutomation": null,
      "donedate": null,
      "duedate": "2017-06-02T12:00:00-05:00",
      "duration": "0",
      "edate": "2017-06-02T12:15:00-05:00",
      "id": "1",
      "links": {
        "activities": "/api/3/dealTasks/1/activities",
        "automation": "/api/3/dealTasks/1/automation",
        "dealTasktype": "/api/3/dealTasks/1/dealTasktype",
        "doneAutomation": "/api/3/dealTasks/1/doneAutomation",
        "notes": "/api/3/dealTasks/1/notes",
        "owner": "/api/3/dealTasks/1/owner",
        "taskNotifications": "/api/3/dealTasks/1/taskNotifications",
        "user": "/api/3/dealTasks/1/user"
      },
      "note": "Call Steve",
      "owner": {
        "id": "1",
        "type": "deal"
      },
      "relid": "1",
      "reltype": "Deal",
      "status": "0",
      "title": "",
      "udate": "2017-06-01T15:08:55-05:00",
      "user": "1"
    }
  ],
  "deals": [
    {
      "activitycount": "2",
      "cdate": "2017-06-01T15:08:41-05:00",
      "contact": "1",
      "currency": "usd",
      "edate": "0000-00-00 00:00:00",
      "group": "1",
      "hash": "3abd127b",
      "id": "1",
      "links": {
        "activities": "/api/3/deals/1/activities",
        "contact": "/api/3/deals/1/contact",
        "contactDeals": "/api/3/deals/1/contactDeals",
        "group": "/api/3/deals/1/group",
        "nextTask": "/api/3/deals/1/nextTask",
        "notes": "/api/3/deals/1/notes",
        "organization": "/api/3/deals/1/organization",
        "owner": "/api/3/deals/1/owner",
        "scoreValues": "/api/3/deals/1/scoreValues",
        "stage": "/api/3/deals/1/stage",
        "tasks": "/api/3/deals/1/tasks"
      },
      "mdate": "2017-06-01T15:08:55-05:00",
      "nextTask": "1",
      "nextdate": "2017-06-02T12:00:00-05:00",
      "nextdealid": "1",
      "nexttaskid": "1",
      "organization": null,
      "owner": "1",
      "percent": "0",
      "stage": "1",
      "status": "0",
      "title": "New deal",
      "value": "10000"
    }
  ]
}

Path Params

id
int32
required

Deal task type's id

Body Params

dealTask
object
dealTask.dealTasktype
string

Deal task type's id to move deal tasks to

 
Suggest Edits

Organizations

 

Organizations can be used to segment customers, trigger automations, display conditional content and more. The API allows you to create, update, and delete organization resources. You can retrieve individual organizations as well as a list of all organizations.

Suggest Edits

Create an organization

Create a new organization

 
posthttps://:account.api-us1.com/api/3/organizations
{
  organization: {
		name: "Test Organization"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "organization":{
    "name":"Test Organization",
    "links":[],
    "id":"1"
  }
}

Body Params

organization
object
organization.name
string
required

The name to be assigned to the organization.

 
Suggest Edits

Retrieve an organization

Retrieve an existing organization

 
gethttps://:account.api-us1.com/api/3/organizations/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/organizations/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/organizations/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/organizations/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/organizations/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/organizations/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "organization":{
    "name":"Test Organization",
    "links":[],
    "id":"1",
    "contactCount":"0",
    "dealCount":"0"
  }
}

Path Params

id
int32
required

The ID of the organization

 
Suggest Edits

Update an organization

Update an organization

 
puthttps://:account.api-us1.com/api/3/organizations/id
{
  organization: {
    name: "Test Organization"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "organization":{
    "name":"Test Organization",
    "links":[],
    "id":"1"
  }
}

Path Params

id
int32
required

The ID of the organization

Body Params

organization
object
organization.name
string

The name of the organization

 
Suggest Edits

Delete an organization

Delete an existing organization

 
deletehttps://:account.api-us1.com/api/3/organizations/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/organizations/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/organizations/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/organizations/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/organizations/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/organizations/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
int32
required

The organization id

 
Suggest Edits

Delete multiple organizations

Delete multiple existing organizations

 
deletehttps://:account.api-us1.com/api/3/organizations/bulk_delete
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/organizations/bulk_delete
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/organizations/bulk_delete' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/organizations/bulk_delete")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/organizations/bulk_delete");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/organizations/bulk_delete"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "meta": {
    "success":true
  }
}

Query Params

ids[]
array of integers

A list of organization ids to be deleted.

 
Suggest Edits

List all organizations

List all existing organizations

 
gethttps://:account.api-us1.com/api/3/organizations
curl --request GET \
  --url https:///:account.api-us1.com/api/3/organizations
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/organizations' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/organizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/organizations");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/organizations"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "organizations":[{
    "name":"Test Organization",
    "links":[],
    "id":"1",
    "contactCount":"0",
    "dealCount":"0"
  },{
    "name":"Test Organization 2",
    "links":[],
    "id":"2",
    "contactCount":"0",
    "dealCount":"0"
  },{
    "name":"Test Organization 3",
    "links":[],
    "id":"3",
    "contactCount":"0",
    "dealCount":"0"
  }],
  "meta":{
    "total":"3"
  }
}

Query Params

filters[name]
string

Filter by the name of the organization.

orders[name]
string

Order by name

orders[contact_count]
string

Order by contact count

orders[deal_count]
string

Order by deal count

 
Suggest Edits

Connections

 

Deep Data connection resources represent a link between an ActiveCampaign account and an account in some external service such as Shopify. This API is intended to be used by third-parties who create integrations between such services and ActiveCampaign. The API allows you to create, delete, and update connections. You can retrieve individual connections as well as a list of all connections in an account.

Note that connections associated with integrations developed internally by ActiveCampaign can be retrieved but not modified through the API.

Suggest Edits

Create a connection

Create a new connection resource.

 
posthttps://:account.api-us1.com/api/3/connections
{
  "connection": {
    "service": "fooCommerce",
    "externalid": "toystore123",
    "name": "Toystore, Inc.",
    "logoUrl": "http://example.com/i/foo.png",
    "linkUrl": "http://example.com/foo/"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "connection": {
    "isInternal": 0,
    "service": "fooCommerce",
    "externalid": "toystore123",
    "name": "Toystore, Inc.",
    "logoUrl": "http://example.com/i/foo.png",
    "linkUrl": "http://example.com/foo/",
    "cdate": "2017-02-02T14:56:05-06:00",
    "udate": "2017-02-02T14:56:05-06:00",
    "links": {
      "customers": "/connections/1/customers"
    },
    "id": "1"
  }
}

Body Params

connection
object
connection.service
string
required

The name of the service.

connection.externalid
string
required

The id of the account in the external service.

connection.name
string
required

The name associated with the account in the external service. Often this will be a company name (e.g., 'My Toystore, Inc.').

connection.logoUrl
string
required

The URL to a logo image for the external service.

connection.linkUrl
string
required

The URL to a page where the integration with the external service can be managed in the third-party's website.

 
Suggest Edits

Retrieve a connection

Retrieve an existing connection resource.

 
gethttps://:account.api-us1.com/api/3/connections/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/connections/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/connections/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/connections/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/connections/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/connections/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "connection": {
    "isInternal": 0,
    "service": "fooCommerce",
    "externalid": "toystore123",
    "name": "Toystore, Inc.",
    "logoUrl": "http://example.com/i/foo.png",
    "linkUrl": "http://example.com/foo/",
    "cdate": "2017-02-02T14:56:05-06:00",
    "udate": "2017-02-02T14:56:05-06:00",
    "links": {
      "customers": "/connections/1/customers"
    },
    "id": "1"
  }
}

Path Params

id
string
required

The id of the connection to retrieve

 
Suggest Edits

Update a connection

Update an existing connection resource.

 
puthttps://:account.api-us1.com/api/3/connections/id
{
  "connection": {
    "externalid": "acme123@foo.com",
    "name": "Acme, Inc."
  }
}
A binary file was returned

You couldn't be authenticated

{
  "connection": {
    "service": "fooCommerce",
    "externalid": "acme123@foo.com",
    "name": "Acme, Inc.",
    "isInternal": "0",
    "status": "1",
    "syncStatus": "0",
    "logoUrl": "http://foocorp.net/i/path3523.png",
    "linkUrl": "http://example.com/",
    "cdate": "2017-02-02T14:56:05-06:00",
    "udate": "2017-02-03T15:54:51-06:00",
    "links": {
      "customers": "/api/3/connections/2/customers"
    },
    "id": "2"
  }
}

Path Params

id
string
required

The id of the connection to update

Body Params

connection
object
connection.service
string

The name of the service.

connection.externalid
string

The id of the account in the external service.

connection.name
string

The name associated with the account in the external service.

connection.logoUrl
string

The URL to a logo image for the third-party service.

connection.linkUrl
string

The link to the third-party integrator's site.

connection.status
int32

The status of the connection (0 = error; 1 = connected)

connection.syncStatus
int32

The status of a sync triggered on the connection (0 = sync stopped; 1 = sync running).

 
Suggest Edits

Delete a connection

Delete an existing connection resource.

 
deletehttps://:account.api-us1.com/api/3/connections/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/connections/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/connections/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/connections/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/connections/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/connections/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
string
required

The id of the connection to delete.

 
Suggest Edits

List all connections

List all existing connection resources.

 
gethttps://:account.api-us1.com/api/3/connections
curl --request GET \
  --url https:///:account.api-us1.com/api/3/connections
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/connections' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/connections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/connections");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/connections"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "connections": [
    {
      "service": "shopify",
      "externalid": "foo.myshopify.com",
      "name": "Foo, Inc.",
      "isInternal": "1",
      "status": "1",
      "syncStatus": "0",
      "lastSync": "2017-02-02T13:09:07-06:00",
      "logoUrl": "",
      "linkUrl": "",
      "cdate": "2017-02-02T13:09:07-06:00",
      "udate": "2017-02-02T13:09:12-06:00",
      "links": {
        "customers": "/api/3/connections/1/customers"
      },
      "id": "1"
    },
    {
      "service": "fooCommerce",
      "externalid": "acme123@foo.com",
      "name": "Acme, Inc.",
      "isInternal": "0",
      "status": "1",
      "syncStatus": "0",
      "lastSync": null,
      "logoUrl": "http://example.com/i/foo.png",
      "linkUrl": "http://example.com/foo/",
      "cdate": "2017-02-02T14:56:05-06:00",
      "udate": "2017-02-03T15:54:51-06:00",
      "links": {
        "customers": "/api/3/connections/2/customers"
      },
      "id": "2"
    }
  ],
  "meta": {
    "total": "2"
  }
}

Query Params

filters[service]
string

Filter by the external service name.

filters[externalid]
string

Filter by the external id associated with a connection.

 
Suggest Edits

E-Commerce Customers

 

E-Commerce customer resources represent a customer in an external e-commerce service such as Shopify. Customer resources primarily hold aggregate e-commerce data associated with a contact including the total revenue, total number of orders, and total number of products ordered (see the table below). This data cannot be saved to a customer object directly, but will be updated when order resources are created or updated for a customer. Note that a customer is related to a contact by the email address.

Field
Description

totalRevenue

The total revenue amount for the customer.

totalOrders

The total number of orders placed by the customer.

totalProducts

The total number of products ordered by the customer.

avgRevenuePerOrder

The average revenue per order for the customer.

avgProductCategory

The most frequent product category ordered by a customer.

Fields representing a monetary value are formatted in the lowest unit of the currency. For example, $32.80 would be represented as 3280.

The API allows you to create, update, and delete customer resources. You can retrieve individual customers as well as a list of all customers. Before you can create any customers, you must have created a connection resource for the e-commerce service.

Suggest Edits

Create a customer

Create a new e-commerce customer resource.

 
posthttps://:account.api-us1.com/api/3/ecomCustomers
{
  "ecomCustomer": {
    "connectionid": "1",
    "externalid": "56789",
    "email": "alice@example.com"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "ecomCustomer": {
    "connectionid": "1",
    "externalid": "56789",
    "email": "alice@example.com",
    "links": {
      "connection": "/api/3/ecomCustomers/1/connection",
      "orders": "/api/3/ecomCustomers/1/orders"
    },
    "id": "1",
    "connection": "1"
  }
}

Body Params

ecomCustomer
object
ecomCustomer.connectionid
string
required

The id of the connection object for the service where the customer originates.

ecomCustomer.externalid
string
required

The id of the customer in the external service.

ecomCustomer.email
string
required

The email address of the customer.

 
Suggest Edits

Retrieve a customer

Retrieve an existing e-commerce customer resource.

 
gethttps://:account.api-us1.com/api/3/ecomCustomers/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/ecomCustomers/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/ecomCustomers/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/ecomCustomers/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/ecomCustomers/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/ecomCustomers/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ecomCustomer": {
    "connectionid": "1",
    "externalid": "56789",
    "email": "alice@example.com",
    "totalRevenue": "3280",
    "totalOrders": "2",
    "totalProducts": "2",
    "avgRevenuePerOrder": "2285",
    "avgProductCategory": "Electronics",
    "tstamp": "2017-02-06T14:05:31-06:00",
    "links": {
      "connection": "/api/3/ecomCustomers/1/connection",
      "orders": "/api/3/ecomCustomers/1/orders"
    },
    "id": "1",
    "connection": "1"
  }
}

Path Params

id
string
required

The id of the customer to retrieve

 
Suggest Edits

Update a customer

Update an existing e-commerce customer resource.

 
puthttps://:account.api-us1.com/api/3/ecomCustomers/id
{
  "ecomCustomer": {
    "externalid": "98765"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "ecomCustomer": {
    "connectionid": "1",
    "externalid": "98765",
    "email": "alice@example.com",
    "totalRevenue": "3280",
    "totalOrders": "2",
    "totalProducts": "2",
    "avgRevenuePerOrder": "2285",
    "avgProductCategory": "Electronics",
    "tstamp": "2017-02-06T14:05:31-06:00",
    "links": {
      "connection": "/api/3/ecomCustomers/1/connection",
      "orders": "/api/3/ecomCustomers/1/orders"
    },
    "id": "1",
    "connection": "1"
  }
}

Path Params

id
string
required

The id of the customer to update

Body Params

ecomCustomer
object
ecomCustomer.externalid
string

The id of the customer in the external service.

ecomCustomer.connectionid
string

The id of the connection object for the service where the customer originates.

ecomCustomer.email
string

The email address of the customer.

 

Updating a customer should be rare

You should rarely need to update a customer object directly since its aggregate data fields are updated automatically when orders are saved.

Suggest Edits

Delete a customer

Delete an existing e-commerce customer resource.

 
deletehttps://:account.api-us1.com/api/3/ecomCustomer/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/ecomCustomer/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/ecomCustomer/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/ecomCustomer/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/ecomCustomer/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/ecomCustomer/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
string
required

The id of the customer to delete.

 
Suggest Edits

List all customers

List all e-commerce customer resources.

 
gethttps://:account.api-us1.com/api/3/ecomCustomers
curl --request GET \
  --url https:///:account.api-us1.com/api/3/ecomCustomers
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/ecomCustomers' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/ecomCustomers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/ecomCustomers");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/ecomCustomers"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ecomCustomers": [
    {
      "connectionid": "1",
      "externalid": "56789",
      "email": "alice@example.com",
      "totalRevenue": "3280",
      "totalOrders": "2",
      "totalProducts": "2",
      "avgRevenuePerOrder": "2285",
      "avgProductCategory": "Electronics",
      "tstamp": "2017-02-06T14:05:31-06:00",
      "links": {
        "connection": "/api/3/ecomCustomers/1/connection",
        "orders": "/api/3/ecomCustomers/1/orders"
      },
      "id": "1",
      "connection": "1"
    },
    {
      "connectionid": "2",
      "externalid": "44322",
      "email": "alice@example.com",
      "totalRevenue": "7599",
      "totalOrders": "1",
      "totalProducts": "1",
      "avgRevenuePerOrder": "7599",
      "avgProductCategory": "Books",
      "tstamp": "2016-12-13T18:02:07-06:00",
      "links": {
        "connection": "/api/3/ecomCustomers/3/connection",
        "orders": "/api/3/ecomCustomers/3/orders"
      },
      "id": "3",
      "connection": "2"
    },
    {
      "connectionid": "0",
      "externalid": "0",
      "email": "alice@example.com",
      "totalRevenue": "10879",
      "totalOrders": "3",
      "totalProducts": "3",
      "avgRevenuePerOrder": "3626",
      "avgProductCategory": "Electronics",
      "tstamp": "2017-02-06T14:05:31-06:00",
      "links": {
        "connection": "/api/3/ecomCustomers/2/connection",
        "orders": "/api/3/ecomCustomers/2/orders"
      },
      "id": "2",
      "connection": null
    }
  ],
  "meta": {
    "total": "3"
  }
}

Query Params

filters[email]
string

Filter by the email address of a customer.

filters[externalid]
string

Filter by the id of the customer in the external service.

filters[connectionid]
string

Filter by the id of the connection object for the service where the customer originates.

 
Suggest Edits

E-Commerce Orders

 

E-Commerce order resources represent orders in an external e-commerce service such as Shopify. The API allows you to create, update, and delete order resources. You can retrieve individual orders as well as a list of all orders. Before you can create any orders, you must have created a connection resource for the e-commerce service and a customer resource for the customer who placed the order.

Whenever order resources are saved through the API, the aggregate data fields of the related customer resource are automatically updated.

The automation start Makes a purchase will only trigger if the E-Commerce order source is from a realtime webhook ecomOrder.source = 1. For more information please read this post The Makes a Purchase Trigger is Here!.

Suggest Edits

Create an order

Create a new e-commerce order resource.

 
posthttps://:account.api-us1.com/api/3/ecomOrders
{
  "ecomOrder": {
    "externalid": "3246315233",
    "source": "1",
    "email": "alice@example.com",
    "orderNumber": "1057",
    "orderProducts": [
      {
        "externalid": "PROD12345",
        "name": "Pogo Stick",
        "price": "4900",
        "quantity": "1",
        "category": "Toys"
      },
      {
        "externalid": "PROD23456",
        "name": "Skateboard",
        "price": "3000",
        "quantity": "1",
        "category": "Toys"
      }
    ],
    "orderUrl": "https://example.com/orders/3246315233",
    "orderDate": "2016-09-13T17:41:39-04:00",
    "shippingMethod": "UPS Ground",
    "totalPrice": "9111",
    "currency": "USD",
    "connectionid": "1",
    "customerid": "1"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "ecomOrder": {
    "externalid": "3246315233",
    "source": "1",
    "email": "alice@example.com",
    "currency": "USD",
    "connectionid": "1",
    "customerid": "1",
    "orderNumber": "1057",
    "orderUrl": "https://example.com/orders/3246315233",
    "orderDate": "2016-09-13T17:41:39-04:00",
    "shippingMethod": "UPS Ground",
    "totalPrice": "9111",
    "totalProducts": 2,
    "customer": "1",
    "orderProducts": [
      "2",
      "3"
    ],
    "links": {
      "customer": "/api/3/ecomOrders/2/customer",
      "orderProducts": "/api/3/ecomOrders/2/orderProducts"
    },
    "id": "2"
  },
  "ecomOrderProducts": [
    {
      "orderid": "2",
      "connectionid": "1",
      "externalid": "PROD12345",
      "name": "Pogo Stick",
      "price": "4900",
      "quantity": "1",
      "category": "Toys",
      "tstamp": "2017-02-07T10:25:12-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/2/ecomOrder"
      },
      "id": "2",
      "ecomOrder": "2"
    },
    {
      "orderid": "2",
      "connectionid": "1",
      "externalid": "PROD23456",
      "name": "Skateboard",
      "price": "3000",
      "quantity": "1",
      "category": "Toys",
      "tstamp": "2017-02-07T10:25:12-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/3/ecomOrder"
      },
      "id": "3",
      "ecomOrder": "2"
    }
  ]
}

Body Params

ecomOrder
object
ecomOrder.externalid
string
required

The id of the order in the external service.

ecomOrder.source
int32

The order source code (0 - sync, 1 - realtime webhook).

ecomOrder.email
string
required

The email address of the customer who placed the order.

ecomOrder.orderProducts
object
ecomOrder.orderProducts.name
string
required

The name of the product

ecomOrder.orderProducts.price
int32
required

The price of the product.

ecomOrder.orderProducts.quantity
int32
required

The quantity ordered.

ecomOrder.orderProducts.externalid
string

The id of the product in the external service.

ecomOrder.totalPrice
string
required

The total price of the order including tax and shipping charges.

ecomOrder.currency
string
required

The currency of the order (3-digit ISO code, e.g., 'USD').

ecomOrder.connectionid
int32
required

The id of the connection from which this order originated.

ecomOrder.customerid
int32
required

The id of the customer associated with this order.

ecomOrder.orderNumber
string

The order number in the external system (this may differ from the externalid).

ecomOrder.orderUrl
string

The URL for the order in the external service.

ecomOrder.orderDate
date

The date the order was placed.

ecomOrder.shippingMethod
string

The shipping method of the order.

 
Suggest Edits

Retrieve an order

Retrieve an existing e-commerce order resource.

 
gethttps://:account.api-us1.com/api/3/ecomOrders/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/ecomOrders/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/ecomOrders/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/ecomOrders/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/ecomOrders/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/ecomOrders/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ecomOrder": {
    "externalid": "3246315233",
    "source": "1",
    "email": "alice@example.com",
    "currency": "USD",
    "connectionid": "1",
    "customerid": "1",
    "orderNumber": "1057",
    "orderUrl": "https://example.com/orders/3246315233",
    "orderDate": "2016-09-13T17:41:39-04:00",
    "shippingMethod": "UPS Ground",
    "totalPrice": "9111",
    "totalProducts": 2,
    "customer": "1",
    "orderProducts": [
      "2",
      "3"
    ],
    "links": {
      "customer": "/api/3/ecomOrders/2/customer",
      "orderProducts": "/api/3/ecomOrders/2/orderProducts"
    },
    "id": "2"
  },
  "ecomOrderProducts": [
    {
      "orderid": "2",
      "connectionid": "1",
      "externalid": "PROD12345",
      "name": "Pogo Stick",
      "price": "4900",
      "quantity": "1",
      "category": "Toys",
      "tstamp": "2017-02-07T10:25:12-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/2/ecomOrder"
      },
      "id": "2",
      "ecomOrder": "2"
    },
    {
      "orderid": "2",
      "connectionid": "1",
      "externalid": "PROD23456",
      "name": "Skateboard",
      "price": "3000",
      "quantity": "1",
      "category": "Toys",
      "tstamp": "2017-02-07T10:25:12-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/3/ecomOrder"
      },
      "id": "3",
      "ecomOrder": "2"
    }
  ]
}

Path Params

id
int32
required

The id of the order to retrieve.

 
Suggest Edits

Update an order

Update an existing e-commerce resource.

 
puthttps://:account.api-us1.com/api/3/ecomOrders/id
{
	"ecomOrder": {
		"shippingMethod": "Expedited Shipping",
		"totalPrice": "11111"
	}
}
A binary file was returned

You couldn't be authenticated

{
  "ecomOrder": {
    "customerid": "1",
    "connectionid": "1",
    "externalid": "3246315233",
    "source": "1",
    "orderNumber": "1057",
    "email": "alice@example.com",
    "totalPrice": "11111",
    "totalProducts": "2",
    "currency": "USD",
    "shippingMethod": "Expedited Shipping",
    "orderUrl": "https://example.com/orders/3246315233",
    "orderDate": "2016-09-13 17:41:39",
    "tstamp": "2017-02-07T11:36:38-06:00",
    "customer": "1",
    "links": {
      "customer": "/api/3/ecomOrders/1/customer",
      "orderProducts": "/api/3/ecomOrders/1/orderProducts"
    },
    "id": "1"
  }
}

Path Params

id
int32
required

The id of the order to update

Body Params

ecomOrder
object
ecomOrder.totalPrice
int32

The total price of the order including tax and shipping charges.

ecomOrder.currency
string

The currency of the order (3-digit ISO code, e.g., 'USD').

ecomOrder.orderNumber
string

The order number in the external system (this may differ from the externalid).

ecomOrder.orderUrl
string

The URL for the order in the external service.

ecomOrder.orderDate
string

The date the order was placed.

ecomOrder.shippingMethod
string

The shipping method of the order.

ecomOrder.email
string

The email address of the customer who placed the order.

ecomOrder.orderProducts
array of mixed types

A list of product objects, each containing information about a product included in the order (see params specified for creating an order.

 

Updating products for an order

When including the orderProducts field in an update request, bear in mind that an order's products will be replaced with whatever is specified.

Suggest Edits

Delete an order

Delete an existing e-commerce order resource.

 
deletehttps://:account.api-us1.com/api/3/ecomOrders/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/ecomOrders/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/ecomOrders/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/ecomOrders/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/ecomOrders/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/ecomOrders/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
int32
required

The id of the order to delete.

 
Suggest Edits

List all orders

List all existing e-commerce order resources.

 
gethttps://:account.api-us1.com/api/3/ecomOrders
curl --request GET \
  --url https:///:account.api-us1.com/api/3/ecomOrders
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/ecomOrders' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/ecomOrders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/ecomOrders");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/ecomOrders"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ecomOrders": [
    {
      "customerid": "1",
      "connectionid": "1",
      "externalid": "3246315233",
      "source": "1",
      "orderNumber": "1057",
      "email": "alice@example.com",
      "totalPrice": "9111",
      "totalProducts": "2",
      "currency": "USD",
      "shippingMethod": "UPS Ground",
      "orderUrl": "https://example.com/orders/3246315233",
      "orderDate": "2016-09-13 17:41:39",
      "tstamp": "2017-02-07T11:36:38-06:00",
      "orderProducts": [
        "4",
        "5"
      ],
      "links": {
        "customer": "/api/3/ecomOrders/1/customer",
        "orderProducts": "/api/3/ecomOrders/1/orderProducts"
      },
      "id": "1",
      "customer": "1"
    },
    {
      "customerid": "1",
      "connectionid": "1",
      "externalid": "3246312135",
      "source": "1",
      "orderNumber": "1001",
      "email": "alice@example.com",
      "totalPrice": "14486",
      "totalProducts": "2",
      "currency": "USD",
      "shippingMethod": "Standard Shipping",
      "orderUrl": "https://example.com/orders/3246312135",
      "orderDate": "2016-05-31 11:07:52",
      "tstamp": "2017-02-07T11:38:23-06:00",
      "orderProducts": [
        "3"
      ],
      "links": {
        "customer": "/api/3/ecomOrders/2/customer",
        "orderProducts": "/api/3/ecomOrders/2/orderProducts"
      },
      "id": "2",
      "customer": "1"
    }
  ],
  "ecomOrderProducts": [
    {
      "orderid": "1",
      "connectionid": "1",
      "externalid": "PROD12345",
      "name": "Pogo Stick",
      "price": "4900",
      "quantity": "1",
      "category": "Toys",
      "tstamp": "2017-02-07T11:38:26-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/4/ecomOrder"
      },
      "id": "4",
      "ecomOrder": "1"
    },
    {
      "orderid": "1",
      "connectionid": "1",
      "externalid": "PROD23456",
      "name": "Skateboard",
      "price": "3000",
      "quantity": "1",
      "category": "Toys",
      "tstamp": "2017-02-07T11:38:26-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/5/ecomOrder"
      },
      "id": "5",
      "ecomOrder": "1"
    },
    {
      "orderid": "2",
      "connectionid": "1",
      "externalid": "PROD119993",
      "name": "Galaxy S7 case",
      "price": "7000",
      "quantity": "2",
      "category": "Mobile",
      "tstamp": "2017-02-07T11:38:23-06:00",
      "links": {
        "ecomOrder": "/api/3/ecomOrderProducts/3/ecomOrder"
      },
      "id": "3",
      "ecomOrder": "2"
    }
  ],
  "meta": {
    "total": "2"
  }
}

Query Params

filters[connectionid]
int32

Filter by the connection id. Must be greater than 0.

filters[externalid]
int32

Filter by the external id of the order.

filters[email]
string

Filter by the customer email address.

 
Suggest Edits

Event Tracking

 
Suggest Edits

Retrieve status

Get event tracking status (enabled or disabled)

 
gethttps://:account.api-us1.com/api/3/eventTracking
curl --request GET \
  --url https:///:account.api-us1.com/api/3/eventTracking
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/eventTracking' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/eventTracking")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/eventTracking");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/eventTracking"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "eventTracking" {
    "enabled": true
  }
}
 
Suggest Edits

Enable/disable

Enable or disable event tracking

 
puthttps://:account.api-us1.com/api/3/eventTracking
{
  "eventTracking": {
    "enabled": true
  }
}
{
  "eventTracking": {
    "enabled": false
  }
}
A binary file was returned

You couldn't be authenticated

{
  "eventTracking" {
    "enabled": true
  }
}

Body Params

eventTracking
object
eventTracking.enabled
boolean
required

Whether event tracking should be enabled

 
Suggest Edits

List all events (names only)

List the names of tracked events

 
gethttps://:account.api-us1.com/api/3/eventTrackingEvents
curl --request GET \
  --url https:///:account.api-us1.com/api/3/eventTrackingEvents
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/eventTrackingEvents' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/eventTrackingEvents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/eventTrackingEvents");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/eventTrackingEvents"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "eventTrackingEvents": [
    {
      "name": "__pagevisit"
    },
    {
      "name": "__redir"
    }
  ],
  "meta": {
    "total": 2,
  }
}
 
Suggest Edits

Create a new event (name only)

Create a new event tracking event (name only)

 
posthttps://:account.api-us1.com/api/3/eventTrackingEvent
{
	"eventTrackingEvent": {
		"name": "my new fab event"
	}
}
A binary file was returned

You couldn't be authenticated

{
	"eventTrackingEvent": {
		"name": "my new fab event"
	}
}

Body Params

eventTrackingEvent
object
eventTrackingEvent.name
string
required

The name of the event

 

This will only add the event name. It will not add values for an event. Make sure that event tracking is enabled before making this call.

Suggest Edits

Remove event (name only)

Remove an existing event tracking event (name only)

 
deletehttps://:account.api-us1.com/api/3/eventTrackingEvent/name
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/eventTrackingEvent/name
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/eventTrackingEvent/name' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/eventTrackingEvent/name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/eventTrackingEvent/name");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/eventTrackingEvent/name"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

name
string
required

Name of event to delete. Spaces in names are allowed, but must be encoded (for example, "my%20event").

 

This will only remove the event name. Any contacts that have a value associated with this event name already will still retain that association. Make sure that event tracking is enabled before making this call.

Suggest Edits

Site Tracking

 
Suggest Edits

Retrieve status

Get site tracking status (enabled or disabled)

 
gethttps://:account.api-us1.com/api/3/siteTracking
curl --request GET \
  --url https:///:account.api-us1.com/api/3/siteTracking
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/siteTracking' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/siteTracking")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/siteTracking");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/siteTracking"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "siteTracking": {
    "enabled": true
  }
}
 
Suggest Edits

Enable/disable

Enable or disable site tracking

 
puthttps://:account.api-us1.com/api/3/siteTracking
{
  "siteTracking": {
    "enabled": true
  }
}
{
  "siteTracking": {
    "enabled": false
  }
}
A binary file was returned

You couldn't be authenticated

{
  "siteTracking": {
    "enabled": true
  }
}

Body Params

siteTracking
object
siteTracking.enabled
boolean
required

Whether site tracking should be enabled

 
Suggest Edits

List all whitelisted domains

List of all whitelisted site tracking domains

 
gethttps://:account.api-us1.com/api/3/siteTrackingDomains
curl --request GET \
  --url https:///:account.api-us1.com/api/3/siteTrackingDomains
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/siteTrackingDomains' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/siteTrackingDomains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/siteTrackingDomains");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/siteTrackingDomains"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "siteTrackingDomains": [
    {
      "name": "example.com"
    }
  ],
  "meta": {
    "total": 1
  }
}
 
Suggest Edits

Add domain to whitelist

Add a domain to the site tracking whitelist

 
posthttps://:account.api-us1.com/api/3/siteTrackingDomains
{
    "siteTrackingDomain": {
        "name": "example.com"
    }
}
A binary file was returned

You couldn't be authenticated

{
    "siteTrackingDomain": {
        "name": "example.com"
    }
}

Body Params

siteTrackingDomain
object
siteTrackingDomain.name
string
required

The domain name to add to the whitelist.

 
Suggest Edits

Remove domain from whitelist

Remove a domain from the site tracking whitelist

 
deletehttps://:account.api-us1.com/api/3/siteTrackingDomain/name
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/siteTrackingDomain/name
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/siteTrackingDomain/name' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/siteTrackingDomain/name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/siteTrackingDomain/name");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/siteTrackingDomain/name"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

name
string
required

The domain name to remove from the whitelist

 
Suggest Edits

Webhooks

Automatically extract data. Obtain subscription updates, interactions, and more in real-time.

 

Webhooks provide the ability to receive real-time data updates about your contact & campaign activity.

Choose to receive data based on certain actions (subscribes, unsubscribes, reads, etc..) and have all applicable data sent to a URL of your choice. You can then use your own custom script to read, save, and do whatever you want with that data. This is a powerful option that allows you to keep all of your data in sync and opens up the possibility of all sorts of integration options.

With every webhook you create you can choose when it should actually fire. Perhaps you only want to receive data when a contact is added from the API. You can simply specify subscribe as the event and api as the source when you create your webhook. You can specify multiple events and sources for each webhook if you wish. All event and source options are listed below.

Events

Event
Description

forward

Campaign forwarded

open

Campaign opened

share

Campaign shared

sent

Campaign starts sending

subscribe

Contact added

subscriber_note

Contact note added

contact_tag_added

Contact tag added

contact_tag_removed

Contact tag removed

unsubscribe

Contact unsubscription

update

Contact updated

deal_add

Deal added

deal_note_add

Deal note added

deal_pipeline_add

Deal pipeline added

deal_stage_add

Deal stage added

deal_task_add

Deal task added

deal_task_complete

Deal task completed``

deal_tasktype_add

Deal task type added

deal_update

Deal updated

bounce

Email bounces

reply

Email replies

click

Link clicked

list_add

List added

sms_reply

SMS reply

sms_sent

SMS sent

sms_unsub

SMS unsubscribe

Sources

Source
Description

public

Run the hooks when a contact triggers the action

admin

Run the hooks when an admin user triggers the action

api

Run the hooks when an API call triggers the action

system

Run the hooks when automated systems triggers the action

Suggest Edits

Create a webhook

Create a new webhook

 
posthttps://:account.api-us1.com/api/3/webhooks
{
    "webhook": {
      "name": "My Hook",
      "url": "http://example.com/my-hook",
      "events": [
        "subscribe",
        "unsubscribe",
        "sent"
      ],
      "sources": [
        "public",
        "system"
      ]
    }
}
A binary file was returned

You couldn't be authenticated

{
  "webhook": {
    "cdate": "2016-01-01T12:00:00-00:00",
    "listid": "0",
    "name": "My Hook",
    "url": "http://example.com/my-hook",
    "events": [
      "subscribe",
      "unsubscribe",
      "sent"
    ],
    "sources": [
      "public",
      "system"
    ],
    "links": [],
    "id": "1"
  }
}

Body Params

webhook
object
webhook.name
string
required

A name (or label) to give this webhook.

webhook.url
string
required

The URL where the webhook will send the POST request when the event occurs.

webhook.events
array of strings
required

The event(s) that will trigger the webhook to fire.

webhook.sources
array of strings
required

The source(s) causing an event to occur.

webhook.listid
int32

The id of a list associated with an event (required for some events).

 
Suggest Edits

Retrieve a webhook

Retrieve an existing webhook

 
gethttps://:account.api-us1.com/api/3/webhooks/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/webhooks/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/webhooks/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/webhooks/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/webhooks/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/webhooks/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "webhook": {
    "cdate": "2016-01-01T12:00:00-00:00",
    "listid": "0",
    "name": "My hook",
    "url": "http://example.com/my-hook",
    "events": [
      "subscribe",
      "unsubscribe",
      "sent"
    ],
    "sources": [
      "admin",
      "api",
      "system"
    ],
    "links": [],
    "id": "1"
  }
}

Path Params

id
int32
required
 
Suggest Edits

Update a webhook

Update an existing webhook

 
puthttps://:account.api-us1.com/api/3/webhooks/id
{
    "webhook": {
      "names": "My Hook",
      "url": "http://example.com/my-hook",
      "events": [
        "subscribe",
        "unsubscribe",
        "sent"
      ],
      "sources": [
        "public",
        "system"
      ]
    }
}
A binary file was returned

You couldn't be authenticated

{
  "webhook": {
    "cdate": "2016-01-01T12:00:00-00:00",
    "listid": "0",
    "name": "My Hook",
    "url": "http://example.com/my-hook",
    "events": [
      "subscribe",
      "unsubscribe",
      "sent"
    ],
    "sources": [
      "public",
      "system"
    ],
    "links": [],
    "id": "1"
  }
}

Path Params

id
int32
required

The webhook id

Body Params

webhook
object
webhook.name
string

A name (or label) to give the webhook.

webhook.url
string

The URL where the webhook will send the POST request when the event occurs.

webhook.events
array of strings

The The event(s) that will trigger the webhook to fire. that will trigger the webhook to fire.

webhook.sources
array of strings

The source(s) causing an event to occur.

webhook.listid
int32

The id of a list associated with an event (required for some events).

 
Suggest Edits

Delete a webhook

Delete an existing webhook

 
deletehttps://:account.api-us1.com/api/3/webhooks/id
curl --request DELETE \
  --url https:///:account.api-us1.com/api/3/webhooks/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https:///:account.api-us1.com/api/3/webhooks/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/webhooks/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https:///:account.api-us1.com/api/3/webhooks/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/webhooks/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

id
int32
required

The webhook id

 
Suggest Edits

List all webhooks

List all existing webhooks

 
gethttps://:account.api-us1.com/api/3/webhooks
curl --request GET \
  --url https:///:account.api-us1.com/api/3/webhooks
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/webhooks' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/webhooks");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/webhooks"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "webhooks": [
    {
      "cdate": "2016-01-01T12:00:00-00:00",
      "listid": "0",
      "name": "My Hook",
      "url": "http://example.com/my-hook",
      "events": [
        "subscribe",
        "unsubscribe",
        "sent"
      ],
      "sources": [
        "public",
        "system"
      ],
      "links": [],
      "id": "1"
    },
    {
      "cdate": "2016-01-01T12:00:00-00:00",
      "listid": "0",
      "name": "My Hook 2",
      "url": "http://example.com/my-hook-2",
      "events": [
        "subscribe"
      ],
      "sources": [
        "admin"
      ],
      "links": [],
      "id": "2"
    },
  ],
  "meta": {
    "total": "2"
  }
}

Query Params

filters[name]
string

Filter by webhook name

filters[url]
string

Filter by webhook url

filters[listid]
string

Filter by webhook's associated list

 
Suggest Edits

List all webhook events

List all available webhook events

 
gethttps://:account.api-us1.com/api/3/webhook/events
curl --request GET \
  --url https:///:account.api-us1.com/api/3/webhook/events
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/webhook/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/webhook/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/webhook/events");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/webhook/events"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "webhookEvents": [
    "bounce",
    "click",
    "contact_tag_added",
    "contact_tag_removed",
    "deal_add",
    "deal_note_add",
    "deal_pipeline_add",
    "deal_stage_add",
    "deal_task_add",
    "deal_task_complete",
    "deal_tasktype_add",
    "deal_update",
    "forward",
    "list_add",
    "open",
    "reply",
    "sent",
    "share",
    "sms_reply",
    "sms_sent",
    "sms_unsub",
    "subscribe",
    "subscriber_note",
    "unsubscribe",
    "update"
  ],
  "meta": {
    "total": 25
  }
}
 
 
Suggest Edits

Retrieve a branding

Retrieve an existing branding resource

 
gethttps://:account.api-us1.com/api/3/brandings/id
curl --request GET \
  --url https:///:account.api-us1.com/api/3/brandings/id
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/brandings/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/brandings/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/brandings/id");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/brandings/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"branding": {
		"groupid": "3",
		"siteName": "ActiveCampaign Email Marketing",
		"siteLogo": "http:\/\/mysite.com\/logo.jpg",
		"siteLogoSmall": "http:\/\/mysite.com\/logo_small.jpg",
		"headerTextValue": "my custom text header",
		"headerHtmlValue": "<p>my custom HTML header<\/p>",
		"footerTextValue": "my custom text footer",
		"footerHtmlValue": "<p>my custom HTML footer<\/p>",
		"copyright": "1",
		"version": "1",
		"license": "1",
		"links": "1",
		"help": "1",
		"adminTemplateHtm": "",
		"adminTemplateCss": "",
		"publicTemplateHtm": "",
		"publicTemplateCss": "",
		"favicon": null,
		"id": "1"
	}
}

Path Params

id
int32
required
 
Suggest Edits

Update a branding

Update an existing branding resource

 
puthttps://:account.api-us1.com/api/3/brandings/id
curl --request PUT \
  --url https:///:account.api-us1.com/api/3/brandings/1
var request = require("request");

var options = { method: 'PUT',
  url: 'https:///:account.api-us1.com/api/3/brandings/1' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/brandings/1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https:///:account.api-us1.com/api/3/brandings/1");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/brandings/1"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"branding": {
		"groupid": "3",
		"siteName": "ActiveCampaign Email Marketing",
		"siteLogo": "http:\/\/mysite.com\/logo.jpg",
		"siteLogoSmall": "http:\/\/mysite.com\/logo_small.jpg",
		"headerTextValue": "my custom text header",
		"headerHtmlValue": "<p>my custom HTML header<\/p>",
		"footerTextValue": "my custom text footer",
		"footerHtmlValue": "<p>my custom HTML footer<\/p>",
		"copyright": "1",
		"version": "1",
		"license": "1",
		"links": "1",
		"help": "1",
		"adminTemplateHtm": "",
		"adminTemplateCss": "",
		"publicTemplateHtm": "",
		"publicTemplateCss": "",
		"favicon": null,
		"id": "1"
	}
}

Path Params

id
int32
required

Branding ID

Body Params

branding
object
branding.groupid
int32

The group ID. This value will always be 3.

branding.siteName
string

Title of software. Example: 'ActiveCampaign Email Marketing'

branding.siteLogo
string
branding.siteLogoSmall
string

URL of small logo. Small logos appear in the header of the admin panel.

branding.headerTextValue
string

Content of non-removable header. Example: text header content

branding.headerHtmlValue
string

Content of non-removable header. Example:

header content here

branding.footerTextValue
string

Content of non-removeable footer. Example: text footer content

branding.footerHtmlValue
string

Content of non-removeable footer. Example:

footer content here

branding.copyright
boolean

unknown

branding.version
boolean

unknown

branding.license
boolean

unknown

branding.links
boolean

External links. To enable (which is the default) exclude this parameter entirely. To disable (remove our branding), just pass this parameter with any value.

branding.help
string
branding.adminTemplateHtm
string

The actual HTML template (ONLY AVAILABLE FOR CERTAIN PLANS)

branding.adminTemplateCss
string

The actual CSS. Example: test color: green; (ONLY AVAILABLE FOR CERTAIN PLANS)

branding.publicTemplateHtm
string

The actual HTML template (ONLY AVAILABLE FOR CERTAIN PLANS)

branding.publicTemplateCss
string

The actual CSS. Example: test color: green; (ONLY AVAILABLE FOR CERTAIN PLANS)

branding.favicon
string

URL of the favicon.

 
Suggest Edits

List all brandings

List all existing branding resources

 
gethttps://:account.api-us1.com/api/3/brandings
curl --request GET \
  --url https:///:account.api-us1.com/api/3/brandings
var request = require("request");

var options = { method: 'GET',
  url: 'https:///:account.api-us1.com/api/3/brandings' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https:///:account.api-us1.com/api/3/brandings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https:///:account.api-us1.com/api/3/brandings");

xhr.send(data);
import requests

url = "https:///:account.api-us1.com/api/3/brandings"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "brandings": [
    {
		"groupid": "3",
		"siteName": "ActiveCampaign Email Marketing",
		"siteLogo": "http:\/\/mysite.com\/logo.jpg",
		"siteLogoSmall": "http:\/\/mysite.com\/logo_small.jpg",
		"headerTextValue": "my custom text header",
		"headerHtmlValue": "<p>my custom HTML header<\/p>",
		"footerTextValue": "my custom text footer",
		"footerHtmlValue": "<p>my custom HTML footer<\/p>",
		"copyright": "1",
		"version": "1",
		"license": "1",
		"links": "1",
		"help": "1",
		"adminTemplateHtm": "",
		"adminTemplateCss": "",
		"publicTemplateHtm": "",
		"publicTemplateCss": "",
		"favicon": null,
		"id": "1"
    }
  ],
  "meta": {
    "total": "1"
  }
}

Path Params

version
string
required

ActiveCampaign API version

Query Params

api_key
string

ActiveCampaign API key