Skip to content

Update create-form.mjs #18304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update create-form.mjs #18304

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 93 additions & 1 deletion components/hubspot/actions/create-form/create-form.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,99 @@ export default {
fieldGroups: {
type: "string[]",
label: "Field Groups",
description: "A list for objects of group type and fields. **Format: `[{ \"groupType\": \"default_group\", \"richTextType\": \"text\", \"fields\": [ { \"objectTypeId\": \"0-1\", \"name\": \"email\", \"label\": \"Email\", \"required\": true, \"hidden\": false, \"fieldType\": \"email\", \"validation\": { \"blockedEmailDomains\": [], \"useDefaultBlockList\": false }}]}]`** [See the documentation](https://developers.hubspot.com/docs/reference/api/marketing/forms#post-%2Fmarketing%2Fv3%2Fforms%2F) for more information.",
description: `Array of stringified JSON objects defining form field groups. Each string must contain a complete field group object.

**FIELD GROUP STRUCTURE:**
Each field group object requires:
- \`groupType\` (string, required) - Values: "default_group" (standard display), "progressive" (conditional reveal), "queued" (sequential)
- \`richTextType\` (string, required) - Values: "text" (HTML/text content), "image" (image content)
- \`richText\` (string, optional) - HTML/text content or image URL to display above fields
- \`fields\` (array, required) - Array of field objects

**FIELD OBJECT STRUCTURE:**
Each field in the \`fields\` array MUST include ALL of these properties:
- \`objectTypeId\` (string, required) - CRM object type: "0-1" (Contact), "0-2" (Company), "0-3" (Deal), "0-5" (Ticket)
- \`name\` (string, required) - Unique field identifier (e.g., "email", "firstname", "company")
- \`label\` (string, required) - Display label for the field
- \`fieldType\` (string, required) - Field type (see FIELD TYPES below)
- \`required\` (boolean, required) - Whether field must be filled
- \`hidden\` (boolean, required) - Whether field is visible (hidden fields can still pass values)
- \`validation\` (object, required) - Validation rules (can be empty object \`{}\` if no validation needed)
- \`dependentFields\` (array, required) - Conditional logic array (can be empty \`[]\` if no dependencies)

Comment on lines +41 to +49
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Overstated “required” properties for fields.

Marking hidden, validation, and dependentFields as required is risky—they may be optional/defaulted. Over-specifying will cause user confusion.

Apply this wording tweak in the description (no behavior change):

- Each field in the `fields` array MUST include ALL of these properties:
+ Each field in the `fields` array typically includes:
@@
- - `required` (boolean, required) - Whether field must be filled
- - `hidden` (boolean, required) - Whether field is visible (hidden fields can still pass values)
- - `validation` (object, required) - Validation rules (can be empty object `{}` if no validation needed)
- - `dependentFields` (array, required) - Conditional logic array (can be empty `[]` if no dependencies)
+ - `required` (boolean, optional) - Whether field must be filled
+ - `hidden` (boolean, optional) - Whether field is visible (hidden fields can still pass values)
+ - `validation` (object, optional) - Validation rules
+ - `dependentFields` (array, optional) - Conditional logic array

🌐 Web query:

Does HubSpot require `hidden`, `validation`, and `dependentFields` on each field object for the Forms v3 Create Form endpoint, or are they optional?

💡 Result:

They're optional. The Create Form (marketing/v3/forms) schema shows fields like hidden, validation and dependentFields on field objects but they are not required for every field — the docs/examples treat them as optional properties. [1][2].

References:

  • Create a form (request body schema includes hidden, validation, dependentFields as properties in examples). [1]
  • HubSpot API client field model docs show many field properties (e.g., defaultValue, description, placeholder) as optional; hidden/required/dependentFields appear as properties rather than required constraints. [2]

Mark optional properties as optional in the Create Form docs.

- Each field in the `fields` array MUST include ALL of these properties:
+ Each field in the `fields` array typically includes:
@@
- - `required` (boolean, required) - Whether field must be filled
- - `hidden` (boolean, required) - Whether field is visible (hidden fields can still pass values)
- - `validation` (object, required) - Validation rules (can be empty object `{}` if no validation needed)
- - `dependentFields` (array, required) - Conditional logic array (can be empty `[]` if no dependencies)
+ - `required` (boolean, optional) - Whether field must be filled
+ - `hidden` (boolean, optional) - Whether field is visible (hidden fields can still pass values)
+ - `validation` (object, optional) - Validation rules
+ - `dependentFields` (array, optional) - Conditional logic array
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- \`objectTypeId\` (string, required) - CRM object type: "0-1" (Contact), "0-2" (Company), "0-3" (Deal), "0-5" (Ticket)
- \`name\` (string, required) - Unique field identifier (e.g., "email", "firstname", "company")
- \`label\` (string, required) - Display label for the field
- \`fieldType\` (string, required) - Field type (see FIELD TYPES below)
- \`required\` (boolean, required) - Whether field must be filled
- \`hidden\` (boolean, required) - Whether field is visible (hidden fields can still pass values)
- \`validation\` (object, required) - Validation rules (can be empty object \`{}\` if no validation needed)
- \`dependentFields\` (array, required) - Conditional logic array (can be empty \`[]\` if no dependencies)
Each field in the `fields` array typically includes:
- `objectTypeId` (string, required) - CRM object type: "0-1" (Contact), "0-2" (Company), "0-3" (Deal), "0-5" (Ticket)
- `name` (string, required) - Unique field identifier (e.g., "email", "firstname", "company")
- `label` (string, required) - Display label for the field
- `fieldType` (string, required) - Field type (see FIELD TYPES below)
- `required` (boolean, optional) - Whether field must be filled
- `hidden` (boolean, optional) - Whether field is visible (hidden fields can still pass values)
- `validation` (object, optional) - Validation rules
- `dependentFields` (array, optional) - Conditional logic array
🤖 Prompt for AI Agents 
In components/hubspot/actions/create-form/create-form.mjs around lines 41 to 49,
the docs list several properties as required when some are actually optional;
update the descriptions to mark validation and dependentFields as optional (they
can be omitted or empty), and mark hidden as optional if it can be omitted,
leaving objectTypeId, name, label, and fieldType as required; adjust the text to
explicitly state "(optional)" for those properties and that they may be omitted
or provided as empty objects/arrays where applicable.

**OPTIONAL FIELD PROPERTIES:**
- \`placeholder\` (string) - Hint text for empty fields
- \`description\` (string) - Help text below the field
- \`defaultValue\` (string) - Pre-populated value

**FIELD TYPES & THEIR SPECIFIC REQUIREMENTS:**

*Text Types:*
- \`"email"\` - Email input with validation
- \`"single_line_text"\` - Single line text input
- \`"multi_line_text"\` - Textarea for longer content
- \`"phone"\` - Phone number input
- \`"mobile_phone"\` - Mobile phone input

*Selection Types (require \`options\` array):*
- \`"dropdown"\` - Dropdown menu. Add: \`"options": [{"label": "Display", "value": "internal"}]\`
- \`"radio"\` - Radio buttons. Add: \`"options": [{"label": "Yes", "value": "true"}]\`
- \`"multiple_checkboxes"\` - Multiple checkboxes. Add: \`"options": [{"label": "Option 1", "value": "opt1"}]\`
- \`"single_checkbox"\` - Single checkbox

*Other Types:*
- \`"number"\` - Numeric input
- \`"datepicker"\` - Date selection
- \`"file"\` - File upload
- \`"payment_link_radio"\` - Payment options

**VALIDATION OBJECT EXAMPLES:**

*Email validation:*
\`"validation": {"blockedEmailDomains": ["competitor.com"], "useDefaultBlockList": true}\`

*Number validation:*
\`"validation": {"min": 0, "max": 100, "decimals": 2}\`

*Text validation:*
\`"validation": {"minLength": 3, "maxLength": 50, "pattern": "^[A-Za-z]+$"}\`

*Date validation:*
\`"validation": {"minDate": "2024-01-01", "maxDate": "2024-12-31"}\`

*File validation:*
\`"validation": {"allowedExtensions": [".pdf", ".doc"], "maxFileSize": 5242880}\`

**DEPENDENT FIELDS STRUCTURE:**
Each dependent field object in \`dependentFields\` array:
\`{
"fieldName": "targetFieldName", // Field to show/hide
"objectTypeId": "0-1", // Object type of dependent field
"controllingValue": "specificValue", // Value that triggers condition
"condition": "EQUAL", // Condition type (see below)
"active": true // Whether dependency is active
}\`

**CONDITION TYPES:**
- \`"EQUAL"\`, \`"NOT_EQUAL"\` - Exact match conditions
- \`"CONTAINS"\`, \`"NOT_CONTAINS"\` - Text contains conditions
- \`"IS_EMPTY"\`, \`"IS_NOT_EMPTY"\` - Presence conditions
- \`"GREATER_THAN"\`, \`"LESS_THAN"\` - Numeric comparisons
- \`"CHECKED"\`, \`"NOT_CHECKED"\` - Checkbox states

Comment on lines +93 to +109
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Dependent fields structure and condition enums look speculative.

Before documenting a structure with condition enums (EQUAL, CONTAINS, etc.), confirm the API supports it on create. Otherwise, remove or clearly mark as illustrative.

- **DEPENDENT FIELDS STRUCTURE:**
- ...
- **CONDITION TYPES:**
- - `"EQUAL"`, `"NOT_EQUAL"` ...
+ (Dependent field visibility/conditional logic may be configured in HubSpot UI and not fully supported via this endpoint. Verify before documenting.)

🌐 Web query:

Does the HubSpot Forms v3 Create Form API support configuring dependent/conditional fields? If yes, what is the exact schema and allowed condition values?

💡 Result:

Short answer: Yes — the Forms API (v3) supports dependent/conditional fields via a field-level dependentFields array. See HubSpot's Forms API docs and the generated models for the exact schema and operators. [1][2][3]

What to use / where to look

  • The Marketing Forms reference (v3) describes form creation and that fields can include dependent/conditional configuration. [1]
  • The CMS "Module and theme fields" docs show the same visibility/conditional model and list the conditional operators supported for visibility rules (EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY, MATCHES_REGEX — plus MATCH/regex semantics and an advanced boolean_operator = AND|OR for multiple criteria). Use this page for the exact operator names and semantics. [2]
  • HubSpot’s generated Forms models (official client code / docs) show the exact request model names used by v3: fields have a dependentFields array, and there is a DependentField / DependentFieldFilter model to describe the controlling field and the filter values. Inspect the generated model docs for the concrete JSON property names (DependentField, DependentFieldFilter, dependentFields). [3]

References

  • HubSpot Marketing API — Forms (v3) (create/update form endpoints). [1]
  • Module & theme fields — visibility / advanced_visibility and allowed operators (EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY, MATCHES_REGEX; boolean_operator = AND|OR). [2]
  • Generated Forms models (shows DependentField and DependentFieldFilter in the v3 client code). [3]

If you want, I can paste an exact JSON example for a v3 Create Form body including a dependentFields block (using the exact property names from the generated model) — tell me which field types and condition you want and I’ll produce a ready-to-send payload.

Use HubSpot’s exact dependentFields schema and operators
Replace the speculative “DEPENDENT FIELDS STRUCTURE” snippet with the real v3 Forms API model:

  • fields[].dependentFields: array of DependentField objects
    • controllingField (string)
    • filters: array of DependentFieldFilter, each with
      • operator: one of EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY, MATCHES_REGEX
      • values: string[] (or regex)
    • boolean_operator: AND | OR (for multi-filter rules)
      Provide a JSON example matching the official model.
🤖 Prompt for AI Agents 
In components/hubspot/actions/create-form/create-form.mjs around lines 93 to
109, replace the speculative "DEPENDENT FIELDS STRUCTURE" block with HubSpot
Forms API v3's actual dependentFields model: use fields[].dependentFields where
each DependentField has controllingField (string), filters (array of
DependentFieldFilter) with operator (EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY,
MATCHES_REGEX), values (string[] or regex string), and a boolean_operator (AND |
OR) for combining filters; update any property names (e.g., fieldName →
controllingField, condition → operator, controllingValue → values) and valid
operator list accordingly, and include a JSON example that follows that exact
schema (showing controllingField, filters array with operator and values, and
boolean_operator).

**COMPLETE EXAMPLE:**
\`[
"{\"groupType\":\"default_group\",\"richTextType\":\"text\",\"richText\":\"<h3>Contact Info</h3>\",\"fields\":[{\"objectTypeId\":\"0-1\",\"name\":\"email\",\"label\":\"Email\",\"fieldType\":\"email\",\"required\":true,\"hidden\":false,\"validation\":{\"useDefaultBlockList\":true},\"dependentFields\":[],\"placeholder\":\"you@example.com\",\"description\":\"We'll never share your email\"},{\"objectTypeId\":\"0-1\",\"name\":\"company_type\",\"label\":\"Company Type\",\"fieldType\":\"dropdown\",\"required\":true,\"hidden\":false,\"validation\":{},\"dependentFields\":[{\"fieldName\":\"enterprise_fields\",\"objectTypeId\":\"0-1\",\"controllingValue\":\"enterprise\",\"condition\":\"EQUAL\",\"active\":true}],\"options\":[{\"label\":\"Small Business\",\"value\":\"small\"},{\"label\":\"Enterprise\",\"value\":\"enterprise\"}]}]}"
]\`

Comment on lines +110 to +114
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Example is hard to follow (double-escaped JSON). Provide a practical copy/paste.

Show both the object and how it should be entered as one array item string.

- **COMPLETE EXAMPLE:**
- `[
-   "{\"groupType\":\"default_group\",\"richTextType\":\"text\",\"richText\":\"<h3>Contact Info</h3>\",\"fields\":[{...}]}"
- ]`
+ **Example (one array item):**
+ Object:
+ {
+   "groupType": "default_group",
+   "fields": [
+     {
+       "objectTypeId": "0-1",
+       "name": "email",
+       "label": "Email",
+       "fieldType": "email",
+       "required": true
+     }
+   ]
+ }
+ Enter as string in Field Groups item:
+ "{\"groupType\":\"default_group\",\"fields\":[{\"objectTypeId\":\"0-1\",\"name\":\"email\",\"label\":\"Email\",\"fieldType\":\"email\",\"required\":true}]}"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**COMPLETE EXAMPLE:**
\`[
"{\"groupType\":\"default_group\",\"richTextType\":\"text\",\"richText\":\"<h3>Contact Info</h3>\",\"fields\":[{\"objectTypeId\":\"0-1\",\"name\":\"email\",\"label\":\"Email\",\"fieldType\":\"email\",\"required\":true,\"hidden\":false,\"validation\":{\"useDefaultBlockList\":true},\"dependentFields\":[],\"placeholder\":\"you@example.com\",\"description\":\"We'll never share your email\"},{\"objectTypeId\":\"0-1\",\"name\":\"company_type\",\"label\":\"Company Type\",\"fieldType\":\"dropdown\",\"required\":true,\"hidden\":false,\"validation\":{},\"dependentFields\":[{\"fieldName\":\"enterprise_fields\",\"objectTypeId\":\"0-1\",\"controllingValue\":\"enterprise\",\"condition\":\"EQUAL\",\"active\":true}],\"options\":[{\"label\":\"Small Business\",\"value\":\"small\"},{\"label\":\"Enterprise\",\"value\":\"enterprise\"}]}]}"
]\`
**Example (one array item):**
Object:
{
"groupType": "default_group",
"fields": [
{
"objectTypeId": "0-1",
"name": "email",
"label": "Email",
"fieldType": "email",
"required": true
}
]
}
Enter as string in Field Groups item:
"{\"groupType\":\"default_group\",\"fields\":[{\"objectTypeId\":\"0-1\",\"name\":\"email\",\"label\":\"Email\",\"fieldType\":\"email\",\"required\":true}]}"
🤖 Prompt for AI Agents 
components/hubspot/actions/create-form/create-form.mjs lines 110-114: the
example shows double-escaped JSON which is hard to copy/paste; replace it with a
clear practical example that first shows the JavaScript object form and then the
exact string value to paste (an array with one JSON-stringified item), e.g.,
present the object in normal JSON formatting and immediately below show the
corresponding single-item array string (the object stringified once, not
double-escaped) so users can copy either the object or the ready-to-paste
string.

**IMPORTANT NOTES:**
- Each array item must be a valid JSON string (use JSON.stringify if building programmatically)
- ALL field properties listed as required MUST be included, even if empty
- Field names must be unique within their objectTypeId
- Hidden dependent fields should have \`"hidden": true\` initially
- For HubSpot default fields, use standard names: "email", "firstname", "lastname", "phone", "company"

[See the documentation](https://developers.hubspot.com/docs/reference/api/marketing/forms#post-%2Fmarketing%2Fv3%2Fforms%2F) for additional details.`,
optional: true,
},
createNewContactForNewEmail: {
Expand Down