Leads

The Leads API provides a simple interface to manage leads. A lead represents an individual or an organization that expresses interest in your goods or services. You can assign an organization to an individual via organization_name field.

The API allows you to create, read, delete and update your leads. You can retrieve individual leads, as well as list of all leads.

Name	Read Only	Type	Description
id	true	number	Unique identifier of the lead.
creator_id	true	number	Unique identifier of the user who created the lead.
owner_id	false	number	Unique identifier of the user who currently owns the lead.
first_name	false	string	First name of the lead.
last_name	false	string	Last name of the lead. Required unless organization_name field is provided.
organization_name	false	string	Organization name of the lead. Required unless last_name field is provided.
status	false	string	Status of the lead.
source_id	false	number	Unique identifier of the Source.
title	false	string	Job title of the lead.
description	false	string	Lead description.
industry	false	string	Organization's industry.
website	false	string	Lead's website.
email	false	string	Lead's email.
phone	false	string	Lead's phone number.
mobile	false	string	Lead's mobile phone number.
fax	false	string	Lead's fax number.
twitter	false	string	Lead's X (formerly Twitter) handle.
facebook	false	string	Lead's Facebook nickname.
linkedin	false	string	Lead's Linkedin nickname.
skype	false	string	Lead's Skype nickname.
address	false	Address	The lead's address. For more information about address object see Address.
tags	false	array	An array of tags for a lead. See more at Tags.
custom_fields	false	object	Custom fields are a either a single key-value pair attached to a lead or a set of key-value pairs attached to a lead. See more at Custom Fields.
created_at	true	string	Date and time of the creation in UTC (ISO8601 format).
updated_at	true	string	Date and time of the last update in UTC (ISO8601 format).

Retrieve all leads

GET /v2/leads

Returns all leads available to the user, according to the parameters provided.

Parameters

