Tech logs: HubSpot's Undocumented Image Resizing API

# URL type 1 - for featured images
https://cdn2.hubspot.net/hubfs/${PORTAL_ID}/${IMG_NAME}.jpg

# URL type 2 - for featured images
https://f.hubspotusercontent40.net/hubfs/${PORTAL_ID}/${IMG_NAME}.jpg

# NOTE: this might vary on your portal.
# The HubSpot File Manager suggest that you can also use branded domain name from the site for these two types
https://brand.com/hubfs/${PORTAL_ID}/${IMG_NAME}.jpg
# A third image type for author icons also exists, but won't be covered here as they are already small thumbnails.

Here I should note that these input URLs might vary based on your Portal and the source of the URLs. Check the API response you're looking at or HubSpot's media manager to find your input URLs. The output URLs might also vary. If you don't know what they are, replicate the template test I did in the previous section.

For the URL types 1 and 2 that we encountered it was possible to extract the PORTAL_ID and IMG_NAME from the Blog API responses with a regular expression, and then reconstruct a URL of the output form which we saw in the last section. The resulting transformed URL succeeds in loading images of the requested size: mission accomplished.

The following function on CodePen implements this transformation. Feel free to adapt it to your needs!

Caveats

There are some caveats to mention:

1. 'Undocumented' probably also means 'unsupported'. If HubSpot would break or change this functionality, and you can not respond quickly to revert the image URLs to their original form, images on your site could break without warning. See Alternatives & Improvements on how to mitigate this situation.
2. Give it some time. For some images it took some time (tens of seconds to minutes) from the first requested resized image in order for the actual resized image to appear. This could be due to scheduled resizing processes or variable time in CDN distribution at HubSpot's side.
3. No complete support. For some reason unknown to us this resizing only works for ~90% of the images where we tried it on. For some images the original resolution was returned, no matter what size parameters we gave it.
4. Only width & height controls. Other Image optimisation APIs pformat format (e.g. WebP) and quality parameters. This API doesn't clearly expose those. Note: it seems that HubSpot is serving WebP by default when using these resizing options APIs.

Alternatives & improvements

One important improvement on the above code would be to load images via JavaScript. In such a case, you could detect potential 400 or 500 error codes when HubSpot changed this API's functionality or signature, and you could automatically insert the original URL instead.

Another sure-fire approach to the whole problem would be to implement a microservice that scrapes the images from the HubSpot Blog API and uploads them to Contentful on a regular basis. This would protect you from API changes. However, this approach also has disadvantages. One, it's more costly to architect & develop. Two, it's more costly to operate because you need to manage an extra service. Still, it could be a solution if you need a massive number of HubSpot-sourced images on an external web page and you have a very low fault tolerance. At least one person on the internet has done something similar.

And with that thought put out there, this post is a wrap! I hope it can help someone who – like me – Googled for a solution to this problem unsuccessfully. It is pretty annoying that HubSpot does not have a documented API for resizing images.

Enjoyed the blog? Perhaps you would be interested in working at Columbia Road! We're constantly looking for nice and skilful people to work with – and to have some good banter with! If you are interested in reading more about the work we do at Columbia Road, have a look at our client cases.