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.

JSON format

Name	Type	Read Only	Description
id	number	true	The unique identifier of the contact.
creator_id	number	true	The unique identifier of the user the contact was created by.
owner_id	number	false	The unique identifier of the user the contact is currently assigned to.
is_organization	boolean	false	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	false	The unique identifier of the organization the contact belongs to. The field will be set only if the contact is an individual.
parent_organization_id	number	false	The unique identifier of an organization contact that is parent of this organization. The field will be set only if the contact is an organization and has parent.
name	string	false	Name of the contact. Required only if the contact is an organization.
first_name	string	false	First name of the contact.
last_name	string	false	Last name of the contact. Required only if the contact is an individual.
customer_status	string	false	The customer status of the contact. Possible values: none, current, past
prospect_status	string	false	The prospect status of the contact. Possible values: none, current, lost
title	string	false	The contact’s job title.
description	string	false	The contact’s description.
industry	string	false	The contact’s industry.
website	string	false	The contact’s website address.
email	string	false	The contact’s email address.
phone	string	false	The contact’s phone number.
mobile	string	false	The contact’s mobile phone number.
fax	string	false	The contact’s fax number.
twitter	string	false	The contact’s X (formerly Twitter) handle.
facebook	string	false	The contact’s Facebook nickname.
linkedin	string	false	The contact’s Linkedin nickname.
skype	string	false	The contact’s Skype nickname.
address	string	false	The contact’s address. For more information about the address object see Address.
billing_address	string	false	The customers’s billing address. Applicable only if either customer_status or prospect_status is different from none. For more information about the address object see Address.
shipping_address	string	false	The customer’s shipping address. Applicable only if either customer_status or prospect_status is different from none. For more information about the address object see Address.
tags	array	false	An array of tags for the contact. See more at Tags.
custom_fields	object	false	Custom fields are a key-value pair attached to a contact. See more at Custom Fields.
created_at	string	true	Date and time that the contact was created in UTC (ISO8601 format).
updated_at	string	true	Date and time of the last update on the contact in UTC (ISO8601 format).

---

Retrieve all Contacts

GET /v2/contacts

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

Parameters

Name	Required	Type	In	Description
page	false	number	Query	The page number to start from. Page numbering is 1-based and omitting the page parameter will return the first page.
per_page	false	number	Query	The number of records to return per page. Default limit is 25 and 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. To change the sort order to descending, append :desc to the field. Example: sort_by=last_name:desc. Possible values: "id", "name", "first_name", "last_name", "email", "custom_fields", "updated_at", "created_at"
ids	false	string	Query	Comma-separated list of the IDs for the contacts you want to be returned in your request.
creator_id	false	number	Query	User ID. Returns all contacts created by that user.
owner_id	false	number	Query	User ID. Returns all contacts owned by that user.
is_organization	false	boolean	Query	Indicates whether or not this contact refers to an organization or an individual.
contact_id	false	number	Query	The unique identifier of the organization that the contact belongs to.
name	false	string	Query	Name of the contact.
first_name	false	string	Query	First name of the contact.
last_name	false	string	Query	Last name of the contact.
email	false	string	Query	Email address of the contact.
phone	false	string	Query	Phone number of the contact.
mobile	false	string	Query	Mobile phone number of the contact.
customer_status	false	string	Query	Customer status of the contact. Possible values: none, current, past
prospect_status	false	string	Query	Prospect status of the contact. Possible values: none, current, lost
address[city]	false	string	Query	City name.
address[postal_code]	false	string	Query	Zip code or equivalent
address[country]	false	string	Query	Country name.
address[state]	false	string	Query	State/region name.
billing_address	false	Address	Query	null if contact is neither a customer nor a prospect (see customer_status and prospect_status fields for details).
shipping_address	false	Address	Query	null if contact is neither a customer nor a prospect (see customer_status and prospect_status fields for details).
custom_fields	false	string	Query	Filterable custom field. Example: To find contacts 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	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/contacts \
-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,
        "is_organization": true,
        "contact_id": null,
        "parent_organization_id": 2,
        "name": "Design Services Company",
        "first_name": null,
        "last_name": null,
        "customer_status": "none",
        "prospect_status": "none",
        "title": null,
        "description": null,
        "industry": "Design Services",
        "website": "http://www.designservice.com",
        "email": null,
        "phone": null,
        "mobile": null,
        "fax": "[phone]",
        "twitter": null,
        "facebook": null,
        "linkedin": null,
        "skype": null,
        "address": {
          "line1": "2726 Smith Street",
          "city": "Hyannis",
          "postal_code": "02601",
          "state": "MA",
          "country": "US"
        },
        "billing_address": null,
        "shipping_address": null,
        "tags": [
          "important"
        ],
        "custom_fields": {
          "known_via": "tom"
        },
        "created_at": "2014-08-27T16:32:56Z",
        "updated_at": "2014-08-27T16:32:56Z"
      },
      "meta": {
        "type": "contact"
      }
    },
    {
      "data": {
        "id": 2,
        "creator_id": 1,
        "owner_id": 1,
        "is_organization": false,
        "contact_id": 1,
        "parent_organization_id": null,
        "name": "Mark Johnson",
        "first_name": "Mark",
        "last_name": "Johnson",
        "customer_status": "none",
        "prospect_status": "none",
        "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"
        },
        "billing_address": null,
        "shipping_address": null,
        "tags": [
          "important"
        ],
        "custom_fields": {
          "known_via": "tom"
        },
        "created_at": "2014-08-27T16:32:56Z",
        "updated_at": "2014-08-27T16:32:56Z"
      },
      "meta": {
        "type": "contact"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "count": 2,
    "links": {
      "self": "http://api.getbase.com/v2/contacts"
    }
  }
}

