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-8Content-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": "+44-208-1234567",        "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": "+44-208-1234567",    "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-8Content-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": "+44-208-1234567",    "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-8Content-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": "+44-208-1234567",    "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.+44-208-1234567
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-8Content-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": "+44-208-1234567",    "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-8Content-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": "+44-208-1234567",    "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"  }}