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.

Properties

Attribute Description
id number readonly

Unique identifier of the lead.
creator_id number readonly

Unique identifier of the user who created the lead.
owner_id number

Unique identifier of the user who currently owns the lead.
first_name string

First name of the lead.
last_name string

Last name of the lead. Required unless organization_name field is provided.
organization_name string

Organization name of the lead. Required unless last_name field is provided.
status string

Status of the lead.
source_id number

Unique identifier of the Source.
title string

Job title of the lead.
description string

Lead description.
industry string

Organization’s industry.
website string

Lead’s website.
email string

Lead’s email.
phone string

Lead’s phone number.
mobile string

Lead’s mobile phone number.
fax string

Lead’s fax number.
twitter string

Lead’s Twitter handle.
facebook string

Lead’s Facebook nickname.
linkedin string

Lead’s Linkedin nickname.
skype string

Lead’s Skype nickname.
address Address

The lead’s address. For more information about address object see Address.
tags array

An array of tags for a lead. See more at Tags.
custom_fields 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 string readonly

Date and time of the creation in UTC (ISO8601 format).
updated_at string readonly

Date and time of the last update in UTC (ISO8601 format).

Endpoints

Retrieve all leads

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

Parameters

Attribute Description
page number optional

Page number to start from. Page numbering starts at 1 and omitting the page parameter will return the first page.

e.g. ?page=2
per_page number optional

Number of records to return per page. The default limit is 25 and the maximum number that can be returned is 100.

e.g. ?per_page=20
sort_by string optional

A field to sort by. You can sort by filterable custom fields as well, e.g. to filter by external id use ?sort_by=custom_fields:external_id (supported custom field types are: Number, Single Line Text, Dropdown, Multi Select). Default ordering is ascending. If you want to change the sort order to descending, append :desc to the field e.g. sort_by=last_name:desc.

Possible values:

  • id
  • first_name
  • last_name
  • organization_name
  • email
  • custom_fields
  • created_at
  • updated_at
e.g. ?sort_by=created_at
ids string optional

Comma-separated list of lead IDs to be returned in a request.

e.g. ?ids=1,2,3
creator_id number optional

User ID. Returns all leads created by that user.

e.g. ?creator_id=1
owner_id number optional

User ID. Returns all leads owned by that user.

e.g. ?owner_id=1
source_id number optional

Id of the Source.

e.g. ?source_id=10
first_name string optional

First name of the lead.

e.g. ?first_name=Mark
last_name string optional

Last name of the lead.

e.g. ?last_name=Johnson
organization_name string optional

Organization name of the lead.

e.g. ?organization_name=Design%20Services%20Company
status string optional

Status of the lead.

e.g. ?status=unqualified
email string optional

Email address of the lead.

e.g. ?email=mark@designservices.com
phone string optional

Phone number of the lead.

e.g. ?phone=508-778-6516
mobile string optional

Mobile phone number of the lead.

e.g. ?mobile=508-778-6516
address[city] string optional

City name.

e.g. ?address[city]=Hyannis
address[postal_code] string optional

Zip or Postal code

e.g. ?address[postal_code]=02601
address[state] string optional

State/region name.

e.g. ?address[state]=CA
address[country] string optional

Country name.

e.g. ?address[country]=United%20States
custom_fields string optional

Filterable custom field e.g. ?custom_fields[external_id]=SKU01 (supported custom field types are: Number, Single Line Text, Dropdown, Multi Select). Custom fields must be defined and have Filterable property assigned.
inclusive boolean optional

Indicates how filters should be combine. true value, the default, uses AND logic. false value uses OR logic to combine filters.

e.g. ?inclusive=true

Create a lead

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

Parameters

Attribute Description
last_name string required

Required only if a lead is an individual. company_name is empty.

e.g. "last_name": "Johnson"
organization_name string required

Required only if a lead is an organization. last_name is empty.

e.g. "organization_name": "Design Services Company"
first_name string optional
e.g. "first_name": "Mark"
owner_id number optional

Defaults to user’s unique identifier the lead is created by.

