# Contacts History

**URL:** <https://community.hubspot.com/t/contacts-history/79233>\
**Category:** APIs & Integrations\
**Tags:** contacts\
**Created:** [April 13, 2023, 6:25am UTC](https://community.hubspot.com/t/contacts-history/79233 "2023-04-13T06:25:57Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![StephaneBadel](https://avatars.discourse-cdn.com/v4/letter/s/9dc877/32.png) [@StephaneBadel](https://community.hubspot.com/u/StephaneBadel)\
**Post date:** [April 13, 2023, 6:25am UTC](https://community.hubspot.com/t/contacts-history/79233/1 "2023-04-13T06:25:57Z")

</div>

Is there a way to retrive contacts history to run further analysis outside of Hubspot (python pandas)?

---

<div class="post-metadata">

**Author:** ![himanshurauthan](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/himanshurauthan/32/53076_2.png) [@himanshurauthan](https://community.hubspot.com/u/himanshurauthan)\
**Post date:** [April 13, 2023, 7:18am UTC](https://community.hubspot.com/t/contacts-history/79233/2 "2023-04-13T07:18:37Z")

</div>

Hello @StephaneBadel

HubSpot provides an API that allows you to retrieve data from the platform. To retrieve contacts history, you can use the Contacts API or the Timeline API.

Here are the general steps to retrieve contacts history data using the Contacts API:

Obtain an API key from HubSpot.  
Use the Contacts API to fetch a list of contacts and their associated IDs.  
Use the Timeline API to fetch the timeline events associated with each contact ID.  
You can filter the events to only include contact property changes or other events that are relevant to your analysis.  
Store the data in a format that can be loaded into Pandas, such as a CSV file.  
Use Pandas to perform the desired analysis on the data.  
You can use the requests library in Python to make API requests to HubSpot, and the pandas library to perform data analysis.

Here is an example of how to retrieve contacts history data using the HubSpot API and Python:

```lia-code-sample
import requests
import pandas as pd

# Set up API key and endpoint URLs
api_key = 'your-api-key'
contacts_url = 'https://api.hubapi.com/contacts/v1/lists/all/contacts/all'
timeline_url = 'https://api.hubapi.com/contacts/v1/contact/vid/{}/timeline'

# Fetch list of contacts
params = {'hapikey': api_key}
response = requests.get(contacts_url, params=params)
contacts = response.json()['contacts']

# Fetch timeline events for each contact
timeline_events = []
for contact in contacts:
 vid = contact['vid']
 response = requests.get(timeline_url.format(vid), params=params)
 events = response.json()['results']
 timeline_events.extend(events)

# Convert data to Pandas DataFrame
df = pd.json_normalize(timeline_events)

```

This code fetches a list of all contacts from HubSpot, then fetches the timeline events associated with each contact using the Timeline API. The resulting data is stored in a Pandas DataFrame for further analysis.

---

<div class="post-metadata">

**Author:** ![StephaneBadel](https://avatars.discourse-cdn.com/v4/letter/s/9dc877/32.png) [@StephaneBadel](https://community.hubspot.com/u/StephaneBadel)\
**Post date:** [April 18, 2023, 1:31am UTC](https://community.hubspot.com/t/contacts-history/79233/3 "2023-04-18T01:31:39Z")

</div>

Thanks for your answer ! The timeline GET call response is a 404, im not sure where to actually get the history then..

---

<div class="post-metadata">

**Author:** ![StephaneBadel](https://avatars.discourse-cdn.com/v4/letter/s/9dc877/32.png) [@StephaneBadel](https://community.hubspot.com/u/StephaneBadel)\
**Post date:** [April 14, 2023, 8:51am UTC](https://community.hubspot.com/t/contacts-history/79233/4 "2023-04-14T08:51:22Z")

</div>

Thanks for your answer!

However, the timeline URL seems like it gives a 404 response!

---

<div class="post-metadata">

**Author:** ![jminro](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/jminro/32/197045_2.png) [@jminro](https://community.hubspot.com/u/jminro)\
**Post date:** [April 18, 2023, 7:13pm UTC](https://community.hubspot.com/t/contacts-history/79233/5 "2023-04-18T19:13:45Z")

</div>

Yes, it is possible to retrieve contact history from HubSpot and run further analysis using Python and pandas.

To do this, you can use the HubSpot API to access the contact information and export it as a CSV file. Then, you can use pandas to read in the CSV file and perform any further analysis or manipulations.

Here are the general steps you can follow:

1. Authenticate with the HubSpot API using an API key or OAuth 2.0.
2. Use the API to retrieve the contact information, including any relevant properties or engagement data. You can use the [Contacts API](https://legacydocs.hubspot.com/docs/methods/contacts/contacts-overview) [idea](https://usernamesideas.com/) or the Engagements API, depending on the specific data you need.
3. Export the data as a CSV file using Python’s built-in CSV module or a third-party library like Pandas.
4. Use pandas to read in the CSV file and perform any desired analysis or manipulations.

Here’s an example code snippet that retrieves contact properties and engagement data for all contacts and exports it as a CSV file:

import requests  
import csv

# Set up API credentials and endpoint URL  
api\_key = ‘YOUR\_API\_KEY\_HERE’  
endpoint = ‘[https://api.hubapi.com](https://api.hubapi.com)’

# Set up API request headers  
headers = {‘Authorization’: f’Bearer {api\_key}'}

# Define the properties and engagements to retrieve  
properties = [‘firstname’, ‘lastname’, ‘email’]  
engagements = [‘type’, ‘timestamp’]

# Make the API request to retrieve the contacts  
response = requests.get(f’{endpoint}/contacts/v1/lists/all/contacts/all’,  
headers=headers,  
params={‘property’: properties, ‘engagement’: engagements})

# Extract the contact and engagement data from the response  
data = response.json()[‘contacts’]  
for contact in data:  
contact[‘engagements’] = [engagement[‘engagement’] for engagement in contact[‘engagements’]]

# Export the data as a CSV file  
with open(‘contact\_data.csv’, ‘w’, newline=‘’) as csv\_file:  
writer = csv.DictWriter(csv\_file, fieldnames=properties + [‘engagements’])  
writer.writeheader()  
writer.writerows(data)

---

<div class="post-metadata">

**Author:** ![GRajput](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/grajput/32/102020_2.png) [@GRajput](https://community.hubspot.com/u/GRajput)\
**Post date:** [April 20, 2023, 12:09pm UTC](https://community.hubspot.com/t/contacts-history/79233/6 "2023-04-20T12:09:22Z")

</div>

Hi @StephaneBadel

Yes, you can retrieve contact history data from HubSpot using the HubSpot API and then analyze it using Python and Pandas.  
To retrieve contact history data, you can use the `GET /contacts/v1/lists/all/contacts/all` endpoint of the HubSpot Contacts API. This endpoint returns a paginated list of contacts along with their associated timeline events, such as form submissions, email opens, and page views.  
Here is an example Python script using the `requests` and `pandas` libraries to retrieve contact history data and analyze it:

import requests  
import pandas as pd

# Set up the request headers and query parameters  
headers = {‘Authorization’: ‘Bearer YOUR\_HUBSPOT\_API\_KEY’}  
params = {‘property’: [‘email’, ‘firstname’, ‘lastname’, ‘hs\_object\_id’], ‘propertyMode’: ‘value\_only’}

# Make the initial request to get the first page of contacts  
url = ‘[https://api.hubapi.com/contacts/v1/lists/all/contacts/all](https://api.hubapi.com/contacts/v1/lists/all/contacts/all)’  
response = requests.get(url, headers=headers, params=params)  
data = response.json()

# Paginate through the results to get all contacts  
while True:  
# Extract the contact and event data from the response  
contacts = data[‘contacts’]  
events = [event for contact in contacts for event in contact[‘timeline’][‘events’]]

# Convert the event data to a Pandas DataFrame  
events\_df = pd.json\_normalize(events)

# Do further analysis on the event data using Pandas  
# For example, group the events by type and count the occurrences of each type  
event\_counts = events\_df.groupby(‘eventTypeId’)[‘eventId’].count()

# Make the next request if there are more pages  
if ‘has-more’ in data and data[‘has-more’]:  
params[‘vidOffset’] = data[‘vid-offset’]  
response = requests.get(url, headers=headers, params=params)  
data = response.json()  
else:  
break  
In this example, the `Authorization` header should be replaced with your HubSpot API key. You can also adjust the `property` query parameter to include additional contact properties that you want to retrieve.  
The code above retrieves all contacts and their associated events, then converts the event data to a Pandas DataFrame and performs some basic analysis on it, such as counting the occurrences of each event type. You can modify the code to perform any other analysis you need on the contact history data.

Please mark it as SOLUTION ACCEPTED if you like the solution.

Thank you!

---

<div class="post-metadata">

**Author:** ![StephaneBadel](https://avatars.discourse-cdn.com/v4/letter/s/9dc877/32.png) [@StephaneBadel](https://community.hubspot.com/u/StephaneBadel)\
**Post date:** [April 21, 2023, 3:08am UTC](https://community.hubspot.com/t/contacts-history/79233/7 "2023-04-21T03:08:47Z")

</div>

Thanks a lot for your answer GRajput! One thing, I thought API Key was deprecated and should be replaced by an app token?

Or am I missing something here?

Thanks!

---

<div class="post-metadata">

**Author:** ![StephaneBadel](https://avatars.discourse-cdn.com/v4/letter/s/9dc877/32.png) [@StephaneBadel](https://community.hubspot.com/u/StephaneBadel)\
**Post date:** [April 25, 2023, 2:23am UTC](https://community.hubspot.com/t/contacts-history/79233/8 "2023-04-25T02:23:43Z")

</div>

Hello GRajput,

Any feedback? Thanks!

---

<div class="post-metadata">

**Author:** ![StephaneBadel](https://avatars.discourse-cdn.com/v4/letter/s/9dc877/32.png) [@StephaneBadel](https://community.hubspot.com/u/StephaneBadel)\
**Post date:** [June 7, 2023, 9:13am UTC](https://community.hubspot.com/t/contacts-history/79233/9 "2023-06-07T09:13:59Z")

</div>

Hello GRajput,

Any help on the 404 response?

Thanks

---

<div class="post-metadata">

**Author:** ![HHarrison9](https://avatars.discourse-cdn.com/v4/letter/h/c4cdca/32.png) [@HHarrison9](https://community.hubspot.com/u/HHarrison9)\
**Post date:** [October 14, 2023, 6:37am UTC](https://community.hubspot.com/t/contacts-history/79233/10 "2023-10-14T06:37:13Z")

</div>

Discord by default and only option is to search with Google which kicks you to a web browser directly opening to the Google search page for the phrase you’ve highlighted.

If this is something you would like to see, you could suggest it to Discord through their support channels [NamesDio](https://namesdio.com/), or community forums