Breaking Change: Removed Support for Referencing Custom Object Types by Base Name

[hseligson]

We are removing the undocumented support for requesting custom object types by their base name (GET/crm/v3/objects/{baseName}) in HubSpot public APIs. All custom object types must be referenced by their unique identifier (object type ID, fully qualified name, or short-hand custom object type name) to ensure clarity and consistency in API interactions.

What's changing?

Previously, referring to custom object types by their base name in API requests was possible. For instance, if both a HubSpot-defined object type and a custom object type were named "vendor," using the base name would cause confusion and result in unexpected behavior in API responses.
As a result, the base name format will no longer be supported after April 29th, 2025. Here is an example using the base name "vendor."

// Example

GET /crm/v3/objects/vendor

Instead, you must use one of the following formats for your request:

• Using the short-hand custom object type name, aka GET /crm/v3/objects/p_{object_name}

// Example

GET /crm/v3/objects/p_vendor

• Using the GET /crm/v3/objects/objectTypeId

// Example

GET /crm/v3/objects/2-123

• Using the GET /crm/v3/objects/fullyQualifiedName

// Example

GET /crm/v3/objects/p345_vendor

 

What does this mean for developers?

Failing to update your custom object type API calls that refer to their base name instead of their unique identifier (object type ID, fully qualified name, or short-hand custom object type name) will result in unexpected errors or a failed request, returning a 400 error response:

{
status:"error",
message:"Unable to infer object type from: vendor",
correlationId:"cfb4f7d2-c7dc-4b91-a5f1-b0fa417ae2e8"
}

We recommend the following next steps:

• Review and update your API integrations to ensure that all API requests to custom object types comply with the documented requirements and no longer refer to a custom object type by its base name.
• Please refer to our API Documentation for more information on retrieving custom object type data and understanding the available reference formats.

When is it happening?

This change will go into effect on April 29th, 2025.

Questions or comments? Join the forum below for a peer-to-peer discussion.

[evaldas]

There used to be an issue with using the base name if the custom object contained multiple words (i.e. "basketball_teams"). Will the short-hand custom object type name (i.e. "p_basketball_teams") address the multiple word issue?

[hseligson]

Hey @evaldas - thank you for your comment! Would you mind telling me more about what sort of issues you would face when leveraging multiple words? I'd love to know more!

[evaldas]

Hey @hseligson  - sure!

If a custom object was simply named "Vendors" and you used the base name in the request it worked fine because it's a single word:

// Example

GET /crm/v3/objects/vendor

However, if the custom object is multiple words, i.e. "Food Vendors", then it would return an error:

// Example

GET /crm/v3/objects/food_vendor

"status":"error",

"messages":"Unable to infer object type from: food_vendor"

[hseligson]

@evaldas - thank you for the additional context and for sharing the error message! 
I tested this with the example "food_vendor" and received the same error when requesting crm/v3/objects/food_vendors.
However, when I modified the request to the formats we documented in our docs, I received a 200 with the following requests:

• crm/v3/objects/p_food_vendors
• crm/v3/objects/{objectTypeId}
• crm/v3/objects/p{portalId}_food_vendors

I suggest leveraging the formats we have documented to avoid errors. Please feel free to let me know if you have any additional concerns.

[BRVNARISHIGE]

Does this change also apply to references to custom objects in HubL? (e.g., the crm_object function)

[hseligson]

@BRVNARISHIGE - This is a great question, and I'll follow up with our product team for confirmation.