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-8Content-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": "+44-208-1234567",        "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": "+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"        },        "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. +44-208-1234567
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": "+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": [      "contractor",      "early-adopter"    ],    "custom_fields": {      "referral_website": "http://www.example.com"    }  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-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": "+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"    },    "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-8Content-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": "+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"    },    "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. +44-208-1234567
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-8Content-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": "+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"    },    "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-8Content-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": "+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"    },    "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"  }}