# HubSpot Form Field Configuration Guide


**Last Updated:** 2026-02-20

**Date:** 2025-11-15  
**Status:** ⚠️ Form configuration gaps identified - 3 properties need to be added (code fixes completed ✅, gclid\_\_c verified ✅, export-workdays form GUID corrected ✅, submit-template template fields added ✅, shiftops-hubspot properties added ✅, submit-template simplified to use utm_campaign**c and source**c ✅)

**Last Verified:** 2025-11-15  
**Verification Script:** `scripts/hubspot/detailed-form-field-check.php`  
**Audit Script:** `scripts/hubspot/verify-contact-data.php` + `scripts/hubspot/analyze-audit-results.php`

## Overview

All 9 HubSpot integration endpoints are working correctly and sending all properties. **API verification reveals 3 properties are truly missing** from HubSpot forms (many fields previously thought missing are actually present as hidden fields, including `gclid__c`, `partner__c`, `industry`, `company_size`, `leadsource`, `template_category__c`, `template_type__c`, `shiftops_index`, `grade`).

**Code Status:** ✅ Field name corrections completed (leadstatus → hs_lead_status, removed invalid field names, export-workdays form GUID corrected, submit-template fields added, submit-template simplified to use utm_campaign**c and source**c)  
**HubSpot Forms:** ⚠️ Missing 3 properties total (verified via API)

**Verification Results (2025-11-15 - Updated):**

- Total Forms Verified: 7
- Forms Complete (Field Configuration): 7/7 ✅ (all forms complete - hs_lead_status added to addon-request)
- Forms with Missing Fields: 0 ✅
- Total Missing Properties: 0 ✅
- **Field Capture Status:** ✅ Fields ARE being captured correctly (manual verification confirmed)
- Field Name Variations Found: 1 (leadstatus → hs_lead_status) ✅ Fixed
- Code Issues: ✅ All fixed
- **gclid\_\_c:** ✅ Present in all relevant forms (verified)
- **partner\_\_c:** ✅ Present in all relevant forms (verified)

**See:** `docs/guides/HUBSPOT_CONTACT_AUDIT_REPORT.md` for complete audit findings.

## Form GUIDs and Required Fields

### 1. collect-lead.php (Tools Lead Collection)

**Form GUID:** `a91b263c-7ca2-418b-b35c-9664c30e968b`  
**Form Name:** Universal Tools Form

**Required Fields:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `company` ✅
- `sign_up_type__c` ✅
- `content` ✅
- `hs_lead_status` ✅
- `description` ✅
- `tool_type` ✅
- `calculation_data` ✅
- `utm_campaign__c` ✅
- `source__c` ✅
- `utm_medium__c` ✅
- `utm_term__c` ✅
- `content__c` ✅
- `leadsource` ✅
- `partner__c` ✅ PRESENT (hidden)
- `gclid__c` ✅ PRESENT (hidden)

**Note:** Code sends `leadstatus` but form uses `hs_lead_status` ✅ (code updated to use correct field name)

**Audit Results:** Contact created ✅, Code sending all properties ✅, Form complete ✅ (0 missing properties)

### 2. submit-template.php (Template Downloads)

**Form GUID:** `11e392f7-aece-4969-8c39-402ee6cb2330`  
**Form Name:** Templates Form

**Required Fields:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `phone` ✅
- `content` ✅ (hidden)
- `sign_up_type__c` ✅ (hidden)
- `hs_lead_status` ✅ (hidden)
- `utm_campaign__c` ✅ (hidden)
- `utm_medium__c` ✅ (hidden)
- `content__c` ✅ (hidden)
- `utm_term__c` ✅ (hidden)
- `source__c` ✅ (hidden)
- `leadsource` ✅ (hidden)
- `industry` ✅ PRESENT (visible)
- `company_size` ✅ PRESENT (hidden)
- `template_type__c` ✅ PRESENT (hidden) - **ADDED**
- `template_category__c` ✅ PRESENT (hidden) - **ADDED**
- `utm_campaign__c` ✅ PRESENT (hidden) - Used for campaign tracking
- `source__c` ✅ PRESENT (hidden) - Used for source tracking
- `partner__c` ✅ PRESENT (hidden)
- `gclid__c` ✅ PRESENT (hidden)

**Field Name Variations:**

- `signuptype` → `sign_up_type__c` ✅ (form has `sign_up_type__c`, code sends both - `signuptype` is redundant)

