Catalog api response change -object entry removed "name": "Objects" and "group": "CRM"

Developer Support
1

Subject: Clarification on generic CRM v3 batch operation OpenAPI specification

Previously, HubSpot exposed a generic batch-create operation for CRM objects:

POST /crm/v3/objects/{objectType}/batch/create

Our understanding was that this operation used a common contract across standard and custom objects: the same path parameter, request and response structure, required fields, and general validation behavior. Our integration separately retrieves the selected object’s properties through HubSpot metadata and uses those to populate the request and response property fields.

We now see object-specific OpenAPI specifications for standard objects, while the generic CRM Objects definition appears available only for custom objects. Could you please clarify the following?

  1. Has the generic batch-create API contract intentionally been removed for standard CRM objects?
  2. Do Contact, Company, Deal, Ticket, Product, and Line Item batch-create operations differ at the API-contract level—for example, in path or query parameters, request/response schemas, required fields, validation behavior, associations, or error responses?
  3. If the operation contract remains functionally the same and only object properties differ, why was the generic CRM Objects specification/catalog entry replaced by object-specific specifications?
  4. What generic OpenAPI specification do you recommend for integrations that must support both standard and custom CRM objects?
  5. What is the stable discovery mechanism for the generic CRM Objects specification?
    • Is there a dedicated stable OpenAPI URL?
    • Is there a stable specification ID, tag, metadata attribute, or documented catalog query?
    • Is HubSpot planning to restore or provide a stable identifier for the generic CRM Objects specification?
  6. When was this change introduced? Please share the relevant changelog, release note, or OpenAPI specification/catalog change.

From our perspective, object properties are already handled through separate metadata calls. An object-specific OpenAPI document is therefore necessary only if the operation contract itself differs—not solely because objects such as Contacts, Companies, and Deals expose different properties.

We would appreciate confirmation on whether the per-object specifications reflect an actual API-contract difference or only a catalog/documentation restructuring.

What is the recommended stable discovery mechanism for the generic CRM Objects specification?
Is there a dedicated stable OpenAPI URL?
Is there a stable specification ID, tag, metadata attribute, or documented catalog query?
Is HubSpot planning to restore or provide a stable identifier for the generic CRM Objects spec?

2

I would separate two things here: the runtime CRM object API contract, and the OpenAPI metadata used for generated clients.

If only the name/group style metadata changed, I would not treat that as a runtime contract change. The safer integration shape is:

  1. Resolve the selected object from HubSpot object/property metadata.
  2. Build the batch payload from that object’s properties, not from the OpenAPI tag name.
  3. Keep one tested adapter for /{objectType}/batch/create, then run contract tests against at least contacts, deals, and one custom object.

If your codegen depends on those removed labels, I would pin the previous spec briefly and open a docs/spec issue with the exact spec URL and diff. If the API response itself changed, include the request ID, timestamp, object type, and before/after response in the Support ticket.

3

our concern is why “name”: “Objects” and “group”: “CRM” objects removed? which was returning structure. or i would say any reason to keep this generic structure only under custom object not with standard one.. provide me exact time when this change introduced - sharing link would be appreciated

6

Hi @ShubhangiPawar

From what I’ve seen, this looks more like a documentation/OpenAPI catalog change than a change to the underlying batch create endpoint itself. The generic endpoint (/crm/v3/objects/{objectType}/batch/create) still appears to follow the same overall pattern, with the main differences coming from the object metadata rather than the operation contract.

That said, I understand why this creates problems for integrations that rely on a single generic OpenAPI definition. Having separate specs for standard objects but a generic one for custom objects makes automated discovery and code generation much harder.

I’d be interested to hear from the HubSpot team whether this was an intentional documentation change or whether a stable generic specification (or identifier) is still planned. That would make maintaining integrations much simpler.

In the meantime, are you generating your client from the OpenAPI specs, or are you using the metadata APIs to build the request models dynamically? That context might help identify the best approach.

7

we are using catalog url for v3 version and group -CRM to fetch open api url. using this open api url we get generic endpoint or paths and structure. we are using seperate metadata api calls to fetch objects properties and schema of custom objects..

8

Hi @ShubhangiPawar
Thanks for the clarification. That helps me better understand your implementation.

So if I understand correctly, you’re using the generic CRM OpenAPI specification for the operation definitions, while relying on the metadata APIs to retrieve the object-specific properties and schemas. That seems like a sensible approach for supporting both standard and custom objects.

I’m interested to see what the HubSpot team recommends regarding the long-term, supported discovery mechanism for the generic specification.

9

Hi there @ShubhangiPawar !

Thanks for the detailed write-up! This is a great question and I wanted to make sure I got you accurate information before responding, so I checked in with the team. Here are the answers to your questions!

1. Has the generic batch-create API contract been intentionally removed for standard CRM objects?

