HubSpot Custom Properties

What Custom Properties Are

HubSpot comes with default properties like name, email, and deal amount. But most integrations need to store data that doesn’t fit into those defaults — a Jobber job ID, a Clio matter number, or a custom status field from your internal system.

Custom properties are fields you create in HubSpot to hold this data. We use them as the bridge between HubSpot and whatever system we’re connecting it to.

When We Need Them

We’ll tell you exactly which custom properties to create during setup. Common reasons:

• External IDs: Storing the record ID from the other system so we can link records across platforms
• Sync status fields: Tracking whether a record has been synced, when, and its current state
• Data that doesn’t have a default field: Industry-specific data, custom scores, or classification fields

Creating Custom Properties

1. Open Property Settings

1. Log into HubSpot
2. Click the Settings gear icon
3. In the left sidebar, go to Properties
4. Select the object type: Contact, Company, or Deal

2. Create a New Property

1. Click the button to create a new property
2. Choose or create a property group (more on this below)
3. Enter the label — this is what users see in the HubSpot UI
4. Set the internal name — this is what the API uses

Important: The internal name is auto-generated from the label, but you can edit it. Use a clear, lowercase, underscore-separated format. For example: jobber_client_id, sync_status, clio_matter_number. Avoid spaces and special characters. Once set, internal names can’t be changed.

3. Choose the Property Type

• Single-line text: For IDs, short strings, names
• Multi-line text: For notes or descriptions
• Number: For quantities, scores, or numeric IDs
• Dropdown select: For status fields with a fixed set of options
• Date picker: For dates
• Checkbox: For yes/no flags

Pick the type that matches the data. If a field will always be a number (like an external ID), use the number type — it prevents bad data from getting in.

4. Set Up Options (for Dropdowns)

If you chose a dropdown, add the options. For example, a sync status field might have:

• Pending
• Synced
• Failed
• Skipped

5. Save

Click save. The property is immediately available in the UI and through the API.

Property Groups

Property groups keep things organized. Instead of your custom properties mixed in with HubSpot defaults, create a group like “Integration Fields” or “Jobber Sync” to keep them together.

To create a group, look for the option to add a new group when creating a property, or manage groups from the property settings page.

Naming Conventions

We recommend prefixing custom properties with the system name to avoid confusion:

• jobber_client_id (not just client_id)
• clio_matter_number (not just matter_number)
• xero_invoice_status (not just invoice_status)

This makes it obvious which system each property relates to, especially if you have multiple integrations.

Common Issues

Can’t Find the Property in the API

If a property exists in the UI but doesn’t appear in API responses, check that it has a value set on the record. HubSpot’s API only returns properties that have been explicitly requested or that have values. We typically request properties by internal name.

Property Type Mismatch

If a field is created as text but should be a number, you’ll need to create a new property with the right type and migrate the data. HubSpot doesn’t let you change a property’s type after creation.

Too Many Properties

HubSpot has property limits depending on your plan. If you’re close to the limit, let us know and we’ll work with you to consolidate.

Next Steps

• Set up your private app for API access: HubSpot Private App Setup
• Understand the different credential types: HubSpot API Credentials
• Learn more about our HubSpot Implementation Services