**Code Issues Fixed:**

- ✅ Removed invalid field names: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `gclid`, `lead_source`, `signuptype` (form only has `__c` versions)
- ✅ Removed `utm_source__c` (form uses `source__c` instead - confirmed via API)
- ✅ Using `source__c` for utm_source ✅ (form has this, code uses this)
- ✅ Using `utm_campaign__c` for utm_campaign ✅ (form has this, code uses this)

**Audit Results:** Contact created ✅, Code sending all properties ✅, Form complete ✅ (using utm_campaign**c and source**c instead of campaign**c and lead_source_detail**c)

### 3. addon-request.php (Add-on Pricing Requests)

**Form GUID:** `c2022eda-c9b4-4010-a02d-d920852585b1`  
**Form Name:** Add-on Pricing Request Form

**Required Fields:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `company` ✅
- `phone` ✅
- `description` ✅
- `sign_up_type__c` ✅
- `pricing_inquiry_type` ✅
- `utm_campaign__c` ✅
- `source__c` ✅
- `utm_medium__c` ✅
- `utm_term__c` ✅
- `content__c` ✅
- `leadsource` ✅
- `partner__c` ✅ PRESENT (hidden)
- `gclid__c` ✅ PRESENT (hidden)

**Note:** Code sends `leadstatus` but form may not have this field. Code updated to use `hs_lead_status` instead.

**Note:** Code sends `lead_source` but form has `leadsource` - these may be the same field with different names, or `lead_source` needs to be added.

**Audit Results:** Contact created ✅, Code sending all properties ✅, Form complete ✅ (0 missing properties)

### 4. export-workdays.php (Workdays Export)

**Form GUID:** `a91b263c-7ca2-418b-b35c-9664c30e968b`  
**Form Name:** Tools Lead Collection Form (shared tools form)

**Required Fields:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `company` ✅
- `phone` ✅
- `description` ✅
- `sign_up_type__c` ✅
- `pricing_inquiry_type` ✅
- `utm_campaign__c` ✅
- `source__c` ✅
- `utm_medium__c` ✅
- `utm_term__c` ✅
- `content__c` ✅
- `leadsource` ✅
- `tool_type` ✅ PRESENT (hidden)
- `calculation_data` ✅ PRESENT (hidden)
- `gclid__c` ✅ PRESENT (hidden)

**Audit Results:** Contact created ✅, Code sending all properties ✅, Form complete ✅ (0 missing properties - now using correct tools form)

### 5. shiftops-nps.php (NPS Survey)

**Form GUID:** `804459f7-c18d-4da6-8a0b-a81f44bb8275`  
**Form Name:** ShiftOps NPS Form

**Required Fields:**

- `email` ✅
- `nps_score` ✅ (hidden)
- `nps_category` ✅ (hidden)
- `nps_feedback` ✅ (hidden)
- `shiftops_nps_context` ✅ (hidden)
- `leadsource` ✅ (hidden)
- `utm_campaign__c` ✅ (hidden)
- `content__c` ✅ (hidden)
- `utm_medium__c` ✅ (hidden)
- `source__c` ✅ (hidden)
- `utm_term__c` ✅ (hidden)

**Audit Results:** Contact created ✅, Code sending all properties ✅, Form complete ✅

### 6. shiftops-hubspot.php (ShiftOps Data Submission)

**Form GUID:** `41d07332-6697-4daa-b27e-dd60515f9c0f`  
**Form Name:** ShiftOps HubSpot Form

**Required Fields:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `phone` ✅
- `sign_up_type__c` ✅ (hidden)
- `utm_campaign__c` ✅ (hidden)
- `source__c` ✅ (hidden)
- `utm_medium__c` ✅ (hidden)
- `utm_term__c` ✅ (hidden)
- `content__c` ✅ (hidden)
- `leadsource` ✅ (hidden)
- `content` ✅ (hidden)
- `gclid__c` ✅ (hidden)
- `description` ✅ (hidden)
- `tool_type` ✅ (hidden)
- `calculation_data` ✅ (hidden)
- `company` ✅ PRESENT (business name sent to Company Name field)
- `shiftops_index` ✅ PRESENT (hidden) - **ADDED**
- `grade` ✅ PRESENT (hidden) - **ADDED**
- `hs_lead_status` ⚠️ **NOT IN CODE OR FORM** (intentionally omitted?)
- `industry` ⚠️ **NOT IN CODE OR FORM** (intentionally omitted?)
- `company_size` ⚠️ **NOT IN CODE OR FORM** (intentionally omitted?)

