tap-hubspot is a Singer tap for Hubspot.
Built with the Meltano Singer SDK.
catalogstatediscoveraboutstream-mapsschema-flatteningbatch
| Setting | Required | Default | Description |
|---|---|---|---|
| access_token | False | None | Token to authenticate against the API service |
| client_id | False | None | The OAuth app client ID. |
| client_secret | False | None | The OAuth app client secret. |
| refresh_token | False | None | The OAuth app refresh token. |
| start_date | False | None | Earliest record date to sync |
| end_date | False | None | Latest record date to sync |
| limit_events_month | False | None | Hard limit the start date to last X months from today (no limit if not set) |
| stream_maps | False | None | Config object for stream maps capability. For more information check out Stream Maps. |
| stream_map_config | False | None | User-defined config values to be used within map expressions. |
| flattening_enabled | False | None | 'True' to enable schema flattening and automatically expand nested properties. |
| flattening_max_depth | False | None | The max depth to flatten schemas. |
| batch_config | False | None |
A full list of supported settings and capabilities is available by running: tap-hubspot --about
The limit_events_month parameter provides a way to hard limit how far back the tap will sync data, regardless of the configured start_date. This is useful for:
- Preventing excessive API usage when syncing large historical datasets
- Implementing rolling data windows for incremental syncs
- Controlling resource usage by limiting data volume
- When
limit_events_monthis set to a positive integer (e.g.,6), the tap calculates a limit date by going back31 * Ndays from today - The effective start date becomes the more recent of:
- The configured
start_dateOR existing incremental state - The calculated limit date (31 * N days ago from today)
- The configured
- This applies to both initial runs and incremental syncs with existing state
- If
limit_events_monthis not set or isnull, the originalstart_dateor incremental state is used without any limitation - When limiting is applied, a log message will show the date change
Initial Run:
# Configuration
start_date: "2020-01-01T00:00:00Z"
limit_events_month: 6
# Result: If today is 2025-07-18, the effective start date becomes 2024-01-20T00:00:00Z
# (186 days ago = 31 * 6), ignoring the older start_date of 2020-01-01Incremental Run with Old State:
# Configuration (incremental state exists from 2020-01-01)
limit_events_month: 12
# Log: "Limiting incremental state from 2020-01-01T00:00:00Z to 2023-07-21T00:00:00Z due to limit_events_month=12"
# Result: Uses 2023-07-21 instead of the old 2020-01-01 stateThe licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software.
pipx install git+https://github.com/ryan-miranda-partners/tap-hubspot.gitThis Singer tap will automatically import any environment variables within the working directory's
.env if the --config=ENV is provided, such that config values will be considered if a matching
environment variable is set either in the terminal context or in the .env file.
A Hubspot access token is required to make API requests. (See Hubspot API docs for more info)
The following scopes need to be added to your access token to access the following endpoints:
- Contacts:
crm.schemas.contacts.readorcrm.objects.contacts.read - Users:
settings.users.read - Ticket Pipeline:
media_bridge.readorcrm.schemas.custom.readortimelineorticketsore-commerceorcrm.objects.goals.read - Deal Pipeline:
media_bridge.readorcrm.schemas.custom.readortimelineorticketsore-commerceorcrm.objects.goals.read - Properties: All of
Tickets,crm.objects.deals.read,sales-email-read,crm.objects.contacts.read,crm.objects.companies.read,e-commerce,crm.objects.quotes.read - Owners:
crm.objects.owners.read - Companies:
crm.objects.companies.read - Deals:
crm.objects.deals.read - Feedback Submissions:
crm.objects.contacts.read - Line Items:
e-commerce - Products:
e-commerce - Tickets:
tickets - Quotes:
crm.objects.quotes.readorcrm.schemas.quotes.read - Goals:
crm.objects.goals.read - Emails:
sales-email-read
For more info on the streams and permissions, check the Hubspot API Documentation.
You can easily run tap-hubspot by itself or in a pipeline using Meltano.
The following Streams use the v1 (legacy) endpoint in the Hubspot API:
- TicketPipeline & DealPipeline: The v3 endpoint requires a pipeline ID parameter to make calls to the API. Because of this, you are limited to only pulling data for a single pipeline ID from v3, whereas the v1 API allows you to pull from all pipelines.
- EmailSubscriptions: The v3 endpoint requires you to set a single email address to pull subscription data, whereas the v1 endpoint allows you to pull data from all emails.
This project uses parent-child streams. Learn more about them here.
tap-hubspot --version
tap-hubspot --help
tap-hubspot --config CONFIG --discover > ./catalog.jsonFollow these instructions to contribute to this project.
pipx install poetry
poetry installCreate tests within the tests subfolder and
then run:
poetry run pytestYou can also test the tap-hubspot CLI interface directly using poetry run:
poetry run tap-hubspot --helpTesting with Meltano
Note: This tap will work in any Singer environment and does not require Meltano. Examples here are for convenience and to streamline end-to-end orchestration scenarios.
Your project comes with a custom meltano.yml project file already created. Open the meltano.yml and follow any "TODO" items listed in
the file.
Next, install Meltano (if you haven't already) and any needed plugins:
# Install meltano
pipx install meltano
# Initialize meltano within this directory
cd tap-hubspot
meltano installNow you can test and orchestrate using Meltano:
# Test invocation:
meltano invoke tap-hubspot --version
# OR run a test `elt` pipeline:
meltano elt tap-hubspot target-jsonlSee the dev guide for more instructions on how to use the SDK to develop your own taps and targets.