HubSpot/HubSpot_Search_contacts.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d5d6f3cc-2668-4d3c-ad49-63a3fc63455a",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "<img width=\"8%\" alt=\"HubSpot.png\" src=\"https://raw.githubusercontent.com/jupyter-naas/awesome-notebooks/master/.github/assets/logos/HubSpot.png\" style=\"border-radius: 15%\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8978178-7f09-417e-9f0a-3918a4d374b4",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "# HubSpot - Search contacts\n",
    "<a href=\"https://bit.ly/3JyWIk6\">Give Feedback</a> | <a href=\"https://github.com/jupyter-naas/awesome-notebooks/issues/new?assignees=&labels=bug&template=bug_report.md&title=HubSpot+-+Search+contacts:+Error+short+description\">Bug report</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf232ea3-a970-48c8-b01b-1c7cc5d17cbf",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Tags:** #hubspot #crm #search #endpoints #python #requests #contacts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "00ccb408-774b-499e-99d2-bd5ac8e8a37e",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Author:** [Florent Ravenel](https://www.linkedin.com/in/florent-ravenel/)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d7adff63-c4ce-4a7e-9a4c-c1367c2ca859",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Last update:** 2024-02-15 (Created: 2024-02-15)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68350cf5-e010-4618-b61e-4f77a4fe03ba",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Description:** This notebook demonstrates how to use the CRM search contacts with python requests to filter, sort, and search objects, records, and engagements across your CRM."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c99a7810-dccf-4d25-974f-f81586aa8902",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**References:**\n",
    "- [HubSpot API Documentation](https://developers.hubspot.com/docs/api/crm/search)\n",
    "- [Get your HubSpot Access token](https://knowledge.hubspot.com/articles/kcs_article/integrations/how-do-i-get-my-hubspot-api-key)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28d0654e-579f-4e9a-9fe5-7234af80dd9a",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "## Input"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2f9168c-d148-4511-b75f-a57ee0588b2a",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Import libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "34197898-5462-40a5-8bbc-38c91e3cf0fd",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "import naas\n",
    "import requests\n",
    "import json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1153e066-e4d9-4935-8d4e-1958b9a76ac4",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Setup variables\n",
    "- `hs_access_token`: This variable stores an access token used for accessing the HubSpot API.\n",
    "- `endpoint`: The endpoint to which the request is sent.\n",
    "- `filters`: A list of filter conditions. Each condition is a dictionary that specifies the property name, operator, and value. [More information in API docs](https://developers.hubspot.com/docs/api/crm/search#filter-search-results)\n",
    "- `properties`: A list of properties to be included in the response.\n",
    "- `sorts`: A list of dictionaries that specify the property to sort by and the sort direction.\n",
    "- `limit`: The maximum number of objects to return. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "d772bd38-9fcf-4f10-bbc2-b8bd7bd192eb",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "hs_access_token = naas.secret.get(\"HS_ACCESS_TOKEN\") or \"YOUR_HS_ACCESS_TOKEN\"\n",
    "endpoint = \"contacts\"\n",
    "filters = [\n",
    "    {\n",
    "        \"propertyName\": \"firstname\",\n",
    "        \"operator\": \"EQ\",\n",
    "        \"value\": \"Florent\"\n",
    "    }\n",
    "]\n",
    "properties = [\n",
    "    \"firstname\", \n",
    "    \"lastname\", \n",
    "    \"linkedinbio\",\n",
    "    \"email\"\n",
    "]\n",
    "sorts = [\n",
    "    {\n",
    "        \"propertyName\": \"lastmodifieddate\", \n",
    "        \"direction\": \"DESCENDING\"\n",
    "    }\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a696e461-6282-486f-a2c4-46b5249f47cc",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "## Model"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfbae511-389c-4eb1-a89b-e1efa3f1af12",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Search Contacts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c7b935a-d37b-4b90-9101-4078573988ff",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "This function sends a POST request to the HubSpot CRM search endpoint. It uses the provided API key for authentication and sends a JSON payload that specifies the search parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e8d4b220-4a53-4601-9e78-4b40f53c9060",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "def search(\n",
    "    api_key,\n",
    "    endpoint,\n",
    "    filters=[],\n",
    "    properties=[],\n",
    "    sorts=[],\n",
    "    limit=100,\n",
    "):\n",
    "    \"\"\"\n",
    "    Sends a POST request to the HubSpot API to search for specific objects.\n",
    "\n",
    "    Args:\n",
    "        api_key (str): The API key for authentication.\n",
    "        endpoint (str): The endpoint to which the request is sent.\n",
    "        filters (list, optional): A list of filter conditions. Each condition is a dictionary that specifies the property name, operator, and value. Defaults to an empty list.\n",
    "        properties (list, optional): A list of properties to be included in the response. Defaults to an empty list.\n",
    "        sort (list, optional): A list of dictionaries that specify the property to sort by and the sort direction. Defaults to an empty list.\n",
    "        limit (int, optional): The maximum number of objects to return. Defaults to 100.\n",
    "\n",
    "    Returns:\n",
    "        dict: The JSON response from the API as a dictionary.\n",
    "    \"\"\"\n",
    "    \n",
    "    # Prepare headers for the HTTP request\n",
    "    headers = {\n",
    "        \"Content-Type\": \"application/json\",\n",
    "        \"Authorization\": f\"Bearer {api_key}\"\n",
    "    }\n",
    "    \n",
    "    # URL to query\n",
    "    url = f\"https://api.hubapi.com/crm/v3/objects/{endpoint}/search\"\n",
    "    \n",
    "    # Prepare the payload for the POST request\n",
    "    payload = {\n",
    "        \"filterGroups\": [\n",
    "            {\n",
    "                \"filters\": filters\n",
    "            }\n",
    "        ],\n",
    "        \"properties\": properties,\n",
    "        \"sorts\": sorts,\n",
    "        'limit': limit,\n",
    "    }\n",
    "    # Send the POST request to the endpoint URL\n",
    "    response = requests.post(url, headers=headers, data=json.dumps(payload))\n",
    "    # Parse the JSON response and return it\n",
    "    return response.json()\n",
    "\n",
    "result = search(hs_access_token, endpoint, filters, properties, sorts)\n",
    "print(\"Results:\", result.get(\"total\"))\n",
    "if len(result.get(\"results\")) > 0:\n",
    "    print(result.get(\"results\")[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46a12d9c-6742-4c92-9e24-d91b16fd2eb7",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "## Output"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7fe1f917-af33-4c29-b12f-6b5ba3dd3b8b",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Display result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "74b30759-f32d-4565-bb55-8a2a9b9ddf7f",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "09906c15-f1ff-459d-9279-ae2426a39fcf",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.6"
  },
  "naas": {
   "notebook_id": "305b233161df927d98140eca678ad97c05e852073adda9e2bec5fc775420d9e4",
   "notebook_path": "HubSpot/HubSpot_Search_contacts.ipynb"
  },
  "papermill": {
   "default_parameters": {},
   "environment_variables": {},
   "parameters": {},
   "version": "2.5.0"
  },
  "toc-showcode": false,
  "toc-showmarkdowntxt": false,
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}