# HubSpot Allowlisting Request - API Details **Last Updated:** 2025-11-20 **Date:** 2025-11-15 **Purpose:** Request allowlisting for v4 forms API operations to enable programmatic form updates --- ## API Request Details ### Request URL ``` https://api.hubapi.com/marketing/v3/forms/a91b263c-7ca2-418b-b35c-9664c30e968b ``` ### Request Method ``` PATCH ``` ### Request Headers ``` Authorization: Bearer [Private App Access Token] Accept: application/json Content-Type: application/json ``` ### Request Body (JSON) ```json { "fieldGroups": [ { "default": false, "isSmartGroup": false, "fields": [ { "objectTypeId": "0-1", "name": "email", "label": "Email", "required": true, "hidden": false, "validation": { "blockedEmailDomains": [], "useDefaultBlockList": false }, "fieldType": "email" }, { "objectTypeId": "0-1", "name": "firstname", "label": "First Name", "required": false, "hidden": false, "fieldType": "single_line_text" }, { "objectTypeId": "0-1", "name": "lastname", "label": "Last Name", "required": false, "hidden": false, "fieldType": "single_line_text" } ] }, { "default": false, "isSmartGroup": false, "fields": [ { "objectTypeId": "0-1", "name": "company", "label": "Company Name", "required": false, "hidden": false, "fieldType": "single_line_text" }, { "objectTypeId": "0-1", "name": "sign_up_type__c", "label": "Sign up type", "required": false, "hidden": false, "fieldType": "single_line_text" }, { "objectTypeId": "0-1", "name": "content", "label": "Content", "required": false, "hidden": false, "fieldType": "single_line_text" } ] }, { "default": false, "isSmartGroup": false, "fields": [ { "objectTypeId": "0-1", "name": "hs_lead_status", "label": "Lead Status", "required": false, "hidden": false, "options": [ { "label": "New", "value": "NEW", "description": "", "displayOrder": -1 }, { "label": "Open", "value": "OPEN", "description": "", "displayOrder": -1 }, { "label": "In Progress", "value": "IN_PROGRESS", "description": "", "displayOrder": -1 }, { "label": "Open Deal", "value": "OPEN_DEAL", "description": "", "displayOrder": -1 }, { "label": "Unqualified", "value": "UNQUALIFIED", "description": "", "displayOrder": -1 }, { "label": "Attempted to Contact", "value": "ATTEMPTED_TO_CONTACT", "description": "", "displayOrder": -1 }, { "label": "Connected", "value": "CONNECTED", "description": "", "displayOrder": -1 }, { "label": "Bad Timing", "value": "BAD_TIMING", "description": "", "displayOrder": -1 } ], "fieldType": "radio" }, { "objectTypeId": "0-1", "name": "description", "label": "Description", "required": false, "hidden": false, "fieldType": "multi_line_text" }, { "objectTypeId": "0-1", "name": "tool_type", "label": "Tool Type", "required": false, "hidden": false, "fieldType": "single_line_text" } ] }, { "default": false, "isSmartGroup": false, "fields": [ { "objectTypeId": "0-1", "name": "calculation_data", "label": "Calculation Data", "required": false, "hidden": false, "fieldType": "multi_line_text" }, { "objectTypeId": "0-1", "name": "utm_campaign__c", "label": "utm_campaign", "required": false, "hidden": false, "fieldType": "multi_line_text" }, { "objectTypeId": "0-1", "name": "source__c", "label": "utm_source", "required": false, "hidden": false, "fieldType": "multi_line_text" } ] }, { "default": false, "isSmartGroup": false, "fields": [ { "objectTypeId": "0-1", "name": "utm_medium__c", "label": "utm_medium", "required": false, "hidden": false, "fieldType": "multi_line_text" }, { "objectTypeId": "0-1", "name": "utm_term__c", "label": "utm_term", "required": false, "hidden": false, "fieldType": "multi_line_text" }, { "objectTypeId": "0-1", "name": "content__c", "label": "utm_content", "required": false, "hidden": false, "fieldType": "multi_line_text" } ] }, { "default": false, "isSmartGroup": false, "fields": [ { "objectTypeId": "0-1", "name": "leadsource", "label": "Lead Source", "required": false, "hidden": false, "options": [ { "label": "acquisition", "value": "Acquisition", "description": "", "displayOrder": -1 }, { "label": "other", "value": "other", "description": "", "displayOrder": -1 }, { "label": "supply", "value": "Supply", "description": "", "displayOrder": -1 }, { "label": "trade fair", "value": "trade fair", "description": "", "displayOrder": -1 }, { "label": "google", "value": "Google", "description": "", "displayOrder": -1 }, { "label": "customer recommendation", "value": "Customer recommendation", "description": "", "displayOrder": -1 }, { "label": "partner recommendation", "value": "Partner recommendation", "description": "", "displayOrder": -1 }, { "label": "meta", "value": "meta", "description": "", "displayOrder": -1 }, { "label": "cello kwk", "value": "cello kwk", "description": "", "displayOrder": -1 }, { "label": "linkedin", "value": "linkedin", "description": "", "displayOrder": -1 }, { "label": "cold email", "value": "cold email", "description": "", "displayOrder": -1 }, { "label": "newsletter", "value": "newsletter", "description": "", "displayOrder": -1 }, { "label": "email", "value": "email", "description": "", "displayOrder": -1 }, { "label": "cello affiliate", "value": "cello affiliate", "description": "", "displayOrder": -1 }, { "label": "network", "value": "network", "description": "", "displayOrder": -1 }, { "label": "ratgeber", "value": "ratgeber", "description": "", "displayOrder": -1 }, { "label": "inbound call", "value": "inbound call", "description": "", "displayOrder": -1 }, { "label": "homepage", "value": "homepage", "description": "", "displayOrder": -1 }, { "label": "data import", "value": "data import", "description": "", "displayOrder": -1 }, { "label": "Chat", "value": "Chat", "description": "", "displayOrder": -1 }, { "label": "tiktok", "value": "tiktok", "description": "", "displayOrder": -1 }, { "label": "channel sales", "value": "channel sales", "description": "", "displayOrder": -1 }, { "label": "PDF", "value": "PDF", "description": "", "displayOrder": -1 }, { "label": "cold letter", "value": "cold_letter", "description": "", "displayOrder": -1 }, { "label": "freelance sales rep", "value": "freelance sales rep", "description": "", "displayOrder": -1 }, { "label": "meta outreach", "value": "meta outreach", "description": "", "displayOrder": -1 }, { "label": "honey sales", "value": "honey sales", "description": "", "displayOrder": -1 }, { "label": "OMR", "value": "OMR", "description": "", "displayOrder": -1 }, { "label": "Additional workspace registration", "value": "Additional workspace registration", "description": "", "displayOrder": -1 }, { "label": "Webinar", "value": "Webinar", "description": "", "displayOrder": -1 }, { "label": "Outbound", "value": "Outbound", "description": "", "displayOrder": -1 }, { "label": "Ordio Rocket Squad", "value": "Ordio Rocket Squad", "description": "", "displayOrder": -1 }, { "label": "Organic Search", "value": "Organic Search", "description": "", "displayOrder": -1 }, { "label": "Direct Traffic", "value": "Direct Traffic", "description": "", "displayOrder": -1 }, { "label": "Organic Social", "value": "Organic Social", "description": "", "displayOrder": -1 } ], "fieldType": "dropdown" } ] } ] } ``` --- ## API Response Details ### Response Status Code ``` 403 Forbidden ``` ### Response Body (JSON) ```json { "status": "error", "message": "The client is not allowlisted to perform an operation to v4 forms", "correlationId": "a0f03d5d-c779-40ba-8f47-7b60ac182e52", "category": "BANNED" } ``` --- ## Business Justification We need to programmatically update HubSpot forms to: 1. **Split form groups** - Some forms have groups with more than 3 fields, which violates HubSpot's API requirements. We need to split these into multiple groups (max 3 fields per group). 2. **Add missing fields** - We need to add hidden fields to forms for proper UTM tracking and lead attribution. Currently, 6 forms are missing 31 total fields that are required for accurate marketing attribution. 3. **Maintain consistency** - We have automated scripts that verify and update form configurations. Without allowlisting, we must manually update forms, which is time-consuming and error-prone. **Forms Affected:** - `a91b263c-7ca2-418b-b35c-9664c30e968b` (Tools Lead Collection) - `11e392f7-aece-4969-8c39-402ee6cb2330` (Templates) - `c2022eda-c9b4-4010-a02d-d920852585b1` (Pricing Inquiry Form) - `41d07332-6697-4daa-b27e-dd60515f9c0f` (ShiftOps Grader Lead Capture) - `9f9d4e35-d8d9-4283-93b6-1a789e0a1281` (Lead Capture Popup) **Portal ID:** 145133546 --- ## Additional Context - **API Endpoint:** `/marketing/v3/forms/{formId}` - **Operation:** Updating `fieldGroups` array to reorganize fields and add missing hidden fields - **Use Case:** Automated form management and maintenance - **Frequency:** Periodic updates as new fields are needed for tracking and attribution --- ## Ready to Send Copy the sections above (Request URL, Method, Body, Response) and send to HubSpot Support.