Custom Objects

Custom objects extend HubSpot’s CRM beyond the standard contact, company, deal, and ticket types. They define entirely new object schemas with their own properties, associations, and display configuration. JetStack AI imports the full schema definition and deploys it to target portals with careful validation and conflict detection.

What Gets Imported

Each custom object schema captures:

• Object name — The internal API name of the custom object
• Labels — Singular and plural display labels (e.g., “Project” / “Projects”)
• Properties — All property definitions on the custom object, including name, type, field type, options, and display order
• Associations — Defined associations to other object types (standard or custom)
• Required properties — Properties that must have a value when creating a record
• Searchable properties — Properties included in global search results
• Secondary display properties — Properties shown in the record sidebar alongside the primary display property
• Primary display property — The property used as the record’s main label in the UI

Pre-Deploy Phase

Custom objects are deployed before all other asset types. This is a critical ordering requirement because:

1. Properties on custom objects need the custom object type ID to be deployed
2. Workflows, lists, and forms may reference custom object types
3. Association labels between custom objects require both type IDs to exist

The deploy engine processes the custom object queue first, records the new type IDs, and then proceeds with all other asset types. This ensures that every downstream reference to a custom object type can be remapped correctly.

Deploy Behavior

Existence Matching

Before creating a custom object schema, JetStack AI checks whether a matching object already exists in the target portal. The matching logic checks three fields in order:

1. Object name — Exact match on the internal API name
2. Singular label — Case-insensitive match on the singular display label
3. Plural label — Case-insensitive match on the plural display label

If any of these matches, the existing object is used and its type ID is recorded in the mapping. No new object is created. This prevents duplicate custom objects when re-deploying or deploying to a portal that already has a matching schema.

Property Validation

When creating or updating a custom object schema, JetStack AI validates properties before including them in the API request:

• Required properties — The requiredProperties array is filtered to include only properties that actually exist in the schema being deployed. If a listed required property was excluded during import or is otherwise missing, it is silently removed from the array.
• Searchable properties — The searchableProperties array is similarly filtered to existing properties only.
• Secondary display properties — Validated the same way.
• Option labels — For enumeration properties (select, radio, checkbox), each option’s label and value are validated. Empty or null labels are removed.
• Display order — The displayOrder field is preserved for each property to maintain the intended layout in the HubSpot UI.

Group Auto-Creation

Custom object properties belong to property groups. If the target portal does not have the required property group, JetStack AI creates a default group named “custom_object_properties”. All properties that reference a missing group are assigned to this default group rather than failing.

If the original group name exists in the target portal, properties are assigned to it as expected.

Schema Creation

The HubSpot API for custom object schema creation accepts the full schema in a single request:

1. Object name, labels, and description
2. All properties with their definitions
3. Required, searchable, and secondary display property arrays
4. The primary display property

Associations are configured separately after the schema is created, since they reference other object type IDs that may not be available at schema creation time.

Dependencies

Custom objects have a unique position in the dependency graph:

• No upstream dependencies — Custom objects do not depend on any other asset type. They are always safe to deploy first.
• Many downstream dependents — Properties, association labels, workflows, lists, forms, and pages may all reference custom object type IDs.

Circular Object References

In rare cases, two custom objects may reference each other through associations (Object A associates to Object B, and Object B associates to Object A). JetStack AI handles this by:

1. Creating both object schemas first (without associations)
2. Configuring associations after both type IDs are available

This two-pass approach avoids the circular dependency that would occur if associations were created inline with the schema.

Edge Cases

Schema Creation API Errors

If the HubSpot API rejects the schema creation, common causes include:

• Duplicate object name — An object with the same internal name already exists. The existence matching should catch this, but if the name format differs slightly (e.g., casing), the API may reject the creation. JetStack AI logs the full error details.
• Invalid property configuration — A property has an unsupported type/fieldType combination, or a required property references a non-existent property name. The validation step catches most of these, but API-level validation is stricter in some cases.
• Object limit reached — HubSpot enforces a maximum number of custom objects per portal based on plan tier. If the limit is reached, the API returns an error and the schema cannot be created.

Existing Object with Different Properties

If a custom object with a matching name already exists but has different properties, JetStack AI does not modify the existing schema. It uses the existing object’s type ID and proceeds. Any properties that exist in the source but not in the target should be deployed separately via the Properties asset type.

Primary Display Property

The primary display property must be a single-line text property and must be included in the schema’s property list. If the specified primary display property is missing or has an incompatible type, the API will reject the schema. JetStack AI validates this before submission and falls back to the first text property in the schema if the intended primary display property is not available.

Troubleshooting

• “Custom object already exists” — The existence matching found a match. This is expected behavior. The existing object’s type ID is used for all downstream mapping.
• “Object limit reached” — Your HubSpot plan has a maximum number of custom objects. Delete unused custom objects or upgrade your plan.
• Properties missing after custom object deploy — Only properties included in the schema at creation time are deployed with the object. Additional properties should be deployed via the Properties asset type in a subsequent step.
• Associations not appearing — Associations are configured after schema creation. If the target object type was not yet deployed, the association creation was skipped. Check the deploy log for association-related errors.
• “Invalid property type” error — A property in the schema uses a type/fieldType combination that the API does not accept. Check the deploy log for the specific property name and adjust it in the source data.