# hubspot-api-python
Python [HubSpot API](https://developers.hubspot.com/docs/api/overview) v3 SDK(Client) files and sample apps
Sample Applications can be found in [Sample apps](https://github.com/HubSpot/sample-apps-list)
## Documentation
See the [API docs](https://developers.hubspot.com/docs/api/overview).
## Installation
If you just want to use the package, run:
```bash
pip install --upgrade hubspot-api-client
```
### Requirements
Make sure you have [Python 3.7+](https://docs.python.org/3/) and [pip](https://pypi.org/project/pip/) installed.
## Quickstart
### Configuring HubSpot client
```python
from hubspot import HubSpot
api_client = HubSpot(access_token='your_access_token')
# or set your access token later
api_client = HubSpot()
api_client.access_token = 'your_access_token'
```
You'll need to create a [private app](https://developers.hubspot.com/docs/api/private-apps) to get your access token or you can obtain OAuth2 access token.
#### Hapikey support:
Please, note that hapikey is no longer supported after v5.1.0. You can get more info about hapikey sunset [here](https://developers.hubspot.com/changelog/upcoming-api-key-sunset). Also, plese, visit a [migration guide](https://developers.hubspot.com/docs/api/migrate-an-api-key-integration-to-a-private-app) if you need help with a migration process.
### OAuth API
#### Obtain OAuth2 access token:
```python
from hubspot.auth.oauth import ApiException
try:
tokens = api_client.auth.oauth.tokens_api.create(
grant_type="authorization_code",
redirect_uri='http://localhost',
client_id='client_id',
client_secret='client_secret',
code='code'
)
except ApiException as e:
print("Exception when calling create_token method: %s\n" % e)
```
### CRM API
#### Create contact:
```python
from hubspot.crm.contacts import SimplePublicObjectInputForCreate
from hubspot.crm.contacts.exceptions import ApiException
try:
simple_public_object_input_for_create = SimplePublicObjectInputForCreate(
properties={"email": "email@example.com"}
)
api_response = api_client.crm.contacts.basic_api.create(
simple_public_object_input_for_create=simple_public_object_input_for_create
)
except ApiException as e:
print("Exception when creating contact: %s\n" % e)
```
#### Get contact by id:
```python
from hubspot.crm.contacts import ApiException
try:
contact_fetched = api_client.crm.contacts.basic_api.get_by_id('contact_id')
except ApiException as e:
print("Exception when requesting contact by id: %s\n" % e)
```
#### Get custom objects page:
```python
from hubspot.crm.objects import ApiException
try:
my_custom_objects_page = api_client.crm.objects.basic_api.get_page(object_type="my_custom_object_type")
except ApiException as e:
print("Exception when requesting custom objects: %s\n" % e)
```
#### Get all:
`get_all` method is available for all objects (Companies, Contacts, Deals and etc).
```python
all_contacts = api_client.crm.contacts.get_all()
```
Please note that pagination is used under the hood to get all results.
## Search:
`do_search` method is available for all objects (Companies, Contacts, Deals and etc).
### Example Search by date:
```python
import hubspot
from dateutil import parser
from pprint import pprint
from hubspot.crm.contacts import PublicObjectSearchRequest, ApiException
api_client = hubspot.Client.create(access_token="YOUR_ACCESS_TOKEN")
# timestamp in milliseconds
date = str(int(parser.isoparse("XXXX-XX-XXTXX:XX:XX.XXXZ").timestamp() * 1000))
public_object_search_request = PublicObjectSearchRequest(
filter_groups=[
{
"filters": [
{
"value": date,
"propertyName": "lastmodifieddate",
"operator": "EQ"
}
]
}
], limit=10
)
try:
api_response = api_client.crm.contacts.search_api.do_search(public_object_search_request=public_object_search_request)
pprint(api_response)
except ApiException as e:
print("Exception when calling search_api->do_search: %s\n" % e)
```
### CMS API
#### Get audit logs:
```python
from hubspot.cms.audit_logs import ApiException
try:
audit_logs_page = api_client.cms.audit_logs.default_api.get_page()
except ApiException as e:
print("Exception when calling cards_api->create: %s\n" % e)
```
## Not wrapped endpoint(s)
It is possible to access the hubspot request method directly,
it could be handy if client doesn't have implementation for some endpoint yet.
Exposed request method benefits by having all configured client params.
```python
client.api_request({
"method": "PUT",
"path": "/some/api/not/wrapped/yet",
"body": {"key": "value"}
})
```
### {Example} for `GET` request
```python
import hubspot
from pprint import pprint
from hubspot.crm.contacts import ApiException
client = hubspot.Client.create(access_token="your_access_token")
try:
response = client.api_request(
{"path": "/crm/v3/objects/contacts"}
)
pprint(response)
except ApiException as e:
print(e)
```
### {Example} for `POST` request
```python
import hubspot
from pprint import pprint
from hubspot.crm.contacts import ApiException
client = hubspot.Client.create(access_token="your_access_token")
try:
response = client.api_request(
{
"path": "/crm/v3/objects/contacts",
"method": "POST",
"body": {
"properties":
{
"email": "some_email@some.com",
"lastname": "some_last_name"
},
}
}
)
pprint(response.json())
except ApiException as e:
print(e)
```
### Using utils
#### Get OAuth url:
```python
from hubspot.utils.oauth import get_auth_url
auth_url = get_auth_url(
scope=('contacts',),
client_id='client_id',
redirect_uri='http://localhost'
)
```
#### Validate HubSpot request signature
[Example](./sample-apps/webhooks-app/src/routes/webhooks.py) of usage from [Webhooks Sample App](./sample-apps/webhooks-app):
```python
import os
from flask import request
from hubspot.utils.signature import Signature
Signature.is_valid(
signature=request.headers["X-HubSpot-Signature"],
client_secret=os.getenv("HUBSPOT_CLIENT_SECRET"),
request_body=request.data.decode("utf-8"),
http_uri=request.base_url,
signature_version=request.headers["X-HubSpot-Signature-Version"],
timestamp=request.headers["X-HubSpot-Request-Timestamp"]
)
```
### Retry middleware
You can pass an instance of [urllib3.util.retry.Retry](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html) class to configure http client retries.
With internal error retry middleware:
```python
from hubspot import HubSpot
from urllib3.util.retry import Retry
retry = Retry(
total=3,
backoff_factor=0.3,
status_forcelist=(500, 502, 504),
)
api_client = HubSpot(retry=retry)
```
Or with rate limit retry middleware:
```python
from hubspot import HubSpot
from urllib3.util.retry import Retry
retry = Retry(
total=5,
status_forcelist=(429,),
)
api_client = HubSpot(retry=retry)
```
### Convert response object to dict
`to_dict` method is available for most response objects
```python
contacts = api_client.crm.contacts.basic_api.get_page()
for contact in contacts:
print(contact.to_dict())
```
## Sample Apps
Please, take a look at our [Sample apps](https://github.com/HubSpot/sample-apps-list)
## Contributing
Install the package locally:
```
pip install -e .
```
Set up the development virtualenv:
```
make
```
Run tests:
```
make test
```
Run [Black](https://github.com/psf/black) for code formatting:
```
make fmt
```
Raw data
{
"_id": null,
"home_page": "https://github.com/HubSpot/hubspot-api-python",
"name": "hubspot-api-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "HubSpot",
"author_email": "support@hubspot.com",
"download_url": "https://files.pythonhosted.org/packages/08/52/11b0ecd4fd6e175813a0017ab4bc4697bfde058cac9b98938fa28460028a/hubspot_api_client-11.1.0.tar.gz",
"platform": null,
"description": "# hubspot-api-python\n\nPython [HubSpot API](https://developers.hubspot.com/docs/api/overview) v3 SDK(Client) files and sample apps\n\nSample Applications can be found in [Sample apps](https://github.com/HubSpot/sample-apps-list)\n\n## Documentation\n\nSee the [API docs](https://developers.hubspot.com/docs/api/overview).\n\n## Installation\n\nIf you just want to use the package, run:\n\n```bash\npip install --upgrade hubspot-api-client\n```\n\n### Requirements\n\nMake sure you have [Python 3.7+](https://docs.python.org/3/) and [pip](https://pypi.org/project/pip/) installed.\n\n\n## Quickstart\n\n\n### Configuring HubSpot client\n\n```python\nfrom hubspot import HubSpot\n\napi_client = HubSpot(access_token='your_access_token')\n\n# or set your access token later\napi_client = HubSpot()\napi_client.access_token = 'your_access_token'\n```\n\nYou'll need to create a [private app](https://developers.hubspot.com/docs/api/private-apps) to get your access token or you can obtain OAuth2 access token.\n\n#### Hapikey support:\n\nPlease, note that hapikey is no longer supported after v5.1.0. You can get more info about hapikey sunset [here](https://developers.hubspot.com/changelog/upcoming-api-key-sunset). Also, plese, visit a [migration guide](https://developers.hubspot.com/docs/api/migrate-an-api-key-integration-to-a-private-app) if you need help with a migration process.\n\n### OAuth API\n\n#### Obtain OAuth2 access token:\n\n```python\nfrom hubspot.auth.oauth import ApiException\n\ntry:\n tokens = api_client.auth.oauth.tokens_api.create(\n grant_type=\"authorization_code\",\n redirect_uri='http://localhost',\n client_id='client_id',\n client_secret='client_secret',\n code='code'\n )\nexcept ApiException as e:\n print(\"Exception when calling create_token method: %s\\n\" % e)\n```\n\n### CRM API\n\n\n#### Create contact:\n\n```python\nfrom hubspot.crm.contacts import SimplePublicObjectInputForCreate\nfrom hubspot.crm.contacts.exceptions import ApiException\n\ntry:\n simple_public_object_input_for_create = SimplePublicObjectInputForCreate(\n properties={\"email\": \"email@example.com\"}\n )\n api_response = api_client.crm.contacts.basic_api.create(\n simple_public_object_input_for_create=simple_public_object_input_for_create\n )\nexcept ApiException as e:\n print(\"Exception when creating contact: %s\\n\" % e)\n```\n\n#### Get contact by id:\n\n```python\nfrom hubspot.crm.contacts import ApiException\n\ntry:\n contact_fetched = api_client.crm.contacts.basic_api.get_by_id('contact_id')\nexcept ApiException as e:\n print(\"Exception when requesting contact by id: %s\\n\" % e)\n```\n\n#### Get custom objects page:\n\n```python\nfrom hubspot.crm.objects import ApiException\n\ntry:\n my_custom_objects_page = api_client.crm.objects.basic_api.get_page(object_type=\"my_custom_object_type\")\nexcept ApiException as e:\n print(\"Exception when requesting custom objects: %s\\n\" % e)\n```\n\n#### Get all:\n\n`get_all` method is available for all objects (Companies, Contacts, Deals and etc).\n\n```python\nall_contacts = api_client.crm.contacts.get_all()\n```\n\nPlease note that pagination is used under the hood to get all results.\n\n## Search:\n\n`do_search` method is available for all objects (Companies, Contacts, Deals and etc).\n\n### Example Search by date:\n```python\nimport hubspot\n\nfrom dateutil import parser\nfrom pprint import pprint\nfrom hubspot.crm.contacts import PublicObjectSearchRequest, ApiException\n\napi_client = hubspot.Client.create(access_token=\"YOUR_ACCESS_TOKEN\")\n\n# timestamp in milliseconds\ndate = str(int(parser.isoparse(\"XXXX-XX-XXTXX:XX:XX.XXXZ\").timestamp() * 1000))\npublic_object_search_request = PublicObjectSearchRequest(\n filter_groups=[\n {\n \"filters\": [\n {\n \"value\": date,\n \"propertyName\": \"lastmodifieddate\",\n \"operator\": \"EQ\"\n }\n ]\n }\n ], limit=10\n)\ntry:\n api_response = api_client.crm.contacts.search_api.do_search(public_object_search_request=public_object_search_request)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling search_api->do_search: %s\\n\" % e)\n\n```\n\n### CMS API\n\n#### Get audit logs:\n\n```python\nfrom hubspot.cms.audit_logs import ApiException\n\ntry:\n audit_logs_page = api_client.cms.audit_logs.default_api.get_page()\nexcept ApiException as e:\n print(\"Exception when calling cards_api->create: %s\\n\" % e)\n```\n## Not wrapped endpoint(s)\n\nIt is possible to access the hubspot request method directly,\nit could be handy if client doesn't have implementation for some endpoint yet.\nExposed request method benefits by having all configured client params.\n\n```python\nclient.api_request({\n \"method\": \"PUT\",\n \"path\": \"/some/api/not/wrapped/yet\",\n \"body\": {\"key\": \"value\"}\n})\n```\n\n### {Example} for `GET` request\n\n```python\nimport hubspot\nfrom pprint import pprint\nfrom hubspot.crm.contacts import ApiException\n\nclient = hubspot.Client.create(access_token=\"your_access_token\")\n\ntry:\n response = client.api_request(\n {\"path\": \"/crm/v3/objects/contacts\"}\n )\n pprint(response)\nexcept ApiException as e:\n print(e)\n```\n\n### {Example} for `POST` request\n\n```python\nimport hubspot\nfrom pprint import pprint\nfrom hubspot.crm.contacts import ApiException\n\nclient = hubspot.Client.create(access_token=\"your_access_token\")\n\ntry:\n response = client.api_request(\n {\n \"path\": \"/crm/v3/objects/contacts\",\n \"method\": \"POST\",\n \"body\": {\n \"properties\":\n {\n \"email\": \"some_email@some.com\",\n \"lastname\": \"some_last_name\"\n },\n }\n }\n\n )\n pprint(response.json())\nexcept ApiException as e:\n print(e)\n```\n### Using utils\n\n#### Get OAuth url:\n\n```python\nfrom hubspot.utils.oauth import get_auth_url\n\nauth_url = get_auth_url(\n scope=('contacts',),\n client_id='client_id',\n redirect_uri='http://localhost'\n)\n```\n\n#### Validate HubSpot request signature\n\n[Example](./sample-apps/webhooks-app/src/routes/webhooks.py) of usage from [Webhooks Sample App](./sample-apps/webhooks-app):\n\n```python\nimport os\nfrom flask import request\nfrom hubspot.utils.signature import Signature\n\nSignature.is_valid(\n signature=request.headers[\"X-HubSpot-Signature\"],\n client_secret=os.getenv(\"HUBSPOT_CLIENT_SECRET\"),\n request_body=request.data.decode(\"utf-8\"),\n http_uri=request.base_url,\n signature_version=request.headers[\"X-HubSpot-Signature-Version\"],\n timestamp=request.headers[\"X-HubSpot-Request-Timestamp\"]\n)\n```\n\n### Retry middleware\n\nYou can pass an instance of [urllib3.util.retry.Retry](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html) class to configure http client retries.\nWith internal error retry middleware:\n\n```python\nfrom hubspot import HubSpot\nfrom urllib3.util.retry import Retry\n\nretry = Retry(\n total=3,\n backoff_factor=0.3,\n status_forcelist=(500, 502, 504),\n)\napi_client = HubSpot(retry=retry)\n```\nOr with rate limit retry middleware:\n\n```python\nfrom hubspot import HubSpot\nfrom urllib3.util.retry import Retry\n\nretry = Retry(\n total=5,\n status_forcelist=(429,),\n)\napi_client = HubSpot(retry=retry)\n```\n\n### Convert response object to dict\n\n`to_dict` method is available for most response objects\n\n```python\ncontacts = api_client.crm.contacts.basic_api.get_page()\nfor contact in contacts:\n print(contact.to_dict())\n```\n\n## Sample Apps\n\nPlease, take a look at our [Sample apps](https://github.com/HubSpot/sample-apps-list)\n\n## Contributing\n\nInstall the package locally:\n\n```\npip install -e .\n```\n\nSet up the development virtualenv:\n\n```\nmake\n```\n\nRun tests:\n```\nmake test\n```\n\nRun [Black](https://github.com/psf/black) for code formatting:\n```\nmake fmt\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "HubSpot API client",
"version": "11.1.0",
"project_urls": {
"Homepage": "https://github.com/HubSpot/hubspot-api-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a1d3a2dbdea1f491d5bf362d74d4b7342ece6c043a43c8ee997f8fb8b776239d",
"md5": "5c0069a05b0ca43789b9ef7815785ad1",
"sha256": "0c49e2c2f511a56d249c6890d2dfdd62afd04f66edc69a591e8348e28804634b"
},
"downloads": -1,
"filename": "hubspot_api_client-11.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c0069a05b0ca43789b9ef7815785ad1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 3945382,
"upload_time": "2024-12-13T08:20:42",
"upload_time_iso_8601": "2024-12-13T08:20:42.129936Z",
"url": "https://files.pythonhosted.org/packages/a1/d3/a2dbdea1f491d5bf362d74d4b7342ece6c043a43c8ee997f8fb8b776239d/hubspot_api_client-11.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "085211b0ecd4fd6e175813a0017ab4bc4697bfde058cac9b98938fa28460028a",
"md5": "c46398f014d44a91508135434f8ec2cb",
"sha256": "93ed914f1cd4dad67bacf26b8a1ec8506847483fa801cb2bddd4b2d887d0f825"
},
"downloads": -1,
"filename": "hubspot_api_client-11.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c46398f014d44a91508135434f8ec2cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 1732887,
"upload_time": "2024-12-13T08:20:44",
"upload_time_iso_8601": "2024-12-13T08:20:44.380171Z",
"url": "https://files.pythonhosted.org/packages/08/52/11b0ecd4fd6e175813a0017ab4bc4697bfde058cac9b98938fa28460028a/hubspot_api_client-11.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 08:20:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HubSpot",
"github_project": "hubspot-api-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hubspot-api-client"
}
JSON
