Search for contacts | Contacts API

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing & CRM

Required Scope:

crm.objects.contacts.read

This endpoint is used to get contacts by email address, first and last name, phone number, or company.

Use case for this endpoint: Let's say you need to do some basic deduplication of your contacts. You can do so using this endpoint by searching for contacts with the same phone number or first and last name.

Response details

This method only returns a small subset of data about the contact. However, the returned data will include the contact ID (vid), which you can use to look up more data about that particular contact.

Required parameters	How to use	Description
OAuth access token or private app access token	Authorization: Bearer {token} header	Used to authenticate the request. Please see this page for more details about authentication.
Search query	&q= - Used in the request URL	The search term for what you're searching for. You can use all of a word or just parts of a word as well. For example, if you we're searching for contacts with "hubspot" in their name or email, searching for "hub" would also return contacts with "hubspot" in their email address.

Optional parameters	How to use	Description
Count	&count=X - Used in the request URL	This parameter lets you specify the amount of contacts to return in your API call. The default for this parameter (if it isn't specified) is 20 contacts. The maximum amount of contacts you can have returned to you via this parameter is 100.
Offset	&offset=X - Used in the request URL	This parameter is used to page through the results. Every call to this endpoint will return an offset value. This value is used in the offset= parameter of the next call to get the next page of contacts.
Property	&property=X - Used in the request URL	If you include the "property" parameter, then the properties in the "contact" object in the returned data will only include the property or properties that you request.
Sort	&sort=X - Used in the request URL	This parameter takes in an internal property name (e.g. vid) and sorts contact search results by that field.
Order	&order=X - Used in the request URL	This parameter accepts "DESC" or "ASC" as values (defaults to "DESC") to order results by the property specified in "sort" parameter. As such, this parameter will only work when used in conjunction with "sort".

Example URL: https://api.hubapi.com/contacts/v1/search/query?q=testingapis

JSON

Developers

Search for contacts by email, name, phone number, or company

GET /contacts/v1/search/query

Method Details

Response details

About

Jobs

Learn Inbound

Support

Locations