**Audit Results:** Contact created ✅, Code sending all expected properties ✅, Form complete ✅ (10/10 expected fields). Note: hs_lead_status, industry, and company_size are not sent by code and not in form - verify if this is intentional.

### 7. lead-capture.php (Lead Capture Popup)

**Form GUID:** `9f9d4e35-d8d9-4283-93b6-1a789e0a1281`  
**Form Name:** Lead Capture Modal Form

**Required Fields:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `phone` ✅
- `company` ✅
- `additional_information__c` ✅
- `lead_capture_trigger` ✅
- `utm_campaign__c` ✅
- `source__c` ✅
- `utm_medium__c` ✅
- `utm_term__c` ✅
- `content__c` ✅
- `sign_up_type__c` ✅
- `leadsource` ✅
- `gclid__c` ✅ PRESENT (hidden)

**Audit Results:** Contact created ✅, Code sending all properties ✅, Form complete ✅ (0 missing properties)

### 8. Hero Email Form (include_email_form.php)

**Form GUID:** `c1d24914-f2a2-4371-b12a-7217553f5897`  
**Form Name:** Hero Email Form

**Used by:** Homepage, /gastro, and other hero sections with email capture (not /einladung – see Cello form).

**Required Fields:**

- `email` ✅
- `sign_up_type__c` ✅ (hidden)
- `hs_lead_status` ✅ (hidden)
- `source__c` ✅ (hidden)
- `utm_medium__c` ✅ (hidden)
- `utm_campaign__c` ✅ (hidden)
- `utm_term__c` ✅ (hidden)
- `content__c` ✅ (hidden)
- `gclid__c` ✅ (hidden)
- `leadsource` ✅ (hidden)
- `partner` ✅ (hidden)
- `cello_referral_ucc__c` ⚠️ **ADD TO FORM** – Cello referrer code (optional for Hero; /einladung uses Cello form)
- `cello_referral__c` ⚠️ **ADD TO FORM** – Cello referrer name (optional for Hero; /einladung uses Cello form)

**Verification:** `php v2/scripts/hubspot/verify-hero-form-cello.php`

**Submission:** Client-side via `v2/base/include_email_form.php`; redirects to `workspace.ordio.com/join#/create/email` only after HubSpot success.

**See:** [CELLO_HUBSPOT_INTEGRATION.md](../systems/cello/CELLO_HUBSPOT_INTEGRATION.md)

### 9. Cello Form (include_email_form.php when $emailFormCello)

**Form GUID:** `a47cfeb7-4d00-4a76-971d-23a82739fb15`  
**Form Name:** Cello

**Used by:** `v2/pages/cello_einladung.php` (/einladung) – dedicated Cello referral landing page.

**Required Fields (Contact unless noted):**

- `email` ✅
- `hs_lead_status` ✅ (hidden)
- `leadsource` ✅ (hidden, preset "cello affiliate")
- `source__c` ✅ (hidden)
- `utm_medium__c` ✅ (hidden)
- `utm_campaign__c` ✅ (hidden)
- `utm_term__c` ✅ (hidden)
- `content__c` ✅ (hidden)
- `sign_up_type__c` ⚠️ **ADD TO FORM** (hidden; value "cello_einladung") – never use `sign_up_type` (invalid)
- `cello_referral_ucc__c` ✅ (hidden) – Cello referrer code
- `cello_referral__c` ✅ (hidden) – Cello referrer name, decoded from base64 celloN
- `record_type_id__dropdown_` ✅ (hidden)
- `recycled_inbound_lead` ✅ (hidden)

**Verification:** `php v2/scripts/hubspot/verify-cello-form.php`

**Submission:** Client-side via `v2/base/include_email_form.php` when `$emailFormCello` is true; redirects to `workspace.ordio.com/join#/create/email` only after HubSpot success.

**See:** [CELLO_HUBSPOT_INTEGRATION.md](../systems/cello/CELLO_HUBSPOT_INTEGRATION.md)

### 10. webinar-registration.php (Product Webinars)

**API Type:** CRM API v3 (not Forms API)  
**No Form GUID** - Uses direct contact creation

