TimeXtender HubSpot Data Source
Access and ingest data from the CRM-related REST APIs in HubSpot using the TimeXtender HubSpot data source.
Authentication
HubSpot REST APIs use 2 main ways to authenticate based on if you create a private or public application to share the data. Using a public application requires OAuth authentication. The more common way is to use a private application and then you are provided with a Bearer token to authenticate with.
Custom Objects
In HubSpot, it is possible to create your own Custom Objects in addition to the default HubSpot objects. In the TimeXtender HubSpot data source connector you have the option to include these custom objects when the data source is run on the Ingest Service. The actual endpoints for these custom objects are not available in the portal but are generated internally when the data source is run. If you only want to include certain custom objects you can provide a comma-separated list of these objects names in the input field for custom objects. If left blank (and Include custom objects is checked off) all custom objects will be included. It is also possible to get archived results from the custom objects by checking off the Custom Objects Archived checkbox.
Request limits
HubSpot has rate limits that limit the number of API calls that can be made over different intervals.
The TimeXtender HubSpot data source has the Private Apps Free and Starter tier limits set as default values. This limits the number of requests to 10 requests per second (100 per 10 seconds) and a total of 250000 requests per day.
If you have a different tier or experience that you breach the 10-second limit, these settings can be adjusted under Request Limits settings. Note that to set the 10-second limit, you have to adjust it to a per 1-second limit and set it accordingly.
Endpoints
There are 4 different types of endpoints in the TimeXtender HubSpot data source connector:
- CRM objects and engagements endpoints
- Object pipeline and stage endpoints
- Owners' and teams endpoint
- Custom objects endpoint
CRM objects and engagements endpoints
These endpoints are the main endpoints containing objects like companies, products, emails, etc. Each endpoint has a set of query parameters that can be edited to define the output of the API. Below are the different parameters and descriptions:
| Name of parameter | Description |
| properties | Each object has a set of properties (columns in a table) that can be defined in this field as a comma-separated list, eg: id, name, date and so forth. If this parameter is left blank, there will be an API call done in the background to get all available properties and they will be applied when the data source is run. |
| propertiesWithHistory | Same as for properties above, provide a comma-separated list of the properties that you want to receive historical data for. Leave this blank to populate it with all properties. Note: To enable this field it is necessary to check off the “Include properties with history” checkbox on the endpoint. Including properties with history will also reduce the number of records limit to a maximum of 50 records per call. This is sorted out by the logic in the connector, so it is not necessary to reduce the limit, but it will increase the number of calls necessary to pull all data. |
| limit | The maximum limit of records per call at the time of implementation is 100. 50 when properties with history are included. |
| archived | The default value here is false, which means non-archived records are returned from the endpoint. If set to true it will return archived records. |
| associations | For this parameter, you can provide a comma-separated list of objects you want to return associations to from the current object. If left empty it will provide associations to all the other CRM objects, and if Include Custom Objects is checked off these will also be included. |
For each endpoint, there are also 3 table flattening transformations that produce 3 different tables returned from the endpoint:
| Name of table flattening | Description |
| associations | This transformation will provide the associations table. It will have the name structure as follows: <ObjectName>Associations |
| properties | This transformation is the main table containing the properties returned on the object. It will have the name structure as follows: <ObjectName> |
| history | This transformation contains the propertiesWithHistory data. It will have the name structure as follows: <ObjectName>History This table will have the id (record) and property columns as foreign keys to the main properties table. |
Below the table flattening transformations, there is also a checkbox for Only list flattened tables. This is checked by default.
In addition to this, there is also a checkbox for Include properties with history. This is unchecked by default. Checking this and not providing any properties in the propertiesWithHistory parameter mentioned above will result in all properties being returned with history.
Note: Checking Include properties with history will reduce the record limit per call to 50 and will also potentially result in very large amounts of data.
Object pipeline and stages endpoints
These endpoints contain the different objects pipelines and stages associated with them. According to HubSpot documentation, only deals and tickets have pipelines and stages, but companies, contacts, products, and tasks can also have pipelines and stages associated with them. The data for these pipelines are returned in these endpoints. The endpoints have the name structure as follows: <object_name>_pipeline_and_stages.
Each endpoint has 2 table flattening transformations resulting in 2 tables:
| Name of table flattening | Description |
| pipelines | This transformation returns the pipelines associated with the object. The table name will have the following structure: <ObjectName>Pipelines |
| stages | This transformation returns the stages available for the objects pipelines. The table name will have the following structure: <ObjectName>PipelineStages |
Owners and teams pipeline
This endpoint, named owners_and_teams, pulls out all the owners assigned to CRM objects in HubSpot. Owners can also be part of teams, and teams are extracted in a separate table.
Note: The teams table is an aggregate of all teams which owners are assigned to, so this table should not be considered an exhaustive list of all teams (there is no such endpoint). It will also potentially contain many duplicates.
The endpoint results in two tables:
| Name of table flattening | Description |
| owners | This transformation returns the owners assigned to CRM objects in HubSpot. The table name will be: Owners |
| teams | This transformation returns the aggregate of all teams owners are assigned to. The table name will be: Teams |
Custom objects endpoint
This endpoint, named “custom_objects”, returns the custom objects schemas with properties and potential associations.
Note: This endpoint does not return any custom object data.
The endpoint results in three tables:
| Name of table flattening | Description |
| custom_objects | This transformation returns the custom objects with name, required properties, etc. The table name will be: CustomObjects |
| custom_objects_properties | This transformation returns the custom objects properties with name, label, type, etc. The table name will be: CustomObjectProperties |
| custom_objects_associations | This transformation returns the custom objects potential associations. The table name will be: CustomObjectAssociations |