---

Create a contact

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

Parameters

Name	Required	Type	In	Description
name	true	string	Body	Required only if the contact is an organization. is_organization is set to true.
first_name	false	string	Body	The field will be set only if the contact is an individual. is_organization is set to false.
last_name	true	string	Body	Required only if the contact is an individual. is_organization is set to false.
owner_id	false	number	Body	Defaults to the unique identifier of the user who created the contact.
is_organization	false	boolean	Body	This value can be set only during creation and cannot be changed later.
contact_id	false	number	Body	The field will be set only if the contact is an individual. is_organization is set to false.
parent_organization_id	false	number	Body	The unique identifier of a contact that should be set as parent for this organization. Referenced contact also has to be an organization. It can be set only for organization contacts (is_organization set to true.
customer_status	false	string	Body	e.g. none
prospect_status	false	string	Body	e.g. current
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	e.g. mjohnson
linkedin	false	string	Body	e.g. mjohnson
skype	false	string	Body	e.g. mjohnson
address	false	address	Body
billing_address	false	Address	Body	null if contact is neither a customer nor a prospect (see customer_status and prospect_status fields for details).
shipping_address	false	Address	Body	null if contact is neither a customer nor a prospect (see customer_status and prospect_status fields for details).
tags	false	array	Body	In order to modify this, you need to supply the entire set.
custom_fields	false	object	Body	e.g. {"known_via": "tom"}

Allowed for

• Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/contacts \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "contact_id": 1,
    "name": "Mark Johnson",
    "first_name": "Mark",
    "last_name": "Johnson",
    "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": [
      "contractor",
      "early-adopter"
    ],
    "custom_fields": {
      "referral_website": "http://www.example.com"
    }
  }
}'

Example response

HTTP/1.1 200 OK

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

{
  "data": {
    "id": 2,
    "creator_id": 1,
    "owner_id": 1,
    "is_organization": false,
    "contact_id": 1,
    "parent_organization_id": null,
    "name": "Mark Johnson",
    "first_name": "Mark",
    "last_name": "Johnson",
    "customer_status": "none",
    "prospect_status": "none",
    "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"
    },
    "billing_address": null,
    "shipping_address": null,
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "contact"
  }
}

---

Retrieve a single contact

GET /v2/contacts/:id

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

Name	Required	Type	In	Description
id	true	number	Query	The unique identifier of the contact.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/contacts/2 \
-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": 2,
    "creator_id": 1,
    "owner_id": 1,
    "is_organization": false,
    "contact_id": 1,
    "parent_organization_id": null,
    "name": "Mark Johnson",
    "first_name": "Mark",
    "last_name": "Johnson",
    "customer_status": "none",
    "prospect_status": "none",
    "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"
    },
    "billing_address": null,
    "shipping_address": null,
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "contact"
  }
}

---

Update a contact

PUT /v2/contacts/:id

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

