FieldPulse Integration for BookSmart Form Builder

Setup Instructions

1. Connect FieldPulse Integration

1. Navigate to Integrations → FieldPulse
2. Enter your FieldPulse API credentials
3. Click Connect to FieldPulse
4. Verify the connection shows as “Connected”
5. Configure default job status and billing code settings

2. Enable FieldPulse for Forms

When creating or editing a form:

1. Expand the Integration Settings accordion
2. Toggle “Send Submissions to FieldPulse” to ON
3. Configure field mappings (see Field Mapping section below)

Field Mapping

Required Fields

These fields must be mapped for FieldPulse integration to work:

Field Type	Field Name	FieldPulse Mapping
Text	fieldpulse_first_name	Customer First Name
Text	fieldpulse_last_name	Customer Last Name
Text/Number	fieldpulse_phone	Customer Phone
Email	fieldpulse_email	Customer Email
Text	fieldpulse_street_address	Street address
Text	fieldpulse_city	City
Select	fieldpulse_state	State
Select	fieldpulse_zip	Zip/Postal Code
Select	fieldpulse_service_type	Job Type
Textarea	fieldpulse_job_description	Start Time
Date Field	fieldpulse_preferred_date	Zip/Postal Code
Radio	fieldpulse_arrival_window	Customer Arrival Window (Start Time)
Text	fieldpulse_zip	Zip/Postal Code

Setting Up Field Mappings

1. Add form fields using the form builder
2. For each field, expand the Advanced Options
3. Find the “FieldPulse Pro Key” dropdown
4. Select the appropriate FieldPulse field mapping (see table above)
5. Ensure all required mappings are configured

How It Works

Submission Process

When a form with FieldPulse integration is submitted:

1. Validation: System validates all required FieldPulse mappings are present
2. Customer Processing: Creates or updates customer record with contact information
3. Address Management: Creates service address linked to customer
4. Job Creation: Creates job with service details and scheduling preferences
5. Response Handling: Processes FieldPulse API response and confirms creation

Data Flow

Form Submission → Field Mapping → Customer Creation → Address Creation → Job Creation → FieldPulse Dashboard

Submission Location

When a job request is submitted using a Booksmart webform the request can be found in the FieldPulse Open Work Orders view : https://webapp.fieldpulse.com/service-new/list/open

Customer Management

FieldPulse integration includes intelligent customer handling:

• Automatic customer creation with complete contact information
• Service address management separate from billing address
• Customer communication preferences
• Historical job tracking and customer notes

API Integration Details

Authentication

The integration uses FieldPulse’s API key authentication:

• API keys are securely stored and encrypted
• Authentication status is monitored continuously
• API rate limits are respected and managed
• Connection health is checked regularly

FieldPulse API Endpoints Used

• Customer Management: /customers
• Address Creation: /customers/{id}/addresses
• Job Creation: /jobs
• Employee Management: /employees
• Service Categories: /job_types

Error Handling

The system includes comprehensive error handling:

• Invalid customer data is validated before API submission
• Duplicate customer detection and management
• Address validation and geocoding verification
• Job scheduling conflict detection
• Network connectivity issues are handled gracefully

Features

Advanced Capabilities

• Complete Customer Profiles: Comprehensive customer information with communication preferences
• Address Management: Separate service and billing address handling
• Job Scheduling: Intelligent job creation with preferred dates and times
• Service Classification: Automatic job type assignment based on form inputs
• Employee Assignment: Smart technician assignment based on service type and location

Customer Lookup

Advanced customer lookup and management:

• Search existing customers by phone number
• Auto-populate customer information for returning clients
• Merge duplicate customer records intelligently
• Link new jobs to existing customer history
• Preserve customer preferences and notes

Analytics Integration

Form submissions to FieldPulse are tracked with:

• Lead source attribution and tracking
• Campaign performance metrics
• Conversion rate optimization
• Customer acquisition cost analysis
• Job completion and revenue tracking

Templates

Pre-built FieldPulse Template

A comprehensive FieldPulse form template is available with:

Step 1: Service Details Selection

• Service type dropdown with Basic FieldPulse categories
• Detailed problem description
• Special requirements or notes

Step 2: Customer Information

• Complete contact information
• Customer lookup by phone number
• Full service address collection

Step 3: Service Location Information

• Full service address collection

