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.
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.
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.
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?
Is there a way to tell if I have a Hubspot contact on my external site?
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?
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.
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:
.png "HubSpot Alumni"){kind=icon}