No, the runtime API itself is unchanged. What changed was an internal restructuring of HubSpot’s API catalog (PAPIMAN), which happened around July 2, 2026. The generic “CRM Objects” catalog entry for standard objects no longer exists; each standard object now has its own object-specific spec entry. The generic entry remains available for custom objects.

2. Do standard object batch-create operations differ at the API-contract level?
No. The contract is the same across standard objects. Individual teams may introduce object-specific handling over time, but there are no current contract-level differences in path parameters, request/response schemas, required fields, or error responses.

3. Why was the generic spec replaced by object-specific specs?
This was a catalog cleanup, not a runtime API change. The generic “CRM Objects” entry was originally an inheritance artifact — it was never intended to be publicly exposed. It’s been replaced with object-specific specs to better reflect that each object type can have its own handling and metadata, even if the underlying contract is shared today.

4. What spec do you recommend for integrations supporting both standard and custom CRM objects?
For standard objects, point your codegen at the object-specific spec for each type (e.g., “Contacts” under CRM, “Deals” under CRM). The generated code will be functionally equivalent — it’s sourced from a different spec file, but the contract is the same. For custom objects, you can continue using the generic spec as before.

5. Stable discovery mechanism / changelog
This change wasn’t announced externally because it was treated as an internal catalog restructuring rather than a runtime API change. I understand that’s frustrating given how it affected your codegen workflow — I’m sorry for the disruption.

One additional note worth flagging: depending on which endpoint you used to fetch the API catalog, that endpoint may not be publicly documented on our docs site. Undocumented endpoints aren’t covered by HubSpot’s stability guarantees and are subject to change without notice — so it’s worth reviewing your discovery mechanism against what’s officially supported in our API Terms and Acceptable Use Policy.

Hope this helps clarify things. Let me know if you have follow-up questions and I’ll do my best to get you answers.

Cassie, Community Manager

10
Copilot said:

Thanks for the clarification.

Could you please confirm whether https://api.hubspot.com/public/api/spec/v1/specs is an officially documented and supported public endpoint? We have observed multiple unannounced catalog/spec changes (e.g., schema and response model updates under CRM Objects), which have impacted our metadata processing.

We would appreciate advance notifications or a changelog reference for such specification changes to help us handle them proactively.

11

we also looking more confirmation on below points @chighsmith

The key section says: date-based versioning changes the API resource path, but it does not change authentication or OAuth scopes.
Old CRM call: /crm/v3/objects/contacts
Date-based CRM call: /crm/objects/2026-03/contacts
OAuth stays the same:authorize user: https://app.hubspot.com/oauth/authorize
get/refresh tokens: https://api.hubapi.com/oauth/v3/token

Use the returned access token in both cases:
Authorization: Bearer <access_token>
Managing OAuth remains the same:
Send the user to the authorize URL.
HubSpot redirects back with an authorization code.
Exchange the code at /oauth/v3/token.
Store the access and refresh tokens securely.
Refresh the access token with the same /oauth/v3/token endpoint when it expires.
Use the access token to call either v3 or date-based CRM APIs.
The only related change is scopes: the date-based endpoint still needs the appropriate existing CRM scope, such as crm.objects.contacts.read or crm.objects.contacts.write.
HubSpot’s OAuth reference is here: Manage OAuth access tokens using the v3 APIs.

please confirm does above information is latest and correct. there is no change in oauth related api for date based versioning.

12

Hi @ShubhangiPawar ! Happy to confirm both points.

On OAuth and date-based versioning:

Yes, your summary is accurate and up to date. Date-based versioning only changes the API resource path — OAuth authentication and token management remain entirely unchanged. To confirm:

  • The authorize URL, token exchange, and refresh flow all stay the same (https://app.hubspot.com/oauth/authorize and https://api.hubapi.com/oauth/v3/token).

  • You use the same Authorization: Bearer <access_token> header whether calling a v3 or date-based endpoint.

  • The required OAuth scopes (e.g. crm.objects.contacts.read / crm.objects.contacts.write) are also unchanged — the date-based path doesn’t introduce new or different scopes.

    There are no OAuth-related API changes associated with date-based versioning.

    On https://api.hubspot.com/public/api/spec/v1/specs:

    This endpoint is not publicly documented on our docs site, which means it is not covered by HubSpot’s stability guarantees or developer terms. As our team noted internally, undocumented endpoints are subject to change without notice — which is exactly what you experienced with the catalog restructuring on ~July 2, 2026.

    Per HubSpot’s API usage guidelines and limits - HubSpot docs, only officially documented and supported APIs are covered by our API Terms and stability commitments. Using undocumented endpoints is not recommended, as they can change or be removed without announcement.

    For advance notifications on supported API changes, the HubSpot Developer Changelog is the best reference.

    Sorry we can’t offer a more formal changelog entry for the July 2 catalog restructuring — because it was treated as an internal cleanup (not a runtime API change), it wasn’t announced externally. I understand that’s frustrating given the impact on your codegen pipeline.

    Let me know if there’s anything else I can help clarify!

Cassie, Community Manager