We have been trying to create a Custom Object via API and have run into a scope issue.
HubSpot AI docs lists out crm.schemas.custom.write as a required scope to create a custom object as shown in the image below. BUT, this is scope does not exist and is not recognised by HubSpot at all, hence creating a Custom Object via API is not possible.
Will you regularly create custom objects and need an automated way to do so, or is this a one-time event?
Have you tried creating the custom object manually and then mapping the field to populate the data. Know this does not scale but may resolve the issue.
Yeah, this is a known confusion with HubSpot’s docs.
The scope crm.schemas.custom.write is referenced in some AI-generated or outdated docs, but it’s not an actual valid scope you can assign in a private app.
What’s actually going on
To create custom objects via API, you don’t need a separate “custom schema” scope you need the correct CRM schema permissions, which are typically covered under:
- crm.objects.custom.write (for records)
- and more importantly, access to *schema endpoints is restricted to certain app types
In many cases, custom object schema creation isn’t fully supported via standard private app scopes, especially depending on your portal permissions and app setup.
What to check
- Make sure you’re using a Private App (not API key / legacy app)
- Ensure your app has:
- full CRM access scopes
- Confirm your HubSpot plan supports custom objects (Enterprise only)
Important limitation
Even with correct scopes, schema creation endpoints can be restricted, and HubSpot sometimes expects custom objects to be created via:
- UI first, then managed via API
or - specific internal/approved apps
Bottom line
You’re not missing anything that scope doesn’t exist.
The issue is documentation inconsistency + restricted schema access, not your implementation.