Contacts

The Contacts API provides a simple interface to manage your contacts. A contact represents an individual (e.g. Mark Johnson) or an organization (e.g. Google). Each contact has two status fields: customer_status and prospect_status. They describe the contact’s relationship to your business.

Types of contacts:

  • Regular Contact - a person or an organization you know, but with whom you have not initiated a business relationship yet.

  • Current Prospect - a person or an organization that you are actively selling to.

  • Lost Prospect - a person or an organization that you have tried to sell to in the past, but were unable to complete a deal. Lost prospects have never been customers before.

  • Current Customer - a person or an organization that currently buys goods or services from your business.

  • Past Customer - a person or an organization that previously bought goods or services from your business, but no longer does so.

You can assign any number of tags and custom fields to a contact. Tags do not need to already exist to be assigned; they will be created if necessary.

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

Properties

Attribute Description
id number readonly

The unique identifier of the contact.

creator_id number readonly

The unique identifier of the user the contact was created by.

owner_id number

The unique identifier of the user the contact is currently assigned to.

is_organization boolean

Indicator of whether or not this contact refers to an organization or an individual. This value can be set only during creation and cannot be changed later. The default value is false.

contact_id number

The unique identifier of the organization the contact belongs to. The field will be set only if the contact is an individual.

name string

Name of the contact. Required only if the contact is an organization.

first_name string

First name of the contact.

last_name string

Last name of the contact. Required only if the contact is an individual.

customer_status string

The customer status of the contact.

Possible values:

  • none
  • current
  • past
prospect_status string

The prospect status of the contact.

Possible values:

  • none
  • current
  • lost
title string

The contact’s job title.

description string

The contact’s description.

industry string

The contact’s industry.

website string

The contact’s website address.

email string

The contact’s email address.

phone string

The contact’s phone number.

mobile string

The contact’s mobile phone number.

fax string

The contact’s fax number.

twitter string

The contact’s Twitter handle.

facebook string

The contact’s Facebook nickname.

linkedin string

The contact’s Linkedin nickname.

skype string

The contact’s Skype nickname.

address Address

The contact’s address. For more information about the address object see Address.

tags array

An array of tags for the contact. See more at Tags.

custom_fields object

Custom fields are a key-value pair attached to a contact. See more at Custom Fields.

created_at string readonly

Date and time that the record was created in UTC ISO8601 format.

updated_at string readonly

Date and time of the record’s last update in UTC ISO8601 format.


Endpoints


Retrieve all contacts

Returns all contacts available to the user according to the parameters provided.

Parameters

Attribute Description
page number optional

The page number to start from. Page numbering is 1-based and omitting the page parameter will return the first page.

e.g. ?page=2
per_page number optional

The number of records to return per page. Default limit is 25 and 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. 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
  • name
  • first_name
  • last_name
  • email
  • custom_fields
  • updated_at
  • created_at
e.g. ?sort_by=created_at
ids string optional

Comma-separated list of the IDs for the contacts you want to be returned in your request.

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

User ID. Returns all contacts created by that user.

e.g. ?creator_id=1
owner_id number optional

User ID. Returns all contacts owned by that user.

e.g. ?owner_id=1
is_organization boolean optional

Indicates whether or not this contact refers to an organization or an individual.

e.g. ?is_organization=true
contact_id number optional

The unique identifier of the organization that the contact belongs to.

e.g. ?contact_id=1
name string optional

Name of the contact.

e.g. ?name=Design%20Services%20Company
first_name string optional

First name of the contact.

e.g. ?first_name=Mark
last_name string optional

Last name of the contact.

e.g. ?last_name=Johnson
email string optional

Email address of the contact.

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

Phone number of the contact.

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

Mobile phone number of the contact.

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

Customer status of the contact.

e.g. ?customer_status=none
prospect_status string optional

Prospect status of the contact.

e.g. ?prospect_status=current
address[city] string optional

City name.

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

Zip code or equivalent

e.g. ?address[postal_code]=MA
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. Custom fields must be defined and have Filterable property asigned.


Create a contact

Create a new contact. A contact may represent a single individual or an organization.

Parameters

Attribute Description
name string required

Required only if the contact is an organization. is_organization is set to true.

e.g. "name": "Design Services Company"
first_name string required

Required only if the contact is an individual. is_organization is set to false.

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

Required only if the contact is an individual. is_organization is set to false.

e.g. "last_name": "Johnson"
owner_id number optional

Defaults to the unique identifier of the user who created the contact.

e.g. "owner_id": "1"
is_organization boolean optional

This value can be set only during creation and cannot be changed later.

e.g. "is_organization": "false"
contact_id number optional

The field will be set only if the contact is an individual. is_organization is set to false.

e.g. "contact_id": "1"
customer_status string optional
e.g. "customer_status": "none"
prospect_status string optional
e.g. "prospect_status": "current"
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 this, you need to supply the entire set.

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

Retrieve a single contact

Returns a single contact available to the user, according to the unique contact ID provided. If the specified contact does not exist, the request will return an error.

Parameters

Attribute Description
id number required

The unique identifier of the contact.


Update a contact

Updates contact information. If the specified contact does not exist, the request will return an error.

Notice When updating contact tags, you need to provide all tags. Any missing tag will be removed from a contact’s tags.

Parameters

Attribute Description
id number required

The unique identifier of the contact.

name string optional

This field will be set only if the contact is an organization. is_organization is set to true.

e.g. "name": "Design Services Company"
first_name string optional

The field will be set only if the contact is an individual. is_organization is set to false.

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

The field will be set only if the contact is an individual. is_organization is set to false.

e.g. "last_name": "Johnson"
contact_id number optional

The field will be set only if the contact is an individual. is_organization is set to false.

e.g. "contact_id": "1"
owner_id number optional
e.g. "owner_id": "1"
customer_status string optional
e.g. "customer_status": "none"
prospect_status string optional
e.g. "prospect_status": "current"
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 this, you need to supply the entire set.

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

Delete a contact

Delete an existing contact. If the specified contact does not exist, the request will return an error. This operation cannot be undone.

Parameters

Attribute Description
id number required

The unique identifier of the contact.


Upsert a contact

Create a new contact 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 contacts match a set of filters, the request will return an error - 409.

  2. If a single contact matches, then the existing contact is updated

  3. If none matches the query, a new contact 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 contacts created by that user.

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

User ID. Returns all contacts owned by that user.

e.g. "owner_id": "1"
is_organization boolean optional

Indicates whether or not this contact refers to an organization or an individual.

e.g. "is_organization": "true"
contact_id number optional

The unique identifier of the organization that the contact belongs to.

e.g. "contact_id": "1"
name string optional

Name of the contact.

e.g. "name": "Design Services Company"
first_name string optional

First name of the contact.

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

Last name of the contact.

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

Email address of the contact.

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

Phone number of the contact.

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

Mobile phone number of the contact.

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

Customer status of the contact.

e.g. "customer_status": "none"
prospect_status string optional

Prospect status of the contact.

e.g. "prospect_status": "current"
address[city] string optional

City name.

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

Zip code or equivalent

e.g. "address[postal_code]": "MA"
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 asigned.