# HubSpot NPS Form Setup Instructions


**Last Updated:** 2025-11-20

## Overview

This document provides detailed instructions for creating the HubSpot form for the ShiftOps Beta NPS Survey. The form will collect user feedback during beta testing.

## Form Details

**Form Name**: ShiftOps Beta NPS Survey

**Form Type**: Embedded

**Thank You Message**: "Vielen Dank für dein Feedback!"

## Required Fields

### 1. Email (Required)

- **Field Name**: `email`
- **Field Type**: Single-line text
- **Required**: Yes
- **Description**: User email address for associating feedback with user accounts

### 2. NPS Score (Required)

- **Field Name**: `nps_score`
- **Field Type**: Number
- **Required**: Yes
- **Description**: NPS rating from 0-10
- **Validation**: Integer between 0 and 10

### 3. NPS Category (Auto-calculated)

- **Field Name**: `nps_category`
- **Field Type**: Single-line text
- **Required**: No (auto-calculated by API)
- **Description**: Automatically calculated based on NPS score:
  - **Promoter**: 9-10
  - **Passive**: 7-8
  - **Detractor**: 0-6

### 4. NPS Feedback (Optional)

- **Field Name**: `nps_feedback`
- **Field Type**: Multi-line text
- **Required**: No
- **Description**: Open-ended feedback from user

### 5. ShiftOps Business Name (Optional)

- **Field Name**: `shiftops_business_name`
- **Field Type**: Single-line text
- **Required**: No
- **Description**: Name of the business being analyzed

### 6. ShiftOps Index (Optional)

- **Field Name**: `shiftops_index`
- **Field Type**: Number
- **Required**: No
- **Description**: Total ShiftOps score (0-100)

### 7. ShiftOps Grade (Optional)

- **Field Name**: `shiftops_grade`
- **Field Type**: Single-line text
- **Required**: No
- **Description**: Grade (A-F) assigned to the business

### 8. ShiftOps Place ID (Optional)

- **Field Name**: `shiftops_place_id`
- **Field Type**: Single-line text
- **Required**: No
- **Description**: Google Places ID for the business

### 9. NPS Survey Version (Optional)

- **Field Name**: `nps_survey_version`
- **Field Type**: Single-line text
- **Required**: No
- **Default Value**: "beta-v1"
- **Description**: Version of the NPS survey for tracking

## Field Mappings Reference

When creating the form in HubSpot, use these exact field names (case-sensitive):

| HubSpot Field Name       | Description                | Type             | Required  |
| ------------------------ | -------------------------- | ---------------- | --------- |
| `email`                  | User email address         | Single-line text | Yes       |
| `nps_score`              | NPS rating (0-10)          | Number           | Yes       |
| `nps_category`           | Promoter/Passive/Detractor | Single-line text | No (auto) |
| `nps_feedback`           | User feedback              | Multi-line text  | No        |
| `shiftops_business_name` | Business name              | Single-line text | No        |
| `shiftops_index`         | ShiftOps score             | Number           | No        |
| `shiftops_grade`         | Grade (A-F)                | Single-line text | No        |
| `shiftops_place_id`      | Google Places ID           | Single-line text | No        |
| `nps_survey_version`     | Survey version             | Single-line text | No        |

## Step-by-Step Setup Instructions

### Step 1: Create New Form

1. Log in to your HubSpot account
2. Navigate to **Marketing** > **Lead Capture** > **Forms**
3. Click **Create form** button
4. Select **Embedded form** as the form type
5. Name the form: **"ShiftOps Beta NPS Survey"**

### Step 2: Add Required Fields

1. Click **Add field** to add each field
2. For each field:
   - Enter the exact field name from the table above
   - Select the appropriate field type
   - Set required/optional status as specified
   - Add a user-friendly label (e.g., "Email" for `email` field)

### Step 3: Configure Field Properties

**Email Field**:

- Label: "Deine E-Mail Adresse"
- Placeholder: "max.muster@unternehmen.de"
- Required: Yes
- Validation: Email format

**NPS Score Field**:

- Label: "NPS Bewertung"
- Placeholder: "0-10"
- Required: Yes
- Validation: Number, 0-10

**NPS Feedback Field**:

- Label: "Was ist der Hauptgrund für deine Bewertung?"
- Placeholder: "Teile uns deine Gedanken mit..."
- Required: No
- Rows: 3

### Step 4: Set Form Properties

1. **Form Name**: ShiftOps Beta NPS Survey
2. **Thank You Message**: "Vielen Dank für dein Feedback!"
3. **Form Type**: Embedded
4. **Submit Button Text**: "Feedback absenden"

### Step 5: Get Form ID

1. After creating the form, click on the form to view details
2. The form ID will be displayed in the URL or form settings
3. It will be in UUID format (e.g., `41d07332-6697-4daa-b27e-dd60515f9c0f`)
4. **Copy this form ID** - you'll need it to update the code

### Step 6: Update Code

1. Open `v2/api/shiftops-nps.php`
2. Find the line: `$hubspotFormId = 'HUBSPOT_FORM_ID_PLACEHOLDER';`
3. Replace `HUBSPOT_FORM_ID_PLACEHOLDER` with your actual form ID
4. Save the file

Example:

```php
$hubspotFormId = '41d07332-6697-4daa-b27e-dd60515f9c0f'; // Your actual form ID
```

## Portal ID

The HubSpot Portal ID is already configured: `145133546`

No changes needed for this.

## Testing

After creating the form and updating the code:

1. Test the form submission by visiting the ShiftOps report page
2. Scroll to 80% or wait 30 seconds to trigger the NPS component
3. Select a score (0-10)
4. Enter optional feedback
5. Enter email address
6. Submit the form
7. Verify the submission appears in HubSpot

## Troubleshooting

### Form Not Submitting

- Verify the form ID is correct in `shiftops-nps.php`
- Check that all required fields are present in HubSpot
- Verify field names match exactly (case-sensitive)
- Check browser console for errors
- Review `logs/shiftops-nps.log` for detailed error messages

### Data Not Appearing in HubSpot

- Verify the form ID matches the form in HubSpot
- Check that field names match exactly
- Ensure required fields are marked as required in HubSpot
- Verify the HubSpot Portal ID is correct

### NPS Component Not Showing

- Check browser console for JavaScript errors
- Verify localStorage is not blocking the component
- Clear `shiftops_nps_submitted` and `shiftops_nps_dismissed` from localStorage
- Ensure scroll/time triggers are working

## Additional Notes

- The NPS category is automatically calculated by the API based on the score
- All optional fields will be included if data is available from the report
- Submissions are logged to `logs/shiftops-nps.log` for debugging
- The form uses the same HubSpot Portal ID as the main ShiftOps form

## Support

If you encounter any issues during setup, check:

1. `logs/shiftops-nps.log` for API errors
2. Browser console for JavaScript errors
3. HubSpot form settings for field configuration
4. Network tab for API request/response details