POST to /crm/v3/schemas with a JSON body specifying name (internal API name), labels.singular and labels.plural for display, and a properties array defining each property with name, label, type, and fieldType
Include the requiredProperties array in the body to mark which properties must be set when creating records of this custom object
Add an associations array to define relationships between the custom object and HubSpot standard objects (contacts, companies, deals) by specifying fromObjectType and toObjectType
Retrieve the created schema using GET /crm/v3/schemas/{objectType} to confirm the objectTypeId and fullyQualifiedName assigned by HubSpot — use these for subsequent API calls
Add additional properties after schema creation using POST /crm/v3/properties/{objectType} if the initial schema definition omitted any fields
Create a record of the new object type using POST /crm/v3/objects/{objectType} with a properties object matching the schema to verify end-to-end functionality
Known gotchas
Custom object names must be unique within the portal, cannot contain spaces or special characters, and cannot be changed after creation — choose the internal name carefully before making the initial POST
The schema API requires a private app token with the crm.schemas.custom.write scope; OAuth tokens for the same scope work equivalently but the app must request this scope during authorization
Deleting a custom object schema is irreversible and deletes all records of that type — there is no soft-delete or restore option available through the API
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp