APIs & Integrations

enrico_bianchet
Member

Property changed by use of a HubSpot API endpoint

SOLVE

Hi,

i'm looking for a way to understand if a contact property is changed by use of a HubSpot API endpoint.

The scope: save a contact in a static list if a property was changed but NOT trought a API endpoint.

 

Thanks for your time.

Enrico

0 Upvotes
1 Accepted solution
jackcoldrick
Solution
HubSpot Employee
HubSpot Employee

Property changed by use of a HubSpot API endpoint

SOLVE

Hi @enrico_bianchet,

There is no way in app to achieve this as we do not allow you to create lists based on the source of a change to a property. However you could do something like this:

 

If you get a contact or contacts using either the "get a contact" or "get all contacts" endpoints you can specify the properties to retrieve and whether or not you want the current value or the historic values over time. The historic values would show the source of the change.

 

For example if I get all contacts as per the request below:

 

https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey={{apikey}}&count=1&propertyMode=value_and_history
 
It returns some JSON relating to a contact in my portal. Within the response is a "properties" object which contains information on the properties requested. If I look at the "lastname" property I can see:
 
"lastname": {
	"value": "inapp updated last name",
	"versions": [
		{
			"value": "inapp updated last name",
			"source-type": "CRM_UI",
			"source-id": "jcoldrick@hubspot.com",
			"source-label": null,
			"timestamp": 1575449293044,
			"selected": false
                        },
		{
			"value": "apiupdated last name",
			"source-type": "API",
			"source-id": null,
			"source-label": null,
			"timestamp": 1575449251365,
			"selected": false
                        },
		{
			"value": "Coldrick",
			"source-type": "FORM",
			"source-id": "2b9bee89-c8aa-452d-9ac8-947ba31c602c",
			"source-label": "Last name",
			"timestamp": 1566802103313,
			"selected": false
                        }
	}
}
 

 

Notice the "source-type" attribute. If a change is made within the CRM/via the UI it will have a value of "CRM_UI". If a change is made via the API it will have a value of "API". If a change is made via a form it will have a value of "FORM". This would help you to identify the source fo the most recent change and you could then use our  Contact Lists API to create/add them to the appropriate static list.

 

However this would all need to be done using our APIs as the above functionality is not possible within the app UI itself. It is also worth noting that using our Contacts API will not return ALL properties for the contact. By default it will only return "firstname", "lastname" and "lastmodifieddate". You can use the "property" parameter in the URL to retrieve all of the properties you wish.

 

I hope this helps!

 

Jack

 

Jack Coldrick
Solutions Engineer @ HubSpot
Add me on LinkedIn

View solution in original post

6 Replies 6
jackcoldrick
Solution
HubSpot Employee
HubSpot Employee

Property changed by use of a HubSpot API endpoint

SOLVE

Hi @enrico_bianchet,

There is no way in app to achieve this as we do not allow you to create lists based on the source of a change to a property. However you could do something like this:

 

If you get a contact or contacts using either the "get a contact" or "get all contacts" endpoints you can specify the properties to retrieve and whether or not you want the current value or the historic values over time. The historic values would show the source of the change.

 

For example if I get all contacts as per the request below:

 

https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey={{apikey}}&count=1&propertyMode=value_and_history
 
It returns some JSON relating to a contact in my portal. Within the response is a "properties" object which contains information on the properties requested. If I look at the "lastname" property I can see:
 
"lastname": {
	"value": "inapp updated last name",
	"versions": [
		{
			"value": "inapp updated last name",
			"source-type": "CRM_UI",
			"source-id": "jcoldrick@hubspot.com",
			"source-label": null,
			"timestamp": 1575449293044,
			"selected": false
                        },
		{
			"value": "apiupdated last name",
			"source-type": "API",
			"source-id": null,
			"source-label": null,
			"timestamp": 1575449251365,
			"selected": false
                        },
		{
			"value": "Coldrick",
			"source-type": "FORM",
			"source-id": "2b9bee89-c8aa-452d-9ac8-947ba31c602c",
			"source-label": "Last name",
			"timestamp": 1566802103313,
			"selected": false
                        }
	}
}
 

 

Notice the "source-type" attribute. If a change is made within the CRM/via the UI it will have a value of "CRM_UI". If a change is made via the API it will have a value of "API". If a change is made via a form it will have a value of "FORM". This would help you to identify the source fo the most recent change and you could then use our  Contact Lists API to create/add them to the appropriate static list.

 

However this would all need to be done using our APIs as the above functionality is not possible within the app UI itself. It is also worth noting that using our Contacts API will not return ALL properties for the contact. By default it will only return "firstname", "lastname" and "lastmodifieddate". You can use the "property" parameter in the URL to retrieve all of the properties you wish.

 