Name	Required	Type	In	Description
id	true	number	Query	The unique identifier of the contact.
name	false	string	Body	This field will be set only if the contact is an organization. is_organization is set to true.
first_name	false	string	Body	The field will be set only if the contact is an individual. is_organization is set to false.
last_name	false	string	Body	The field will be set only if the contact is an individual. is_organization is set to false.
contact_id	false	number	Body	The field will be set only if the contact is an individual. is_organization is set to false.
parent_organization_id	false	number	Body	The unique identifier of a contact that should be set as parent for this organization. Setting this to null will clear existing parent relation. Referenced contact also has to be an organization. It can be set only for organization contacts (is_organization set to true.
owner_id	false	number	Body	e.g. 1
customer_status	false	string	Body	e.g. none
prospect_status	false	string	Body	e.g. current
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	e.g. mjohnson
linkedin	false	string	Body	e.g. mjohnson
skype	false	string	Body	e.g. mjohnson
address	false	address	Body
billing_address	false	Address	Body	Can be updated if contact is either a customer or a prospect (see customer_status and prospect_status fields for details).
shipping_address	false	Address	Body	Can be updated if contact is either a customer or a prospect (see customer_status and prospect_status fields for details).
tags	false	array	Body	In order to modify this, you need to supply the entire set.
custom_fields	false	object	Body	e.g. `{"known_via": "tom"}

Allowed for

• Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/contacts/2 \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "customer_status": "current",
    "tags": [
      "contractor",
      "early-adopter"
    ],
    "custom_fields": {
      "referral_website": "http://www.example.com"
    }
  }
}'

Example response

HTTP/1.1 200 OK

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

{
  "data": {
    "id": 2,
    "creator_id": 1,
    "owner_id": 1,
    "is_organization": false,
    "contact_id": 1,
    "parent_organization_id": null,
    "name": "Mark Johnson",
    "first_name": "Mark",
    "last_name": "Johnson",
    "customer_status": "current",
    "prospect_status": "none",
    "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"
    },
    "billing_address": {
      "line1": "2726 Smith Street",
      "city": "Hyannis",
      "postal_code": "02601",
      "state": "MA",
      "country": "US"
    },
    "shipping_address": {
      "line1": null,
      "city": null,
      "postal_code": null,
      "state": null,
      "country": null
    },
    "tags": [
      "contractor",
      "early-adopter"
    ],
    "custom_fields": {
      "referral_website": "http://www.example.com"
    },
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "contact"
  }
}

---

Delete a contact

DELETE /v2/contacts/:id

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

Parameters

Name	Required	Type	In	Description
id	true	number	Query	The unique identifier of the contact.

Allowed for

• Agents

Using cURL

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

Example response

HTTP/1.1 204 No Content

---

Upsert a contact

POST /v2/contacts/upsert

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 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 contacts created by that user.
owner_id	false	number	Body	User ID. Returns all contacts owned by that user.
is_organization	false	boolean	Body	Indicates whether or not this contact refers to an organization or an individual.
contact_id	false	number	Body	The unique identifier of the organization that the contact belongs to.
parent_organization_id	false	number	Body	The unique identifier of a contact that should be set as parent for this organization. Setting this to null will clear existing parent relation. Referenced contact also has to be an organization. It can be set only for organization contacts (is_organization set to true.
name	false	string	Body	Name of the contact.
first_name	false	string	Body	First name of the contact.
last_name	false	string	Body	Last name of the contact.
email	false	string	Body	Email address of the contact.
phone	false	string	Body	Phone number of the contact.
mobile	false	string	Body	Mobile phone number of the contact.
customer_status	false	string	Body	Customer status of the contact. Possible values: none, current, past
prospect_status	false	string	Body	Prospect status of the contact. Possible values: none, current, lost
address[city]	false	string	Body	City name.
address[postal_code]	false	string	Body	Zip code or equivalent
address[country]	false	string	Body	Country name.
billing_address	false	Address	Body	Can be updated if contact is either a customer or a prospect (see customer_status and prospect_status fields for details).
shipping_address	false	Address	Body	Can be updated if contact is either a customer or a prospect (see customer_status and prospect_status fields for details).
custom_fields	false	string	Body	Filterable custom field. Example: To perform upsert on a contact with a custom field named "external_id" that has 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/contacts/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": 2,
    "creator_id": 1,
    "owner_id": 1,
    "is_organization": false,
    "contact_id": 1,
    "parent_organization_id": null,
    "name": "Mark Johnson",
    "first_name": "Mark",
    "last_name": "Johnson",
    "customer_status": "none",
    "prospect_status": "none",
    "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"
    },
    "billing_address": null,
    "shipping_address": null,
    "tags": [
      "contractor",
      "early-adopter"
    ],
    "custom_fields": {
      "external_id": "SKU01",
      "referral_website": "http://www.example.com"
    },
    "created_at": "2015-07-16T17:14:16Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "contact"
  }
}