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-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:

If multiple contacts match a set of filters, the request will return an error - 409.
If a single contact matches, then the existing contact is updated
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"  }}

Authentication

Sync API

Search API

Firehose API

Core APIs

Apps

Contacts

JSON format

Retrieve all Contacts

Parameters

Allowed for

Using cURL

Example response

Create a contact

Parameters

Allowed for

Using cURL

Example response

Retrieve a single contact

Parameters

Allowed for

Using cURL

Example response

Update a contact

Parameters

Allowed for

Using cURL

Example response

Delete a contact

Parameters

Allowed for

Using cURL

Example response

Upsert a contact

Parameters

Allowed for

Using cURL

Example response