Custom Object Handling

Custom objects define entirely new CRM object types beyond HubSpot’s standard contacts, companies, deals, and tickets. Because many other assets — properties, workflows, lists, association labels — can reference custom objects, they must be deployed before anything else. JetStack AI handles this through a dedicated pre-deploy phase.

The Pre-Deploy Phase

When you click Implement in the deploy wizard, the first thing the engine does — before deploying any workflows, lists, emails, or other assets — is process all custom objects. This pre-deploy phase ensures that:

1. Custom object schemas exist in the target portal before any asset references them
2. Object type IDs are recorded in the remap table for downstream use
3. Properties, associations, and display settings are created before dependent assets are deployed

The pre-deploy phase runs automatically. You do not need to take any action beyond including the custom objects in your asset selection (which happens automatically when they are dependencies of other selected assets).

Existence Matching

Before creating a custom object in the target portal, JetStack AI checks whether one already exists that matches. The matching logic uses three criteria:

• Name — The internal API name of the custom object
• Singular label — The user-facing singular label (e.g., “Project”)
• Plural label — The user-facing plural label (e.g., “Projects”)

A match on any of these three values is considered a hit. If a match is found:

• The existing custom object is used as-is
• Its object type ID is recorded in the remap table
• No new object is created

If no match is found, the full schema is created from scratch.

Why Multiple Matching Criteria

Different portals may use different internal names for the same conceptual object. One portal might name it project while another uses client_project. By matching on labels as well as the internal name, JetStack AI catches cases where the same object exists under a different technical identifier.

Schema Preservation

When a custom object is created in the target portal, JetStack AI preserves the complete schema from the source:

Properties

All custom properties defined on the object are created with their full configuration:

• Property name (internal API name)
• Label (user-facing display name)
• Type (string, number, date, enumeration, etc.)
• Field type (text, textarea, select, checkbox, etc.)
• Description
• Group assignment
• Options (for enumeration properties — each option with label, value, and display order)
• Required/hidden flags

Associations

Custom objects can define associations with other object types (contacts, companies, deals, other custom objects). During pre-deploy:

• Association definitions are created between the custom object and its associated object types
• Association labels are preserved — both the source-to-target label and the inverse label
• If the associated object type is also a custom object, it must be deployed first (the engine handles ordering automatically)

Search and Display Settings

Configuration that controls how the custom object appears in HubSpot’s UI:

• Primary display property — Which property is shown as the record name
• Secondary display properties — Additional properties shown in list views
• Searchable properties — Which properties are indexed for search
• Required properties — Properties that must be filled when creating a record

Property Validation

Before creating properties on a custom object, JetStack AI runs validation to catch issues that would cause the HubSpot API to reject the request:

Invalid Property Names

HubSpot enforces strict rules for property internal names:

• Must start with a lowercase letter
• Can only contain lowercase letters, numbers, and underscores
• Cannot exceed 100 characters
• Cannot use reserved names (e.g., id, createdate, hs_object_id)

Properties with invalid names are filtered out during deployment. A warning is logged for each skipped property, and the remaining valid properties are created normally.

Option Label Validation

For enumeration properties (dropdowns, checkboxes, radio buttons), each option must have:

• A non-empty label
• A non-empty value (internal identifier)
• A valid display order (integer)

Options that fail validation are skipped, and a warning is recorded.

Type Consistency

If the target portal already has a property with the same internal name but a different type (e.g., priority exists as a “number” in the target but is a “string” in the source), the property creation fails for that specific property. See the Troubleshooting guide for the _type_supr suffix strategy used to resolve type conflicts.

Custom Object Mapping

During the mapping step of the deploy wizard, custom objects may appear in the mapping interface if:

• The source portal uses custom object type IDs that need to be resolved in the target
• An asset references a custom object by its object type ID (e.g., 2-12345678)

Custom object type IDs follow the format 2-XXXXXXXX where the numeric portion is portal-specific. The pre-deploy phase creates the object in the target portal and records the new type ID, so downstream assets receive the correct reference automatically.

If a custom object was matched to an existing object in the target portal, the mapping between source type ID and target type ID is resolved without user input.

Deployment Order for Multiple Custom Objects

When deploying multiple custom objects that reference each other (through associations), the engine determines the correct order:

1. Custom objects with no inter-object associations are deployed first
2. Custom objects that reference already-deployed objects are deployed next
3. This continues until all custom objects are deployed

If two custom objects reference each other (bidirectional association), the engine deploys both object schemas first, then creates the association definitions as a second pass.

Limits and Considerations

• HubSpot plan limits — The number of custom objects you can create depends on the target portal’s HubSpot subscription. Enterprise plans support more custom objects than Professional plans.
• Property limits — Each custom object can have up to the HubSpot-enforced property limit. If the source object has more properties than the target portal’s limit allows, excess properties are skipped.
• Association limits — HubSpot limits the number of association types per object. Verify the target portal has capacity before deploying objects with many associations.

Best Practices

• Deploy custom objects before other assets. While JetStack AI handles this automatically through the pre-deploy phase, it is helpful to understand why custom objects appear as the first items in the deployment log.
• Check existing custom objects. If the target portal already has custom objects, review them before deploying to avoid near-duplicates with slightly different names.
• Validate property names in the source. If you see warnings about filtered properties, the source portal may have properties with names that do not meet HubSpot’s current naming requirements.
• Plan for association labels. If your custom object uses specific association labels (e.g., “Primary Contact” instead of the default “Contact”), these are preserved during deployment but should be verified afterward.