Name	Required	Type	In	Description
page	false	number	Query	Page number to start from. Page numbering starts at 1 and omitting the page parameter will return the first page.
per_page	false	number	Query	Number of records to return per page. The default limit is 25 and the maximum number that can be returned is 100.
sort_by	false	string	Query	A field to sort by. You can sort by filterable custom fields as well. Example: To sort by a custom field named "external_id", use ?sort_by=custom_fields:external_id. Supported custom field types: Number, Single Line Text, Dropdown, Multi Select). The default ordering is ascending. If you want to change the sort order to descending, append :desc to the field. Example: sort_by=last_name:desc. Possible values: "id", "first_name", "last_name", "organization_name", "email", "custom_fields", "created_at", "updated_at"
ids	false	string	Query	Comma-separated list of lead IDs to be returned in a request.
creator_id	false	number	Query	User ID. Returns all leads created by that user.
owner_id	false	number	Query	User ID. Returns all leads owned by that user.
source_id	false	number	Query	Id of the Source.
first_name	false	string	Query	First name of the lead.
last_name	false	string	Query	Last name of the lead.
organization_name	false	string	Query	Organization name of the lead.
status	false	string	Query	Status of the lead.
email	false	string	Query	Email address of the lead.
phone	false	string	Query	Phone number of the lead.
mobile	false	string	Query	Mobile phone number of the lead.
address[city]	false	string	Query	City name.
address[postal_code]	false	string	Query	Zip or Postal code
address[state]	false	string	Query	State/region name.
address[country]	false	string	Query	Country name.
custom_fields	false	string	Query	Filterable custom field. Example: To find leads with a custom field named "external_id" with a value of "SKU01", use the following: ?custom_fields[external_id]=SKU01. Supported custom field types: Number, Single Line Text, Dropdown, Multi Select. Custom fields must be defined and have a Filterable property assigned to them.
inclusive	optional	boolean	Query	Indicates how filters should be combine. true value, the default, uses AND logic. false value uses OR logic to combine filters.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/leads \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "items": [
    {
      "data": {
        "id": 1,
        "creator_id": 1,
        "owner_id": 1,
        "first_name": "Mark",
        "last_name": "Johnson",
        "organization_name": "Design Services Company",
        "status": "New",
        "source_id": 10,
        "title": "CEO",
        "description": "I know him via Tom",
        "industry": "Design Services",
        "website": "http://www.designservice.com",
        "email": "[email protected]",
        "phone": "508-778-6516",
        "mobile": "508-778-6516",
        "fax": "[phone]",
        "twitter": "mjohnson",
        "facebook": "mjohnson",
        "linkedin": "mjohnson",
        "skype": "mjohnson",
        "address": {
          "line1": "2726 Smith Street",
          "city": "Hyannis",
          "postal_code": "02601",
          "state": "MA",
          "country": "US"
        },
        "tags": [
          "important"
        ],
        "custom_fields": {
          "known_via": "tom"
        },
        "created_at": "2014-08-27T16:32:56Z",
        "updated_at": "2014-08-27T16:32:56Z"
      },
      "meta": {
        "type": "lead"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "count": 1,
    "links": {
      "self": "http://api.getbase.com/v2/leads.json"
    }
  }
}

---

Create a lead

POST /v2/leads

Creates a new lead. A lead may represent a single individual or an organization.

Parameters

Name	Required	Type	In	Description
last_name	true	string	Body	Required only if a lead is an individual. company_name is empty.
organization_name	true	string	Body	Required only if a lead is an organization. last_name is empty.
first_name	false	string	Body
owner_id	false	number	Body	Defaults to user's unique identifier the lead is created by.
status	false	string	Body
source_id	false	number	Body
unqualified_reason_id	false	number	Body
title	false	string	Body
description	false	string	Body
industry	false	string	Body
website	false	string	Body
email	false	string	Body
phone	false	string	Body
mobile	false	string	Body
fax	false	string	Body
twitter	false	string	Body
facebook	false	string	Body
linkedin	false	string	Body
skype	false	string	Body
address	false	Address	Body
tags	false	array	Body	Example: ["important"]
custom_fields	false	object	Body	Example: {"known_via": "tom"}. See Custom Fields.

Allowed for

• Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/leads \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "first_name": "Mark",
    "last_name": "Johnson",
    "organization_name": "Design Services Company",
    "source_id": 10,
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "website": "http://www.designservice.com",
    "email": "[email protected]",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "[phone]",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": {
      "line1": "2726 Smith Street",
      "city": "Hyannis",
      "postal_code": "02601",
      "state": "MA",
      "country": "US"
    },
    "tags": [
      "important"
    ],
    "custom_fields": {
      "known_via": "tom"
    }
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "first_name": "Mark",
    "last_name": "Johnson",
    "organization_name": "Design Services Company",
    "status": "New",
    "source_id": 10,
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "website": "http://www.designservice.com",
    "email": "[email protected]",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "[phone]",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": {
      "line1": "2726 Smith Street",
      "city": "Hyannis",
      "postal_code": "02601",
      "state": "MA",
      "country": "US"
    },
    "tags": [
      "important"
    ],
    "custom_fields": {
      "known_via": "tom"
    },
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "lead"
  }
}

---

Retrieve a single lead [GET]

GET /v2/leads/:id

Returns a single lead available to the user, according to the unique lead ID provided. If the specified lead does not exist, this query returns an error.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the lead.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/leads/1 \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "first_name": "Mark",
    "last_name": "Johnson",
    "organization_name": "Design Services Company",
    "status": "New",
    "source_id": 10,
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "website": "http://www.designservice.com",
    "email": "[email protected]",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "[phone]",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": {
      "line1": "2726 Smith Street",
      "city": "Hyannis",
      "postal_code": "02601",
      "state": "MA",
      "country": "US"
    },
    "tags": [
      "important"
    ],
    "custom_fields": {
      "known_via": "tom"
    },
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "lead"
  }
}

---

Update a lead

PUT /v2/leads/:id

Updates lead information. If the specified lead does not exist, this query returns an error.

In order to modify tags, you need to supply the entire set of tags. tags are replaced every time they are used in a request.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the lead.
owner_id	false	number	Body
first_name	false	string	Body	e.g.Mark
last_name	false	string	Body	e.g.Johnson
organization_name	false	string	Body	e.g.Design Services Company
status	false	string	Body	e.g.Unqualified
source_id	false	number	Body
unqualified_reason_id	false	number	Body
title	false	string	Body	e.g.CEO
description	false	string	Body	e.g.I know him via Tom
industry	false	string	Body	e.g.Design Services
website	false	string	Body	e.g.www.designservices.com
email	false	string	Body	e.g.[email protected]
phone	false	string	Body	e.g.508-778-6516
mobile	false	string	Body	e.g.508-778-6516
fax	false	string	Body	e.g.[phone]
twitter	false	string	Body	e.g.mjohnson
facebook	false	string	Body	mjohnson
linkedin	false	string	Body	e.g. mjohnson
skype	false	string	Body	e.g. mjohnson
address	false	Address	Body
tags	false	array	Body	To modify the list, you must supply the entire updated list. Example: ["important"]
custom_fields	false	object	Body	Example: {"known_via": "tom"}. See Custom Fields.

Allowed for

• Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/leads/:id \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "tags": [
      "important",
      "friend"
    ]
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "first_name": "Mark",
    "last_name": "Johnson",
    "organization_name": "Design Services Company",
    "status": "New",
    "source_id": 10,
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "website": "http://www.designservice.com",
    "email": "[email protected]",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "[phone]",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": {
      "line1": "2726 Smith Street",
      "city": "Hyannis",
      "postal_code": "02601",
      "state": "MA",
      "country": "US"
    },
    "tags": [
      "important",
      "friend"
    ],
    "custom_fields": {
      "known_via": "tom"
    },
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "lead"
  }
}

---

Delete a lead

DELETE /v2/leads/:id

Delete an existing lead. If the specified lead does not exist, this query returns an error. This operation cannot be undone.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the lead.

Allowed for

• Agents

Using cURL

curl -v -X DELETE https://api.getbase.com/v2/leads/1 \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 204 No Content

---

Upsert a lead

POST /v2/leads/upsert

Create a new lead or update an existing, based on a value of a filter or a set of filters. At least a single filter - query parameter - is required. If no parameters are present, the request will return an error.

Behaviour:

1. If multiple leads match a set of filters, the request will return an error - 409.
2. If a single lead matches, then the existing lead is updated
3. If none matches the query, a new lead is created

Notice Use Upsert API, instead of Create or Update, to avoid creating unwanted, duplicated records. Also very useful if you want Sell to carry external system ids - stored as custom fields.

Parameters

Name	Required	Type	In	Description
creator_id	false	number	Body	User ID. Returns all leads created by that user.
owner_id	false	number	Body	User ID. Returns all leads owned by that user.
source_id	false	number	Body	Id of the Source.
first_name	false	string	Body	First name of the lead.
last_name	false	string	Body	Last name of the lead.
organization_name	false	string	Body	Organization name of the lead.
status	false	string	Body	Status of the lead.
email	false	string	Body	Email address of the lead.
phone	false	string	Body	Phone number of the lead.
mobile	false	string	Body	Mobile phone number of the lead.
address[city]	false	string	Body	City name.
address[postal_code]	false	string	Body	Zip or Postal code
address[country]	false	string	Body	Country name.
custom_fields	false	string	Body	Filterable custom field. Example: To perform an upsert on a lead with a custom field named "external_id" with a value of "SKU01", use the following: ?custom_fields[external_id]=SKU01. Custom fields must be defined and have a Filterable property assigned to them. Supported custom field types: Number, Single Line Text, Dropdown, Multi Select.
inclusive	false	boolean	Body	Indicates how filters should be combine. true value, the default, uses AND logic. false value uses OR logic to combine filters.

Allowed for

• Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/leads/upsert?custom_fields[external_id]=SKU01 \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "address": {
      "line1": "494 Oak Lane"
    },
    "custom_fields": {
      "external_id": "SKU01"
    }
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "first_name": "Mark",
    "last_name": "Johnson",
    "organization_name": "Design Services Company",
    "status": "New",
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "website": "http://www.designservice.com",
    "email": "[email protected]",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "[phone]",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": {
      "line1": "494 Oak Lane",
      "city": "Hyannis",
      "postal_code": "02601",
      "state": "MA",
      "country": "US"
    },
    "tags": [
      "important"
    ],
    "custom_fields": {
      "external_id": "SKU01",
      "known_via": "tom"
    },
    "created_at": "2015-07-16T17:14:16Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "lead"
  }
}

---