# HubSpot Forms Integration Troubleshooting

**Last Updated:** 2026-02-15

Guide for diagnosing and resolving HubSpot form submission issues across ordio.com endpoints.

## Quick Verification

### 1. Verify Form GUID in HubSpot

Submissions go to the form specified by the GUID in code. If you view a different form in HubSpot, submissions will not appear there.

**Steps:**

1. HubSpot: Marketing > Lead Capture > Forms
2. Locate the form (e.g., "Templates", "Tools Lead Collection")
3. Open the form and check the URL: `.../form/{formGuid}/...`
4. Compare with `v2/config/hubspot-config.php` constants:
   - Templates: `HUBSPOT_FORM_GUID_TEMPLATE` = `11e392f7-aece-4969-8c39-402ee6cb2330`
   - Tools: `HUBSPOT_FORM_GUID_TOOLS` = `a91b263c-7ca2-418b-b35c-9664c30e968b`

**Common mistake:** Viewing form `11e39217` while code submits to `11e392f7` — submissions appear in the form the code uses.

### 2. Run Test Scripts

```bash
# Configuration and token
php v2/scripts/test-hubspot-config.php

# Templates form specifically
php v2/scripts/test-template-form-submission.php
```

The template test submits a real payload to HubSpot. Check HubSpot Submissions tab for the test email.

### 3. Check Logs

- **Structured logs:** `logs/` directory (ordio_log output)
- **PHP error log:** Server error_log
- **Submit-template errors:** Look for `'endpoint' => 'submit-template'` in log context

## Common Causes

### Wrong Form GUID

**Symptom:** Submissions not visible in expected form.

**Fix:** Update `HUBSPOT_FORM_GUID_*` in `v2/config/hubspot-config.php` to match the form GUID from HubSpot. Verify in HubSpot URL.

### Missing or Invalid API Token

**Symptom:** HTTP 401, or submissions fail silently.

**Fix:**

1. Ensure `HUBSPOT_API_TOKEN` is set (environment or `v2/config/hubspot-api-key.php`)
2. Token format: `pat-{region}-{hash}` (e.g., `pat-eu1-...`)
3. Required scope: `forms` for Forms API v3
4. Run `php v2/scripts/test-hubspot-config.php`

### Field Name Mismatch

**Symptom:** HTTP 400, or fields not populated in HubSpot.

**Fix:**

1. Check `docs/systems/forms/FORM_CONFIGURATION_REFERENCE.md` for field mappings
2. HubSpot form field names must match exactly (e.g., `hs_lead_status` not `lead_status`)
3. Dropdown values must match (e.g., `hs_lead_status`: `"NEW"` not `"New"`)
4. In non-production, 400 responses include `hubspot_errors` in the API response for debugging

### Empty Field Values (Cannot build FormSubmissionValue)

**Symptom:** HTTP 400 with `"Cannot build FormSubmissionValue, some of required attributes are not set [value]"`.

**Cause:** HubSpot Forms API v3 rejects fields with empty string values. Sending `"value": ""` for optional fields triggers this error.

**Fix:** Omit optional fields when they have empty values. The `submit-template.php` endpoint now filters out empty fields before sending to HubSpot. See `v2/api/submit-template.php` – only include fields where value is non-empty.

### Missing legalConsentOptions

**Symptom:** HTTP 400 when form has GDPR/consent enabled.

**Fix:** If the HubSpot form requires consent, add `legalConsentOptions` to the payload. See HubSpot Forms API v3 docs. Most ordio.com forms do not require this.

### Token Scope

**Symptom:** HTTP 403 Forbidden.

**Fix:** Ensure the Private App token has:
- `forms` — Forms API v3 submissions
- `crm.objects.contacts.read` — Optional, for verification

## Test Script Reference

| Script | Purpose |
|--------|---------|
| `v2/scripts/test-hubspot-config.php` | Token loading, config validation |
| `v2/scripts/test-template-form-submission.php` | Templates form (11e392f7) submission test |
| `v2/scripts/test-hubspot-submission.php` | Event Lead Capture form test |

## Log Locations

| Log Type | Location |
|----------|----------|
| Structured (ordio_log) | `v2/logs/` |
| Tools/collect-lead | `v2/logs/tools_hubspot.log` |
| PHP errors | Server error_log |

## Debug Mode

When `ORDIO_ENV` is not `production` (or host is not ordio.com), submit-template.php includes `hubspot_errors` from HubSpot in the API error response. Use this to diagnose 400 errors without checking server logs.

## Related Documentation

- [FORM_CONFIGURATION_REFERENCE.md](FORM_CONFIGURATION_REFERENCE.md) — Field mappings, form GUIDs
- [docs/guides/HUBSPOT_TESTING_CHECKLIST.md](../../guides/HUBSPOT_TESTING_CHECKLIST.md) — Testing steps
- [docs/guides/HUBSPOT_FORMS_COMPLETE_STATUS.md](../../guides/HUBSPOT_FORMS_COMPLETE_STATUS.md) — Form completion status