I hope this helps!

 

Jack

 

Jack Coldrick
Solutions Engineer @ HubSpot
Add me on LinkedIn
enrico_bianchet
Member

Property changed by use of a HubSpot API endpoint

SOLVE

Hi @jackcoldrick , which is the difference in the company data return data?

from your documentation i can see

"properties": {
    "description": {
      "value": "A far better description than before",
      "timestamp": 1403218621658,
      "source": "API",
      "sourceId": null,
      "versions": [
        {
          "name": "description",
          "value": "A far better description than before",
          "timestamp": 1403218621658,
          "source": "API",
          "sourceVid": [
            
          ]
        }
      ]
    }, ......

i can the see the field "source", i don't understand if track the last modified source from the field as i can see in version.
In the contact data i can't see something similar.

In general, Which is the The order of the versions array?

First value is always the last source has modified the field?

Thanks
Enrico

0 Upvotes
jackcoldrick
HubSpot Employee
HubSpot Employee

Property changed by use of a HubSpot API endpoint

SOLVE

Hi @enrico_bianchet,

 

In all cases the history will be returned in reverse chronological order with the latest change showing first. If you are using the Companies API however there are subtle differences between the way it can be used vs the Contacts API.

 

1) CONTACTS API

For example if we were to "get a contact by ID"  we could easily request specific properties alongside the historic values of those properties by using the "property=" parameter in the query string.

 

2) COMPANY API

If we were to "get a company by ID" we are unable to specify the properties we want nor can we request historic values. It will always return all properties with the most recent value for that Company Object.

 

If you are "getting all companies" in a portal you can retrieve specific properties and their historic values using the "propertiesWithHistory" parameter in your query string. This would return the current and historic values in reverse chronlological order. 

 

For example If I make a request like this:

 

https://api.hubapi.com/companies/v2/companies/paged?hapikey={{apikey}}&propertiesWithHistory=description&limit=1

 

It returns:

 

"properties": {
	"description": {
		"value": "This is the most recent company description",
		"timestamp": 1575635475752,
		"source": "CRM_UI",
		"sourceId": "jackcoldrick-apitesting@gmail.com",
		"versions": [
			{
				"name": "description",
				"value": "This is the most recent company description",
				"timestamp": 1575635475752,
				"sourceId": "jackcoldrick-apitesting@gmail.com",
				"source": "CRM_UI",
				"sourceVid": []
                        },
			{
				"name": "description",
				"value": "This is another update to the company description",
				"timestamp": 1549745479426,
				"sourceId": "BidenPropertyMappings",
				"source": "BIDEN",
				"sourceVid": []
                        },
			{
				"name": "description",
				"value": "This is an update to the company description",
				"timestamp": 1507121289812,
				"sourceId": "BidenPropertyMappings",
				"source": "BIDEN",
				"sourceVid": []
                        },
			{
				"name": "description",
				"value": "This is a company description",
				"timestamp": 1500364875420,
				"sourceId": "jackcoldrick-apitesting@gmail.com",
				"source": "BIDEN",
				"sourceVid": []
                        }
                    ]
	}
}

 

I hope this helps clear up any confusion.

 

Jack

 

 

Jack Coldrick
Solutions Engineer @ HubSpot
Add me on LinkedIn
0 Upvotes
enrico_bianchet
Member

Property changed by use of a HubSpot API endpoint

SOLVE

Hi @jackcoldrick,

thanks for your answer.

You gave me the most important information "In all cases the history will be returned in reverse chronological order with the latest change showing first. "

Just for better understand in the case of company data i'm not sure why use the field revisions when the same last event information seems to be available at base level of the field properties description in this case

"properties": {
	"description": {
		"value": "This is the most recent company description",
		"timestamp": 1575635475752,
		"source": "CRM_UI",
		"sourceId": "jackcoldrick-apitesting@gmail.com",
		"versions": [
			{
				"name": "description",
				"value": "This is the most recent company description",
				"timestamp": 1575635475752,
				"sourceId": "jackcoldrick-apitesting@gmail.com",
				"source": "CRM_UI",
				"sourceVid": []
                        },

Thanks again

Enrico

0 Upvotes
enrico_bianchet
Member

Property changed by use of a HubSpot API endpoint

SOLVE

Thanks@jackcoldrick .

Your suggestion will be very useful as starting point.

Enrico

0 Upvotes
himanshurauthan
Thought Leader | Elite Partner
Thought Leader | Elite Partner

Property changed by use of a HubSpot API endpoint

SOLVE

Hello @enrico_bianchet 

 

It seems that we can only check and compare on values the property holds. There is no way to create a list based on source of property change. It can only be viewed from the contact detail page.

 

Thanks

Digital Marketing & Inbound Expert In Growth Hacking Technology