How to create a Custom Object

Step by step guide to creating a new HubSpot Custom Object through the API using Postman.

  • The portal needs to have an Enterprise subscription to be able to create Custom CRM Objects (Marketing, Sales, Service, CMS - doesn't matter).
  • A portal can have up to 10 custom objects
  • Once the object is created, most object settings can be accessed through the HubSpot UI (creating new properties, record customization etc)
  • For more in-depth knowledge, and a list of everything you can do with the API, please see the excellent CRM Custom Objects API Documentation here
  • For any new Custom Object, remember to always create the property Import ID. This is so we easily can filter out any Custom Objects created through a specific import. You don't have to create this property through the API, it can easily be done in the HubSpot UI once the Custom Object has been created,

How to create a Custom Object using Postman

  1. Download and install Postman (or use the online version)
  2. Click the + and create a new request. Set it to POST.
  3. Enter as your request URL
  4. Under Params, create a new Query Param called hapikey
  5. Go to HubSpot and get the portal specific API key found under Settings > Integrations > API Key and paste it as the hapikey value
  6. Go to Headers and make sure that you have a key called Content-type with the value application/json
  7. Click Body and tick the little box raw
  8. Paste the following JSON:
    "name": "project",
    "labels": {
    "singular": "Project",
    "plural": "Projects"
    "primaryDisplayProperty": "project_name",
    "requiredProperties": [
    "properties": [
    "name": "project_id",
    "label": "Project ID",
    "type": "string",
    "fieldType": "text"
    "associatedObjects": [
  9. Adjust the Name (No blank spaces! must be nameName or name_name), Primary Display Property, Properties and Associations. The default property is a single line text (string). If you want the primary display property to be of another property type, see a list of available fields and fieldTypes here. CO-03

    Please note that you only need to create ONE property through the API and that's the Primary Display Property. Any other properties you can add and adjust in the HubSpot UI once the object has been created.
  10. Hit Send
  11. Check the response body.
    If "Status 201 created": Yay! You've created your first Custom Object.
    If "ERROR": Aaw :( Check the error message and adjust your JSON.
  12. Take note of the fullyQualifiedName and/or the objectTypeId. These are your object identifiers and needed if you want to do any updates to your object through the API in the future (however, the formula for fullyQualifiedName is "p{HubSpot portal ID}_{object name}" and the objectTypeId can be found in the URL when accessing your object in HubSpot).

  13. Once the object is created, open HubSpot and go to Settings > Objects > Custom objects. From here you can adjust most settings including setting up new properties and display properties, record creation properties and property views.

How to edit the secondary display properties

The secondary display properties are the properties displayed on the Association Card in the CRM:


To change your secondary display properties, go to Settings > Properties > Records customization and click on your object.

The primary display property can only be changed through the API using a PATCH request. See the HubSpot CRM Custom Objects API Documentation for more details.