Jobber Integration for BookSmart Form Builder

Overview

The Jobber integration allows your forms to automatically create customers and jobs in Jobber when submitted. This streamlines your workflow by eliminating manual data entry and ensuring all lead information is immediately available in your Jobber account.

Prerequisites

Before setting up Jobber integration, ensure you have:

1. Active Jobber Account: A valid Jobber subscription with API access
2. Jobber OAuth Credentials: Client ID and Client Secret from Jobber
3. Connected Integration: Jobber must be connected in your integrations settings
4. Required Permissions: Read and write access to customers and jobs in Jobber

Setup Instructions

1. Connect Jobber Integration

1. Navigate to Integrations → Jobber
2. Click Connect to Jobber
3. Authorize the connection in the Jobber OAuth flow
4. Verify the connection shows as “Connected”

2. Enable Jobber for Forms

When creating or editing a form:

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

Required Fields

These fields must be mapped for Jobber integration to work:

Field Type	Jobber Mapping	Description
Text	first_name	Customer’s first name
Text	last_name	Customer’s last name
Text/Number	phone	Customer’s phone number

Optional Fields

Additional fields that can be mapped to enhance customer and job data:

Field Type	Jobber Mapping	Description
Email	email	Customer’s email address
Text	address	Street address
Text	city	City
Select	province	State or Province
Text	postal_code	ZIP or Postal Code
Text	job_title	Title for the job
Textarea	job_description	Detailed description of work needed
Date	scheduled_date	Preferred service date
Select	job_type	Type of service requested

Setting Up Field Mappings

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

How It Works

Submission Process

When a form with Jobber integration is submitted:

1. Validation: System validates all required Jobber mappings are present
2. Customer Lookup: Searches for existing customer by phone number
3. Customer Creation: If not found, creates new customer with provided information
4. Job Creation: Creates a new job associated with the customer
5. Confirmation: Returns success/failure status in the response

Data Flow

Form Submission → Field Mapping → Customer Lookup → Customer Creation (if needed) → Job Creation → Confirmation

Customer Duplicate Prevention

The system automatically prevents duplicate customers by:

• Searching existing customers by phone number
• Using existing customer if found
• Only creating new customer if phone number doesn’t exist

API Integration Details

Authentication

The integration uses OAuth 2.0 with automatic token refresh:

• Access tokens are automatically refreshed when expired
• Refresh tokens are securely stored and managed
• Failed authentications are logged and reported

Jobber API Endpoints Used

• Customer Search: POST /api/graphql (clients query)
• Customer Creation: POST /api/graphql (clientCreate mutation)
• Job Creation: POST /api/graphql (jobCreate mutation)

Error Handling

The system includes comprehensive error handling:

• API failures are logged with detailed error messages
• Network timeouts are gracefully handled
• Invalid data submissions are validated before API calls
• User-friendly error messages are returned to forms

Features

Advanced Capabilities

• Smart Customer Matching: Automatically links jobs to existing customers
• Flexible Field Mapping: Map any form field to any Jobber customer/job field
• Address Handling: Complete address information with validation
• Service Scheduling: Optional date selection for job scheduling
• Job Categorization: Support for different job types and priorities

Analytics Integration

Form submissions to Jobber are tracked with:

• Referral source information
• Traffic medium and campaign data
• Conversion tracking
• Performance analytics

Templates

Pre-built Jobber Template

A ready-to-use Jobber form template is available with:

Step 1: Service Request

• Job title field
• Service description textarea

Step 2: Customer Information

• Complete contact information
• Full address collection

Step 3: Scheduling

• Preferred service date
• Service type selection

Step 4: Terms & Conditions

• User agreement checkbox

Using the Template

1. Go to Form Builder → Create New Form
2. Select “Jobber Service Request Template”
3. Customize fields as needed
4. All Jobber mappings are pre-configured

Troubleshooting

Common Issues

“Missing required Jobber mappings” Error

• Ensure first_name, last_name, and phone fields are mapped
• Check that mapped fields are marked as required
• Verify field names match exactly

Jobber API Connection Failed

• Check Jobber integration connection status
• Verify OAuth credentials are valid
• Ensure Jobber account has API access enabled

Customer Creation Failed

• Verify phone number format is correct
• Check for special characters in customer data
• Ensure all required Jobber fields are provided

Job Creation Failed

• Verify customer was created successfully first
• Check job title and description are provided
• Ensure date format is correct (YYYY-MM-DD)

Debug Information

Enable detailed logging by checking application logs for:

• 📤 Sending to Jobber – Integration attempt started
• ✅ Jobber API response received – Successful API call
• ❌ Jobber API call failed – Failed API call with error details

Support

For additional support:

1. Check the integration connection status
2. Review form field mappings
3. Examine application logs for detailed error messages
4. Contact support with specific error messages and form configuration

Best Practices

Form Design

• Clear Field Labels: Use descriptive labels that match Jobber expectations
• Required Field Validation: Mark mapped fields as required to ensure data quality
• Phone Number Formatting: Use consistent phone number format (recommended: +1234567890)
• Address Completion: Collect complete address information for better job management

Data Quality

• Validation Rules: Implement proper validation for email, phone, and postal codes
• Consistent Formatting: Use standardized formats for dates, phones, and addresses
• Error Prevention: Provide helpful hints and examples for complex fields

Performance

• Minimal Required Fields: Only map fields that are essential for your workflow
• Efficient Forms: Keep forms concise while collecting necessary information
• Error Recovery: Provide clear error messages and recovery options

Security Considerations

• OAuth tokens are encrypted and securely stored
• API communications use HTTPS encryption
• Customer data is transmitted securely to Jobber
• Access logs are maintained for audit purposes
• Integration can be disabled at any time without data loss

Limitations

• Maximum of 50 form submissions per minute to prevent API rate limiting
• Phone numbers must be unique per customer in Jobber
• Date fields must be in future for scheduled jobs
• Job titles are limited to 255 characters
• Address fields must be valid for geocoding in Jobber