Is there a way to tell if I have a Hubspot contact on my external site?

Highlighted
Regular Contributor

I started working with the "get contact by token" here: https://developers.hubspot.com/docs/methods/contacts/get_contact_by_utk
Then realized I'd be exceeding the 5% error rate as most visitors are not Hubspot contacts.

I'd like to dynamically unlock certain content for confirmed Hubspot contacts on our website, and ultimately further customizations down the road. Right now, I just need to know if a user with a hubspotutk cookie is a contact or not.

Is there a way? If there isn't -- -- -- why not?

Thanks.

Reply
0 Upvotes
9 Replies 9
Highlighted
HubSpot Moderator

Hi @IVRtechCMO,

If you make a request to that endpoint, it's possible for a usertoken to be associated with a contact record, or with a pseudo-record known as a visitor. This visitor record is not a real contact (i.e. it's not visible in-app) but it still associated with analytics data and some other information. For most scenarios, if you can pull a usertoken from a visitor's browser, you can pull either a full contact record or a visitor record. You can distinguish between the two by looking at the is-contact field; for example, if you make a request to this endpoint that returns a visitor record, you'll see a response similar to the following:

{
vid:1234,
canonical-vid:1234,
merged-vids:[ ],
portal-id:xxxxxx,
is-contact:false,
profile-token:"xxxxxxxxxx",
profile-url:"xxxxxxxxxx",
properties:{ },
form-submissions:[ ],
list-memberships:[ ],
identity-profiles:[ ],
merge-audits:[ ]}

If is-contact is false, then there is no contact record in the UI, and you can treat the visitor as anonymous.

Reply
0 Upvotes
Highlighted
Regular Contributor

Understood. However, I was seeing the 404 response (as indicated by the docs) when hitting the endpoint with a usertoken that's not a contact.

Reply
0 Upvotes
Highlighted
HubSpot Moderator

Hi @IVRtechCMO,

Gotcha; that should be fairly rare. The most common scenario where that would happen is a visitor's first visit to your site; the usertoken is created instantly client side, but it takes a few seconds for the corresponding visitor record to be created in HubSpot. Making a request to pull the contact by usertoken during that window will result in a 404.

The best way to avoid that is to check for the hubspotutk cookie server side, and only try to pull the contact record if it exists when visitor is navigating to your site. This will reduce the likelihood that you're requesting a contact that doesn't yet exist.

Reply
0 Upvotes
Highlighted
Regular Contributor

That's the documented behavior of the API, a 404 if the token is not a contact.

Reply
0 Upvotes
Highlighted
HubSpot Moderator

Hi @IVRtechCMO,

That's true; but visitor records who haven't yet become contacts should still succeed and return a visitor record. Can you give me your Hub ID so that I can create an example record?

Reply
0 Upvotes
Highlighted
Regular Contributor

I don't think you're understanding the business logic here. I want to know if I have a contact so that I can programmatically display different content to them. In this use case, wouldn't a "visitor record" be a false positive?

The Hub ID is 1809254

Reply
0 Upvotes
Highlighted
HubSpot Moderator

Hi @IVRtechCMO,

You're correct that a visitor record would be a false positive; the implication here is that if a visitor record exists, your request will not 404. While it still doesn't give you any actual information about the contact, the fact that these records exist for most visitors with usertokens means that you likely don't have to worry about the error rate limits we have in place.

As an example, here's my usertoken: 95ca28c9725d11c8aad5d3678ba87cdb. If you try to grab my contact record, you should see a visitor record, not a 404, even though my contact record doesn't technically exist in app. Most of the time, when you have a visitor's usertoken, you're safe to call that endpoint without worrying about drastically increasing your error rate.

To address your initial question: The way to know if a usertoken corresponds to a contact record is to make a request to /contacts/v1/contact/utk/:contact_utk/profile and check the response to see if the is-contact field is true or false.

Reply
0 Upvotes
Highlighted
Regular Contributor

That makes some sense. However, on first visit -- before the token exists -- I'll rack up an error rate in excess of the endpoint maximum of 5%.

Reply
0 Upvotes
Highlighted
HubSpot Moderator

Hi @IVRtechCMO,

You should definitely prevent that request from being in situations where the token doesn't exist. This can happen on first visit, or if the visitor is explicitly blocking cookies. In the first visit situation, the tracking code will place the hubspotutk cookie when it loads and you should see it on the visitor's next page load.

Reply
0 Upvotes