**Required Properties:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `phone` ✅
- `sign_up_type__c` ⚠️ **MISSING** (audit: required but missing)
- `source__c` (utm_source) ⚠️ **MISSING** (audit: not set)
- `utm_medium__c` (utm_medium) ⚠️ **MISSING** (audit: not set)
- `utm_campaign__c` (utm_campaign) ⚠️ **MISSING** (audit: not set)
- `utm_term__c` (utm_term) ⚠️ **MISSING**
- `content__c` (utm_content) ⚠️ **MISSING**
- `gclid__c` (gclid) ⚠️ **MISSING**
- `leadsource` (leadSource) ⚠️ **MISSING**

**Test Results:** Contact created ✅, Most UTM fields set ✅, `gclid__c` missing ⚠️

### 11. payroll-webinar-registration.php (Payroll Webinars)

**API Type:** CRM API v3 (not Forms API)  
**No Form GUID** - Uses direct contact creation

**Required Properties:**

- `email` ✅
- `firstname` ✅
- `lastname` ✅
- `phone` ✅
- `sign_up_type__c` ⚠️ **MISSING** (audit: required but missing)
- `source__c` (utm_source) ⚠️ **MISSING** (audit: not set)
- `utm_medium__c` (utm_medium) ⚠️ **MISSING** (audit: not set)
- `utm_campaign__c` (utm_campaign) ⚠️ **MISSING** (audit: not set)
- `utm_term__c` (utm_term) ⚠️ **MISSING** (audit: not set)
- `content__c` (utm_content) ⚠️ **MISSING** (audit: not set)
- `gclid__c` (gclid) ⚠️ **MISSING** (audit: not set)
- `leadsource` (leadSource) ⚠️ **MISSING** (audit: not set)

**Audit Results:** Contact created ✅, Code sending all properties ✅, Properties missing 2 (sign_up_type\_\_c, leadsource) ⚠️

## Field Name Mapping

### Standard UTM Fields

| Code Field Name | HubSpot Property Name | Type     | Required |
| --------------- | --------------------- | -------- | -------- |
| `utm_source`    | `source__c`           | Text     | Yes      |
| `utm_medium`    | `utm_medium__c`       | Text     | Yes      |
| `utm_campaign`  | `utm_campaign__c`     | Text     | No       |
| `utm_term`      | `utm_term__c`         | Text     | No       |
| `utm_content`   | `content__c`          | Text     | No       |
| `gclid`         | `gclid__c`            | Text     | No       |
| `leadSource`    | `leadsource`          | Dropdown | Yes      |

### Cello Referral Fields

| Code Field Name   | HubSpot Property Name       | Type | Required | Notes                          |
| ----------------- | --------------------------- | ---- | -------- | ------------------------------ |
| `ucc`             | `cello_referral_ucc__c`     | Text | No       | Cello and Hero forms           |
| `celloReferrerName` | `cello_referral__c`       | Text | No       | Cello and Hero forms           |
| —                 | `own_cello_ucc__c`          | Text | No       | Empty for new signups          |

### LeadSource Dropdown Values

The `leadsource` property should accept these values:

- `Google Ads`
- `Organic Search`
- `Direct Traffic`
- `referral`
- `linkedin`
- `meta`
- `Google`
- `Paid Search`
- `cello affiliate` (Cello form – /einladung)
- `cello kwk` (Cello campaigns)

## Create Contact Properties (Cello / Hero Forms)

Form submissions only persist to Contact records when field names match existing Contact properties. If HubSpot shows "This value wasn't passed to the Contact record. 'X' isn't a Contact property", create the missing properties first.

**Path:** HubSpot > Settings > Properties > Contact properties > Create property

| Internal Name | Label | Type | Object | Notes |
|---------------|-------|------|--------|-------|
| `cello_referral_ucc__c` | Cello Referral UCC | Single-line text | Contact | Cello form (/einladung) |
| `cello_referral__c` | Cello Referral Name | Single-line text | Contact | Cello and Hero forms |
| `sign_up_type__c` | Sign Up Type | Single-line text | Contact | Used across forms; never use `sign_up_type` (invalid) |

**Create via API (optional):** Run `php v2/scripts/hubspot/create-cello-contact-properties.php` (requires `HUBSPOT_API_TOKEN` with `crm.schemas.contacts.write` scope). Use `--dry-run` to preview.

After creating properties, ensure each form's hidden fields map to these properties in the form editor.

## Configuration Steps

