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

​
Required Scopes

This API requires one of the following scopes:
  • crm.objects.contacts.read
  • content
  • crm.objects.contacts.write

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.