Step 4: Scheduling Preferences

• Preferred service date selection
• Time window preferences
• Terms and conditions acceptance

Using the Template

1. Go to Form Builder → Create New Form
2. Select “FieldPulse Service Request Template”
3. Customize service types to match your offerings
4. Configure scheduling options and time slots
5. All FieldPulse mappings are pre-configured

Advanced Features

Customer Communication

• Automated Notifications: Trigger customer communication workflows
• Preference Management: Respect customer communication preferences
• Multi-channel Contact: Support for phone, email, and SMS
• Language Preferences: Handle multilingual customer communication

Troubleshooting

Common Issues

“Missing required FieldPulse mappings” Error

• Ensure all required fields are mapped: customer_fname, customer_lname, customer_phone, customer_email, street, city, state, zip
• Check that mapped fields are marked as required
• Verify email field has proper email validation

FieldPulse API Connection Failed

• Check FieldPulse integration connection status
• Verify API key is valid and has proper permissions
• Ensure FieldPulse account is active and in good standing
• Check for API rate limit violations

Customer Creation Failed

• Verify phone number format is correct and unique
• Check email address format and validity
• Ensure customer name fields contain valid data
• Verify no special characters in customer information

Job Creation Failed

• Verify customer was created successfully first
• Check that job type exists in FieldPulse
• Ensure service date is in the future
• Verify address is geocodable and within service area

Address Validation Issues

• Ensure complete address information is provided
• Check for valid street addresses and ZIP codes
• Verify city and state combinations are correct
• Test with known valid addresses in your service area

Debug Information

Enable detailed logging by checking application logs for:

• Sending to FieldPulse Pro – Integration attempt started
• FieldPulse API response received – Successful API call
• FieldPulse API call failed – Failed API call with error details

Performance Monitoring

Track integration performance through:

• API response times and success rates
• Customer creation and duplicate detection rates
• Job creation success rates
• Address validation accuracy
• Overall form-to-job conversion rates

Best Practices

Form Design

• Email Validation: Implement strong email validation since email is required
• Phone Formatting: Use consistent phone number formatting
• Address Completion: Ensure complete address collection
• Service Selection: Align form options with FieldPulse job types

Data Quality

• Contact Information: Validate all contact methods are accurate
• Address Standards: Use standardized address formats
• Service Descriptions: Provide clear, detailed service descriptions
• Customer Classification: Properly categorize residential vs. commercial

User Experience

• Customer Recognition: Implement customer lookup for returning clients (*coming soon)
• Service Selection: Make service type selection intuitive
• Scheduling Integration: Show available time slots when possible
• Confirmation Process: Provide clear confirmation of job creation

Workflow Optimization

• Job Prioritization: Set up proper job priority classification
• Technician Assignment: Configure automatic technician assignment rules
• Follow-up Automation: Set up automated follow-up workflows
• Quality Control: Implement job completion verification processes

Security Considerations

• API keys are encrypted and securely stored
• Customer PII is transmitted using HTTPS encryption
• Data access is logged and auditable
• Integration can be disabled immediately if needed
• Customer data is handled according to privacy regulations
• Access controls prevent unauthorized data access

Limitations

• Maximum of 150 form submissions per hour to prevent API rate limiting
• Email addresses must be unique per customer in FieldPulse
• Phone numbers should be unique to prevent customer duplication
• Job scheduling dates must be within 90 days in the future
• Customer names are limited to 100 characters each
• Service descriptions are limited to 2000 characters

Support & Maintenance

Regular Maintenance Tasks

• Monitor API key validity and expiration
• Review and update field mappings as needed
• Analyze error logs and success rates monthly
• Test integration with sample data quarterly
• Update service area configurations as business grows

Performance Optimization

• Monitor API response times
• Optimize field mapping efficiency
• Review customer duplicate detection accuracy
• Analyze job creation success rates
• Identify and resolve common failure patterns

Getting Help

For FieldPulse integration support:

1. Verify FieldPulse connection status in integrations
2. Check all required field mappings are configured
3. Review recent error logs for specific issues
4. Test integration with known valid sample data
5. Contact support with specific error messages and form configuration details

Emergency Procedures

If integration fails:

1. Check FieldPulse system status
2. Verify API key permissions
3. Review recent form submissions for patterns
4. Enable manual processing as backup
5. Document issues for support team review