### For Forms API v3 Forms

1. **Access HubSpot Form Editor**

   - Go to Marketing > Forms
   - Find form by GUID
   - Click Edit

2. **Add Hidden Fields**

   - Click "Add field" → "Hidden field"
   - Add each UTM field with exact property names:
     - `source__c`
     - `utm_medium__c`
     - `utm_campaign__c`
     - `utm_term__c`
     - `content__c`
     - `gclid__c`
     - `leadsource` (dropdown field)

3. **Configure leadsource Dropdown**

   - Set field type to "Dropdown"
   - Add all accepted values (see above)
   - Set as hidden field

4. **Save Form**

### For CRM API Contacts

1. **Verify Properties Exist**

   - Go to Settings > Properties > Contact properties
   - Verify all UTM properties exist:
     - `source__c`
     - `utm_medium__c`
     - `utm_campaign__c`
     - `utm_term__c`
     - `content__c`
     - `gclid__c`
     - `leadsource`

2. **Create Missing Properties**

   - If property doesn't exist, create it with:
     - Internal name: exact match (e.g., `source__c`)
     - Label: User-friendly name (e.g., "UTM Source")
     - Field type: Text (or Dropdown for `leadsource`)

3. **Configure leadsource Property**
   - Set as Dropdown type
   - Add all accepted values
   - Set as required if needed

## Testing After Configuration

After configuring HubSpot forms/properties:

1. Run comprehensive test:

   ```bash
   php scripts/hubspot/test-all-forms-comprehensive.php --base-url=http://localhost:8003
   ```

2. Verify contacts:

   ```bash
   php scripts/hubspot/verify-contact-data.php --results-file=temp/test-results-{timestamp}.json
   ```

3. Check HubSpot UI:
   - Open each test contact in HubSpot
   - Verify UTM fields are populated
   - Verify leadsource is set correctly

## Current Test Results Summary

**All Endpoints:** ✅ Working (9/9)  
**Contacts Created:** ✅ 9/9  
**Forms Verified:** ✅ 7/7 (via API)

**Missing Fields Summary:**

- collect-lead: 0 fields ✅ (complete - all fields present including partner**c and gclid**c)
- submit-template: 0 fields ✅ (complete - using utm_campaign**c and source**c)
- addon-request: 0 fields ✅ (complete - all fields present including partner**c and gclid**c)
- export-workdays: 0 fields ✅ (complete - now using correct tools form)
- shiftops-hubspot: 0 fields ✅ (complete - hs_lead_status, industry, company_size not sent by code, verify if intentional)
- lead-capture: 0 fields ✅ (complete - all fields present including gclid\_\_c)
- shiftops-nps: 0 fields ✅ (complete)

**Total Missing:** 0 fields ✅ (all forms complete - hs_lead_status added to addon-request)

**Critical Discovery:** Comprehensive audit (November 15, 2025) revealed that fields exist in forms but are NOT being captured when contacts are created. This is a submission/mapping issue, not a missing field issue. See `HUBSPOT_CONTACT_AUDIT_REPORT.md` for details.

**Code Fixes Applied:**

- ✅ `collect-lead.php`: `leadstatus` → `hs_lead_status`
- ✅ `addon-request.php`: `leadstatus` → `hs_lead_status`, `lead_source` → `leadsource`
- ✅ `addon-request` form: `hs_lead_status` field added ✅
- ✅ `submit-template.php`: Removed 8 invalid field names (utm_source, utm_medium, etc. without \_\_c), removed campaign**c and lead_source_detail**c
- ✅ `export-workdays.php`: Form GUID corrected (c2022eda... → a91b263c... - Tools Lead Collection), added missing fields to match tools form structure

## Next Steps

1. ✅ **Code fixes completed** - All endpoints working
2. ⏳ **HubSpot form configuration** - Add UTM fields to all forms
3. ⏳ **HubSpot property verification** - Ensure all properties exist
4. ⏳ **Re-test after configuration** - Verify UTM fields are set correctly
5. ⏳ **Browser-based testing** - Test form includes and content pages

## References

- HubSpot Forms API v3 Documentation: https://developers.hubspot.com/docs/api/marketing/forms
- HubSpot CRM API v3 Documentation: https://developers.hubspot.com/docs/api/crm/contacts
- Form Field Configuration: See `docs/guides/HUBSPOT_INTEGRATION_GUIDE.md`