Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 37 ยท Integrations and API

Custom Properties, Objects and Associations

Model your own data in HubSpot: property types and field types, custom objects, association labels and cardinality, and the properties and associations APIs, with runnable stand-ins.

HubSpot's default objects cover many businesses, but yours will have its own facts: a subscription plan, a number of seats, an equipment serial number. HubSpot lets you add custom properties to any object, add entirely custom objects, and describe how objects relate with associations. Getting the model right early keeps reports and automation simple.

HubSpot cannot run here. API requests are shown read-only and the Python blocks are stand-ins that validate and model data. Custom objects are limited to the Enterprise tier of the relevant Hub, and property limits depend on the plan; check your account.

Properties

A property is a field on an object. Create them in Settings > Properties or with the properties API. Each property has:

  • an internal name (lowercase, underscores, cannot be changed later),
  • a label (what people see),
  • a type: string, number, date, datetime, enumeration, bool,
  • a field type: text, textarea, number, select, radio, checkbox, booleancheckbox, date, file, calculation_equation, ...
  • a group (for tidy forms and sidebars).

Pick the type deliberately: if you will sum it in a report, make it a number, not text. If it will drive a workflow branch, an enumeration with fixed options is safer than free text. Other special kinds include calculated properties (formulas), rollup properties (aggregate from associated records, available on higher plans) and read-only properties set only by automation.

Terminal
curl --request POST \
  --url https://api.hubapi.com/crm/v3/properties/contacts \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "support_plan",
    "label": "Support plan",
    "groupName": "contactinformation",
    "type": "enumeration",
    "fieldType": "select",
    "options": [
      {"label": "Basic", "value": "basic"},
      {"label": "Premium", "value": "premium"}
    ]
  }'
Python Validate a record against a property schema (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Custom objects

A custom object is a new record type with its own properties, pipeline (optional) and associations: for example Subscription, Property listing or Device. Define it under Settings > Data Management > Objects, or with POST /crm/v3/schemas. You choose the object name, labels, primary display property (what appears in lists), required properties, and searchable properties. After creation HubSpot gives it an objectTypeId (like 2-1234567) and an API name for use in URLs.

Think twice before creating a custom object: if a deal with a different pipeline would do, use that. Custom objects are best for things with their own lifecycle and many per customer.

Associations

Associations connect records. Contact to company, deal to contact, ticket to contact are built in. Features:

  • Labels: describe the relationship, such as Decision maker, Billing contact, or Primary (a company's primary association marks the main one).
  • Cardinality: a custom association can be one-to-one, one-to-many or many-to-many, depending on your design.
  • v4 API: PUT /crm/v4/objects/{fromObjectType}/{fromId}/associations/{toObjectType}/{toId} creates a link, with a body that carries association type IDs; GET on the same family lists them.

Modeling data

Property Field on one object
Custom object New record type
Association Link between records
Label Names the relationship

Start with properties, add objects when needed

1 / 2

Modeling associations

Python Associations with labels and cardinality (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Designing a model

Draw the entities and their relationships before building. The diagram below shows a software company's data model with one custom object.

flowchart LR
  C["Contact"] --- CO["Company"]
  CO --- D["Deal"]
  CO --- S["Subscription (custom)"]
  S --- T["Ticket"]
  C --- T

A customer can have several subscriptions, and tickets can link to both the subscription and the contact.

Python Turn a spreadsheet row into an API payload

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good practice

  • Reuse existing properties rather than creating near duplicates; keep a data dictionary.
  • Use enumerations for anything you filter or segment on.
  • Never delete a property used in workflows or reports without checking dependencies; archived properties can be restored for a limited time.
  • Document the meaning of each custom object and its associations for new team members.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which property type is best for a field you will sum in reports?

    Only numeric properties can be summed or averaged.
  2. 2. What does an association label do?

    Labels give meaning to associations between two records.
  3. 3. When is a custom object a good choice?

    Use properties for simple fields; custom objects for distinct record types.

Summary

  • Properties define fields; choose type and field type carefully.
  • Custom objects model new record types (Enterprise-level feature).
  • Associations, with labels and cardinality, connect records and drive joins in reports.
  • Plan the model before you build it.

Next: Project: From Form Submission to Closed Deal