Custom Objects: API endpoint for including fields in a form

Develop, Build & Integrate APIs & Integrations
1

Hey everybody!

New to HubSpot and struggling with some of the Custom Object API endpoints.

What I want to achieve:
Create a new Custom Object via API (one or multiple calls) after which, without any manual property inclusion or reshuffling, displays the front-end form with all the properties in the display order I want.

The problem:
I succeed in creating the new Custom Object with all the properties, but I can’t get the properties to display in the order I want on the front-end form.

What I’m doing:
Including all the properties in the POST: Custom Objects | Create call with the conventional property displayOrder included.
*Result: all the properties display on the front-end form, but the display order is ignored.
*
I’ve looked at the other endpoints available, but I don’t see anything that could correct this.

Payload sample:
See table below.

Any inputs would be much appreciated - thanks!

https://api.hubapi.com/crm-object-schemas/v3/schemas
{ “name”: “mh_event_series”, “labels”: { “singular”: “MH Event Series”, “plural”: “MH Event Series” }, “primaryDisplayProperty”: “mh_event_series_id”, “secondaryDisplayProperties”: [ “event_name” ], “requiredProperties”: [], “properties”: [ { “name”: “mh_event_series_id”, “label”: “Event Series ID”, “type”: “string”, “fieldType”: “text”, “displayOrder”: 0, “formField”: false }, { “name”: “event_name”, “label”: “Event Name”, “type”: “string”, “fieldType”: “text”, “displayOrder”: 1, “formField”: false }, { “name”: “recurrence”, “label”: “Recurrence”, “type”: “enumeration”, “fieldType”: “select”, “displayOrder”: 2, “formField”: false, “options”: [ { “label”: “Once-off”, “value”: “once_off”, “displayOrder”: 0, “hidden”: false }, { “label”: “Weekly”, “value”: “weekly”, “displayOrder”: 1, “hidden”: false }, { “label”: “Monthly”, “value”: “monthly”, “displayOrder”: 2, “hidden”: false }, { “label”: “Quarterly”, “value”: “quarterly”, “displayOrder”: 3, “hidden”: false }, { “label”: “Yearly”, “value”: “yearly”, “displayOrder”: 4, “hidden”: false } ] }, { “name”: “series_status”, “label”: “Series Status”, “type”: “enumeration”, “fieldType”: “select”, “displayOrder”: 3, “formField”: false, “options”: [ { “label”: “Active”, “value”: “active”, “displayOrder”: 0, “hidden”: false }, { “label”: “Pending”, “value”: “pending”, “displayOrder”: 1, “hidden”: false }, { “label”: “Inactive”, “value”: “inactive”, “displayOrder”: 2, “hidden”: false }, { “label”: “Past”, “value”: “past”, “displayOrder”: 3, “hidden”: false } ] }, { “name”: “default_capacity”, “label”: “Default Capacity”, “type”: “number”, “fieldType”: “number”, “displayOrder”: 4, “formField”: false }, { “name”: “description”, “label”: “Description”, “type”: “string”, “fieldType”: “textarea”, “displayOrder”: 5, “formField”: false } ] }
3

Hey @ilan-lgtm,

Thanks for bringing this to the community!

I looked into the two relevant docs that I’ve linked below, but couldn’t locate anything on property order.

That said, I’d like to tag in some of our Top Contributors to see if they have any experience with this!

Hey @SteveHTM, @Josh, @MichaelMa – Do you have any suggestions for @ilan-lgtm on this?

Thank you!!

Sam, Community Manager

4

Hi @ilan-lgtm :waving_hand:

Unfortunately, it seems as though HubSpot’s Property displayOrder attribute will not currently help you achieve your goal. I’ve reproduced your example and can’t make any sense of the ordering of properties displayed in the default create custom object record form (i.e. the form displayed when clicking the “Create mh event series” button on the “MH Event Series” custom object index page).

For clarity, here’s a list of the properties created at the time of custom object schema initiation:

  • Event Series ID [string/text] (displayOrder: 0)
  • Event Name [string/text] (displayOrder: 1)
  • Recurrence [enumeration/select] (displayOrder: 2)
  • Series Status [enumeration/select] (displayOrder: 3)
  • Default Capacity [number/number] (displayOrder: 4)
  • Description [string/textarea] (displayOrder: 5)

And the order in which they are returned in the create custom object schema API call (success 201), all with displayOrder matching above:

  • Event Name
  • Default Capacity
  • Event Series ID
  • Series Status
  • Description
  • Recurrence

And the order in which they appear in the default Create MH Event Series form (accessed from the MH Event Series custom object index page):

  • Recurrence
  • Default Capacity
  • Series Status
  • Event Series ID
  • Event Name
  • Description

I don’t see any clear pattern here that could explain how this ordering works. Additionally, as far as I can tell, HubSpot’s developer docs do not explicitly describe how displayOrder works and in which contexts it is used for sorting properties displayed in HubSpot UIs. As such, it’d be great to get some clarification from HubSpot on this (@stassey :raising_hands: ).

I hope this helps. Please let me know if you have any follow-up questions.

5

Clear and concise - thank you, @zach_threadint! Appreciate the effort.

9

Hi @ilan-lgtm and all, thanks for your help!

Here is some additional information on this:

displayOrder in the schema/property API only controls order in the CRM record property panel and other internal UI surfaces, not on a HubSpot form. Setting it in your Create schema payload will never affect field order on a form.

Form field order is controlled entirely by the Forms API’s fieldGroups array. Fields are rendered in the exact sequence you list them within fieldGroups[].fields, grouped in rows, there’s no separate displayOrder for form fields. To get your desired front-end order:

  1. Create the object schema/properties (as you’re doing: displayOrder here still governs the CRM record UI).
  2. Create or update the form via the Create a form (or Update a form) endpoint, listing your fieldGroups[].fields in the exact order you want them to appear. This ordering is the display order for the front-end form.

So you need a second API call against the Forms API (not the schema API) to set the field sequence, using each property’s name/objectTypeId inside fieldGroups.

I hope this helps!

Bérangère

This post was created with the assistance of AI tools