GET
/
contacts
/
v1
/
contact
/
byUtk
/
batch
/
Get a batch of contacts by user token
curl --request GET \
  --url https://api.hubapi.com/contacts/v1/contact/byUtk/batch/
"\nExample GET URL:\nhttps://api.hubapi.com/contacts/v1/contact/utks/batch/?utk=ea02a4db247fdc4c97e350a0d2124174&utk=6084e7de6a2b6f11f31d976090c49841\n\n\nExample JSON output:\n{\n    \"ea02a4db247fdc4c97e350a0d2124174\": {\n        \"vid\": 12629874,\n        \"canonical-vid\": 12629874,\n        \"merged-vids\": [],\n        \"portal-id\": 62515,\n        \"is-contact\": true,\n        \"properties\": {\n            \"hs_is_unworked\": {\n                \"value\": \"true\"\n            },\n            \"hs_analytics_last_url\": {\n                \"value\": \"https://share.hsforms.com/1VgpxBDisTgyvXpzNVSYkhQ1c8j\"\n            },\n            \"ip_state\": {\n                \"value\": \"new hampshire\"\n            },\n            \"hs_legal_basis\": {\n                \"value\": \"Freely given consent from contact\"\n            },\n            \"num_unique_conversion_events\": {\n                \"value\": \"1\"\n            },\n            \"ip_country\": {\n                \"value\": \"united states\"\n            },\n            \"hs_analytics_revenue\": {\n                \"value\": \"0.0\"\n            },\n            \"hs_social_num_broadcast_clicks\": {\n                \"value\": \"0\"\n            },\n            \"createdate\": {\n                \"value\": \"1587160369528\"\n            },\n            \"hs_analytics_last_timestamp\": {\n                \"value\": \"1587482449156\"\n            },\n            \"hs_analytics_num_visits\": {\n                \"value\": \"10\"\n            },\n            \"ip_state_code\": {\n                \"value\": \"nh\"\n            },\n            \"recent_conversion_event_name\": {\n                \"value\": \"New Example Form\"\n            },\n            \"hs_social_linkedin_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_analytics_last_visit_timestamp\": {\n                \"value\": \"1587482434503\"\n            },\n            \"hs_analytics_source\": {\n                \"value\": \"DIRECT_TRAFFIC\"\n            },\n            \"hs_email_domain\": {\n                \"value\": \"hubspot.com\"\n            },\n            \"hs_analytics_num_page_views\": {\n                \"value\": \"19\"\n            },\n            \"email\": {\n                \"value\": \"testcontact@hubspot.com\"\n            },\n            \"hs_analytics_first_url\": {\n                \"value\": \"https://share.hsforms.com/1A46BnFJiTBOFUIyr44xDCQ1c8j\"\n            },\n            \"ip_country_code\": {\n                \"value\": \"us\"\n            },\n            \"hubspotscore\": {\n                \"value\": \"0\"\n            },\n            \"hs_analytics_first_visit_timestamp\": {\n                \"value\": \"1572897038107\"\n            },\n            \"lastmodifieddate\": {\n                \"value\": \"1591530298022\"\n            },\n            \"hs_analytics_first_timestamp\": {\n                \"value\": \"1572897038107\"\n            },\n            \"hs_ip_timezone\": {\n                \"value\": \"america_slash_new_york\"\n            },\n            \"first_conversion_date\": {\n                \"value\": \"1587160368382\"\n            },\n            \"hs_social_google_plus_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_calculated_form_submissions\": {\n                \"value\": \"560a7104-38ac-4e0c-af5e-9ccd55262485::1587160368382;560a7104-38ac-4e0c-af5e-9ccd55262485::1587416418860\"\n            },\n            \"hs_analytics_average_page_views\": {\n                \"value\": \"1\"\n            },\n            \"hs_social_facebook_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_predictivescoringtier\": {\n                \"value\": \"tier_1\"\n            },\n            \"hs_is_contact\": {\n                \"value\": \"true\"\n            },\n            \"ip_city\": {\n                \"value\": \"concord\"\n            },\n            \"hs_predictivecontactscore_v2\": {\n                \"value\": \"3.79\"\n            },\n            \"num_conversion_events\": {\n                \"value\": \"2\"\n            },\n            \"example_score_property\": {\n                \"value\": \"0\"\n            },\n            \"example_file_property\": {\n                \"value\": \"https://api.hubspot.com/form-integrations/v1/uploaded-files/signed-url-redirect/28552456805?portalId=62515&sign=U6ntv5pwmfvaqwWmYa_ZmD2HJuY%3D&conversionId=91da3e05-b7a0-465f-a1d6-1b6e71c4d88a&filename=91da3e05-b7a0-465f-a1d6-1b6e71c4d88a-example_file_property-testfile.txt\"\n            },\n            \"recent_conversion_date\": {\n                \"value\": \"1587416418860\"\n            },\n            \"hs_object_id\": {\n                \"value\": \"12629874\"\n            },\n            \"hs_analytics_num_event_completions\": {\n                \"value\": \"0\"\n            },\n            \"hs_social_twitter_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_lifecyclestage_lead_date\": {\n                \"value\": \"1587160369795\"\n            },\n            \"hs_analytics_source_data_1\": {\n                \"value\": \"share.hsforms.com/62515/038e819c-5262-4c13-8550-8cabe38c4309\"\n            },\n            \"lifecyclestage\": {\n                \"value\": \"lead\"\n            },\n            \"first_conversion_event_name\": {\n                \"value\": \"New Example Form\"\n            }\n        },\n        \"form-submissions\": [\n            {\n                \"conversion-id\": \"91da3e05-b7a0-465f-a1d6-1b6e71c4d88a\",\n                \"timestamp\": 1587416418860,\n                \"form-id\": \"560a7104-38ac-4e0c-af5e-9ccd55262485\",\n                \"portal-id\": 62515,\n                \"page-url\": \"https://share.hsforms.com/1VgpxBDisTgyvXpzNVSYkhQ1c8j\",\n                \"title\": \"New Example Form\",\n                \"form-type\": \"HUBSPOT\",\n                \"contact-associated-by\": [\n                    \"EMAIL\"\n                ],\n                \"meta-data\": []\n            }\n        ],\n        \"identity-profiles\": [\n            {\n                \"vid\": 12629874,\n                \"saved-at-timestamp\": 1587160369547,\n                \"deleted-changed-timestamp\": 0,\n                \"identities\": [\n                    {\n                        \"type\": \"EMAIL\",\n                        \"value\": \"testcontact@hubspot.com\",\n                        \"timestamp\": 1587160368382,\n                        \"is-primary\": true\n                    },\n                    {\n                        \"type\": \"LEAD_GUID\",\n                        \"value\": \"e9190159-9a06-4553-acab-d13b6bf99475\",\n                        \"timestamp\": 1587160369545\n                    }\n                ]\n            }\n        ],\n        \"merge-audits\": []\n    },\n    \"6084e7de6a2b6f11f31d976090c49841\": {\n        \"vid\": 12629924,\n        \"canonical-vid\": 12590024,\n        \"merged-vids\": [],\n        \"portal-id\": 62515,\n        \"is-contact\": true,\n        \"properties\": {\n            \"hs_analytics_last_url\": {\n                \"value\": \"https://share.hsforms.com/1A46BnFJiTBOFUIyr44xDCQ1c8j\"\n            },\n            \"num_unique_conversion_events\": {\n                \"value\": \"1\"\n            },\n            \"hs_email_quarantined\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_revenue\": {\n                \"value\": \"0.0\"\n            },\n            \"createdate\": {\n                \"value\": \"1565113366204\"\n            },\n            \"hs_email_optout_5375287\": {\n                \"value\": \"\"\n            },\n            \"hs_email_optout\": {\n                \"value\": \"true\"\n            },\n            \"recent_conversion_event_name\": {\n                \"value\": \"Example form with file upload\"\n            },\n            \"hs_analytics_num_page_views\": {\n                \"value\": \"1\"\n            },\n            \"state\": {\n                \"value\": \"MA\"\n            },\n            \"zip\": {\n                \"value\": \"02139\"\n            },\n            \"hs_email_optout_4744389\": {\n                \"value\": \"\"\n            },\n            \"hubspotscore\": {\n                \"value\": \"0\"\n            },\n            \"hs_ip_timezone\": {\n                \"value\": \"america_slash_new_york\"\n            },\n            \"hs_email_optout_5583924\": {\n                \"value\": \"\"\n            },\n            \"first_conversion_date\": {\n                \"value\": \"1572900798882\"\n            },\n            \"upload_a_file\": {\n                \"value\": \"https://api.hubspot.com/form-integrations/v1/uploaded-files/signed-url-redirect/20128659661?portalId=62515&sign=sXEkvOBg6C5eiGuxOxrMYWCQb8k%3D&conversionId=unused&filename=1eac2f96-f4b7-4312-a4c3-9962382207f2-upload_a_file-test_file.txt\"\n            },\n            \"ip_zipcode\": {\n                \"value\": \"\"\n            },\n            \"hs_lifecyclestage_subscriber_date\": {\n                \"value\": \"1565113366204\"\n            },\n            \"hs_email_optout_1281663\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_average_page_views\": {\n                \"value\": \"1\"\n            },\n            \"lastname\": {\n                \"value\": \"Schnitt\"\n            },\n            \"hs_is_contact\": {\n                \"value\": \"true\"\n            },\n            \"phone\": {\n                \"value\": \"555-122-2323\"\n            },\n            \"hs_predictivecontactscore_v2\": {\n                \"value\": \"1.0\"\n            },\n            \"num_conversion_events\": {\n                \"value\": \"1\"\n            },\n            \"hs_object_id\": {\n                \"value\": \"12590024\"\n            },\n            \"ip_latlon\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_num_event_completions\": {\n                \"value\": \"0\"\n            },\n            \"hs_lifecyclestage_lead_date\": {\n                \"value\": \"1572900800785\"\n            },\n            \"first_conversion_event_name\": {\n                \"value\": \"Example form with file upload\"\n            },\n            \"hs_email_optout_2849\": {\n                \"value\": \"\"\n            },\n            \"hs_email_hard_bounce_reason_enum\": {\n                \"value\": \"OTHER\"\n            },\n            \"firstname\": {\n                \"value\": \"Matt\"\n            },\n            \"ip_state\": {\n                \"value\": \"new hampshire\"\n            },\n            \"city\": {\n                \"value\": \"Cambridge\"\n            },\n            \"hs_email_optout_354586\": {\n                \"value\": \"\"\n            },\n            \"ip_country\": {\n                \"value\": \"united states\"\n            },\n            \"hs_social_num_broadcast_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_email_recipient_fatigue_recovery_time\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_last_timestamp\": {\n                \"value\": \"1572900738828\"\n            },\n            \"hs_email_optout_6914043\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_num_visits\": {\n                \"value\": \"1\"\n            },\n            \"ip_state_code\": {\n                \"value\": \"nh\"\n            },\n            \"hs_email_optout_5476312\": {\n                \"value\": \"\"\n            },\n            \"hs_social_linkedin_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_email_optout_6497985\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_last_visit_timestamp\": {\n                \"value\": \"1572900738828\"\n            },\n            \"hs_social_last_engagement\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_source\": {\n                \"value\": \"OFFLINE\"\n            },\n            \"hs_searchable_calculated_phone_number\": {\n                \"value\": \"5551222323\"\n            },\n            \"hs_email_domain\": {\n                \"value\": \"hubspot.com\"\n            },\n            \"hs_analytics_first_touch_converting_campaign\": {\n                \"value\": \"\"\n            },\n            \"company\": {\n                \"value\": \"HubSpot\"\n            },\n            \"email\": {\n                \"value\": \"test@hubspot.com\"\n            },\n            \"hs_analytics_first_url\": {\n                \"value\": \"https://share.hsforms.com/1A46BnFJiTBOFUIyr44xDCQ1c8j\"\n            },\n            \"website\": {\n                \"value\": \"http://hubspot.com\"\n            },\n            \"ip_country_code\": {\n                \"value\": \"us\"\n            },\n            \"address\": {\n                \"value\": \"25 First Street\"\n            },\n            \"hs_analytics_first_visit_timestamp\": {\n                \"value\": \"1572900738828\"\n            },\n            \"lastmodifieddate\": {\n                \"value\": \"1591440743208\"\n            },\n            \"hs_analytics_first_timestamp\": {\n                \"value\": \"1565113366204\"\n            },\n            \"hs_social_google_plus_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_analytics_last_touch_converting_campaign\": {\n                \"value\": \"\"\n            },\n            \"hs_calculated_form_submissions\": {\n                \"value\": \"038e819c-5262-4c13-8550-8cabe38c4309::1572900798882\"\n            },\n            \"hs_email_optout_4447431\": {\n                \"value\": \"\"\n            },\n            \"hs_email_optout_230318\": {\n                \"value\": \"\"\n            },\n            \"hs_social_facebook_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_predictivescoringtier\": {\n                \"value\": \"tier_2\"\n            },\n            \"ip_city\": {\n                \"value\": \"concord\"\n            },\n            \"example_score_property\": {\n                \"value\": \"0\"\n            },\n            \"recent_conversion_date\": {\n                \"value\": \"1572900798882\"\n            },\n            \"hs_social_twitter_clicks\": {\n                \"value\": \"0\"\n            },\n            \"hs_analytics_source_data_2\": {\n                \"value\": \"\"\n            },\n            \"hs_analytics_source_data_1\": {\n                \"value\": \"API\"\n            },\n            \"lifecyclestage\": {\n                \"value\": \"lead\"\n            },\n            \"hs_email_optout_5479310\": {\n                \"value\": \"\"\n            }\n        },\n        \"form-submissions\": [\n            {\n                \"conversion-id\": \"1eac2f96-f4b7-4312-a4c3-9962382207f2\",\n                \"timestamp\": 1572900798882,\n                \"form-id\": \"038e819c-5262-4c13-8550-8cabe38c4309\",\n                \"portal-id\": 62515,\n                \"page-url\": \"https://share.hsforms.com/1A46BnFJiTBOFUIyr44xDCQ1c8j\",\n                \"title\": \"Example form with file upload\",\n                \"form-type\": \"HUBSPOT\",\n                \"contact-associated-by\": [\n                    \"EMAIL\"\n                ],\n                \"meta-data\": []\n            }\n        ],\n        \"identity-profiles\": [\n            {\n                \"vid\": 12629924,\n                \"saved-at-timestamp\": 1572900800660,\n                \"deleted-changed-timestamp\": 0,\n                \"identities\": []\n            },\n            {\n                \"vid\": 12590024,\n                \"saved-at-timestamp\": 1572900800660,\n                \"deleted-changed-timestamp\": 0,\n                \"identities\": [\n                    {\n                        \"type\": \"EMAIL\",\n                        \"value\": \"test@hubspot.com\",\n                        \"timestamp\": 1565113366204,\n                        \"is-primary\": true\n                    },\n                    {\n                        \"type\": \"LEAD_GUID\",\n                        \"value\": \"0cc8065d-5db2-4fe6-a6a1-0335f89f130b\",\n                        \"timestamp\": 1565113366213\n                    }\n                ]\n            }\n        ],\n        \"merge-audits\": []\n    }\n}"

Query Parameters

fromTimestamp
string
required

A millisecond timestamp representing the start of the time period that you want the stats for.Note: the time between fromTimestamp and toTimestamp must be 2 years or less.

toTimestamp
string
required

A millisecond timestamp representing the end of the time period that you want the stats for.Note: the time between fromTimestamp and toTimestamp must be 2 years or less.

aggregationProperty
string

A second optional property to further breakdown the lifecycle stage buckets. This must be an enumerated property with 20 or fewer options.

Response

200 - application/json

Successful response - Returns the number of contacts that entered the individual lifecycle stages during the provided time period

The response is of type object.