e.g. "owner_id": "1"
status string optional
e.g. "status": "New"
source_id number optional
e.g. "source_id": "10"
unqualified_reason_id number optional
e.g. "unqualified_reason_id": "10"
title string optional
e.g. "title": "CEO"
description string optional
e.g. "description": "I know him via Tom"
industry string optional
e.g. "industry": "Design Services"
website string optional
e.g. "website": "www.designservices.com"
email string optional
e.g. "email": "mark@designservices.com"
phone string optional
e.g. "phone": "508-778-6516"
mobile string optional
e.g. "mobile": "508-778-6516"
fax string optional
e.g. "fax": "+44-208-1234567"
twitter string optional
e.g. "twitter": "mjohnson"
facebook string optional
e.g. "facebook": "mjohnson"
linkedin string optional
e.g. "linkedin": "mjohnson"
skype string optional
e.g. "skype": "mjohnson"
address Address optional
tags array optional
e.g. "tags": ["important"]
custom_fields object optional
e.g. "custom_fields": {"known_via": "tom"}

Retrieve a single lead

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

Attribute Description
id number required

Unique identifier of the lead.

Update a lead

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

Attribute Description
id number required

Unique identifier of the lead.
owner_id number optional
e.g. "owner_id": "1"
first_name string optional
e.g. "first_name": "Mark"
last_name string optional
e.g. "last_name": "Johnson"
organization_name string optional
e.g. "organization_name": "Design Services Company"
status string optional
e.g. "status": "Unqualified"
source_id number optional
e.g. "source_id": "10"
unqualified_reason_id number optional
e.g. "unqualified_reason_id": "10"
title string optional
e.g. "title": "CEO"
description string optional
e.g. "description": "I know him via Tom"
industry string optional
e.g. "industry": "Design Services"
website string optional
e.g. "website": "www.designservices.com"
email string optional
e.g. "email": "mark@designservices.com"
phone string optional
e.g. "phone": "508-778-6516"
mobile string optional
e.g. "mobile": "508-778-6516"
fax string optional
e.g. "fax": "+44-208-1234567"
twitter string optional
e.g. "twitter": "mjohnson"
facebook string optional
e.g. "facebook": "mjohnson"
linkedin string optional
e.g. "linkedin": "mjohnson"
skype string optional
e.g. "skype": "mjohnson"
address Address optional
tags array optional

In order to modify, you need to supply the entire set.

e.g. "tags": ["important"]
custom_fields object optional
e.g. "custom_fields": {"known_via": "tom"}

Delete a lead

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

Parameters

Attribute Description
id number required

Unique identifier of the lead.

Upsert a lead

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 Base to carry external system ids - stored as custom fields.

Parameters

Attribute Description
creator_id number optional

User ID. Returns all leads created by that user.

e.g. "creator_id": "1"
owner_id number optional

User ID. Returns all leads owned by that user.

e.g. "owner_id": "1"
source_id number optional

Id of the Source.

e.g. "source_id": "10"
first_name string optional

First name of the lead.

e.g. "first_name": "Mark"
last_name string optional

Last name of the lead.

e.g. "last_name": "Johnson"
organization_name string optional

Organization name of the lead.

e.g. "organization_name": "Design Services Company"
status string optional

Status of the lead.

e.g. "status": "unqualified"
email string optional

Email address of the lead.

e.g. "email": "mark@designservices.com"
phone string optional

Phone number of the lead.

e.g. "phone": "508-778-6516"
mobile string optional

Mobile phone number of the lead.

e.g. "mobile": "508-778-6516"
address[city] string optional

City name.

e.g. "address[city]": "Hyannis"
address[postal_code] string optional

Zip or Postal code

e.g. "address[postal_code]": "02601"
address[country] string optional

Country name.

e.g. "address[country]": "United States"
custom_fields string optional

Filterable custom field e.g. ?custom_fields[external_id]=SKU01. Custom fields must be defined and have Filterable property assigned (supported custom field types are: Number, Single Line Text, Dropdown, Multi Select).
inclusive boolean optional

Indicates how filters should be combine. true value, the default, uses AND logic. false value uses OR logic to combine filters.

e.g. "inclusive": "true"