This document outlines how to connect to the Hubspot API in order to retrieve data elements. You will find a list of cURL examples that can be reused with minimal changes required.
Authentication
HubSpot uses OAuth 2.0 for authentication and authorization of third-party applications. The cURL below will use the client credentials to retrieve an access token and a refresh token.
Access Token
curl -X POST \
'https://api.hubapi.com/oauth/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
-d 'grant_type=authorization_code' \
-d 'client_id=<your_client_id>' \
-d 'client_secret=<your_client_secret>' \
-d 'redirect_uri=<your_redirect_uri>' \
-d 'code=<your_authorization_code>'
-
<your_client_id>: The client ID for your HubSpot application. You can find this in the HubSpot developer dashboard. -
<your_client_secret>: The client secret for your HubSpot application. You can find this in the HubSpot developer dashboard. -
<your_redirect_uri>: The redirect URI that you registered for your HubSpot application. This should be the same URI that you used when requesting the authorization code. -
<your_authorization_code>: The authorization code that you received from HubSpot after the user granted permission for your application to access their data.
Refresh Token
The cURL below will use the refresh token to get another access token.
curl -X POST \
'https://api.hubapi.com/oauth/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
-d 'grant_type=refresh_token' \
-d 'client_id=<your_client_id>' \
-d 'client_secret=<your_client_secret>' \
-d 'refresh_token=<your_refresh_token>'-
<your_client_id>: The client ID for your HubSpot application. -
<your_client_secret>: The client secret for your HubSpot application. -
<your_refresh_token>: The refresh token that you received along with the original access token.
Data Connecivity
Get New Leads
This Hubspot API call retrieves new Leads added to Hubspot. Note that the vidOffset parameter is used in conjunction with the vids parameter, which specifies the IDs of the leads you want to retrieve. If you do not specify the vids parameter, the API will retrieve all leads starting from the lead with the specified vidOffset.
curl "https://api.hubapi.com/contacts/v1/lists/all/contacts/all?vidOffset=<last_id>" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_access_token>" \
-X GETSample Results
{
"contacts": [
{
"vid": 12345,
"canonical-vid": 12345,
"merged-vids": [],
"portal-id": 1234567,
"is-contact": true,
"properties": {
"firstname": {
"value": "John"
},
"lastname": {
"value": "Doe"
},
"email": {
"value": "[email protected]"
},
"phone": {
"value": "+1 555-555-5555"
},
"company": {
"value": "Acme Corp"
}
},
"form-submissions": [],
"identity-profiles": [
{
"vid": 12345,
"saved-at-timestamp": 1620319273121,
"deleted-changed-timestamps": []
}
],
"merge-audits": [],
"associated-company-id": null
},
{
"vid": 67890,
"canonical-vid": 67890,
"merged-vids": [],
"portal-id": 1234567,
"is-contact": true,
"properties": {
"firstname": {
"value": "Jane"
},
"lastname": {
"value": "Smith"
},
"email": {
"value": "[email protected]"
},
"phone": {
"value": "+1 555-555-5555"
},
"company": {
"value": "Widgets Inc"
}
},
"form-submissions": [],
"identity-profiles": [
{
"vid": 67890,
"saved-at-timestamp": 1620319273121,
"deleted-changed-timestamps": []
}
],
"merge-audits": [],
"associated-company-id": null
}
],
"has-more": false,
"vid-offset": 12345
}