How can we help you?

1. Overview & System Requirements

The Gravity Forms JobNimbus Integration bridges the gap between your public-facing WordPress lead capture forms and your JobNimbus contractor management ecosystem. Built specifically for roofing specialists, general contractors, restoration contractors, and home service professionals, this integration automates the complete lifecycle from inbound estimate requests to contact creation, job provisioning, status assignment, and field rep task delegation.

Instead of relying on clunky third-party connectors or manually keying customer phone calls and online submissions into JobNimbus, inbound form submissions are parsed in real time. Contacts and related Jobs are created instantly with full address geocoding, lead source attribution, damage description notes, and automated stage assignment.

2. Authentication & API Key Connection

The integration connects securely to JobNimbus through the official JobNimbus REST API v1 using a private organizational API token. Follow these steps to obtain and configure your API key:

Generating Your JobNimbus API Token

1. Log in to your JobNimbus web application with an Administrator profile.
2. Click your user profile avatar in the upper right corner and select Settings.
3. In the left-hand navigation sidebar, locate the API tab under integrations.
4. Click New API Key, assign a recognizable description such as Gravity Forms Website Leads, and click Save.
5. Copy the newly generated secret API key to your clipboard.

Connecting in WordPress Dashboard

1. In your WordPress dashboard, navigate to Forms → Settings → JobNimbus.
2. Paste your JobNimbus API Key into the designated credential field.
3. Click Save Settings. The add-on immediately executes a test handshake ping against JobNimbus endpoints.
4. A green status indicator will display confirming that authentication succeeded and your custom fields, sales reps, and workflows have synced.

3. Feed Configuration & Field Mapping

JobNimbus organizes records into two fundamental entities: Contacts (homeowners, property managers, commercial clients) and Jobs (roof replacements, siding estimates, emergency storm inspections). The add-on allows you to create and map both entities in a single automated submission.

Mapping Contact Entities

• Contact Record Type: Select whether the contact should be recorded as a Customer, Lead, Subcontractor, or Vendor.
• Personal & Company Details: Map First Name, Last Name, Company / HOA Name, Email Address, and Primary Phone (Mobile, Home, Work).
• Job Site Address: Map full street address, city, state, postal code, and country. JobNimbus automatically verifies and geocodes valid addresses for mapping routes.
• Lead Source Attribution: Attribute the inquiry to specific marketing campaigns (e.g., Google Ads, Organic Search, Local Referral, Billboard).

Mapping Job Entities & Pipelines

• Job Creation Toggle: Check the option to automatically create an associated Job under the created Contact.
• Job Name Template: Define dynamic naming conventions using merge tags, such as {First Name} {Last Name} - Roof Replacement.
• Workflow & Status Stage: Choose the initial pipeline stage (e.g., Lead Intake, Estimate Scheduled, or Emergency Tarping).
• Sales Representative Assignment: Assign inbound leads to a specific contractor sales representative or dynamically route assignments based on zip code.
• Work Description & Custom Fields: Map damage description text areas, roof pitch choices, insurance claim numbers, and desired inspection dates directly into JobNimbus custom fields.

4. Advanced Workflows & Contractor Automations

Modern contracting businesses require flexible lead qualification and dispatch logic. The add-on provides robust automation tools to streamline field dispatch:

• Conditional Lead Routing by Service Type: Set up distinct feeds for residential roofing, commercial flat roofing, and solar installation. Submissions trigger specific Job workflows and notify dedicated project estimators.
• Geographic Sales Rep Territory Assignment: Utilize Gravity Forms conditional logic on the ZIP/Postal Code field to route North County submissions to Rep A and South County leads to Rep B automatically.
• Automated Task & Follow-up Scheduling: Automatically generate an urgent callback task assigned to your dispatch team whenever an emergency leak inquiry is received after business hours.
• File & Damage Photo Synchronization: Seamlessly pass uploaded storm damage photos, blueprint PDFs, and insurance paperwork from Gravity Forms into the JobNimbus contact attachment library.

5. Error Handling & Troubleshooting Matrix

Use the following reference guide to diagnose and resolve API response statuses from the JobNimbus platform:

6. Developer Extensibility & Filter Hooks

Extend and customize the JobNimbus payload with clean WordPress filter hooks:

/**
 * Filter: gform_jobnimbus_contact_args
 * Purpose: Customize the contact payload before sending to JobNimbus.
 * 
 * @param array $contact_args Structured contact data.
 * @param array $form         The Gravity Forms form object.
 * @param array $entry        The submitted entry object.
 * @param array $feed         The JobNimbus feed configuration.
 * @return array Modified contact payload.
 */
add_filter( 'gform_jobnimbus_contact_args', function( $contact_args, $form, $entry, $feed ) {
    // Add custom tag for insurance storm claims
    $is_insurance_claim = rgar( $entry, '14' ); // Checkbox field
    if ( ! empty( $is_insurance_claim ) ) {
        $contact_args['tags'][] = 'Storm Restoration';
        $contact_args['tags'][] = 'Insurance Lead';
    }
    
    // Automatically sanitize and standardize phone format
    if ( ! empty( $contact_args['home_phone'] ) ) {
        $contact_args['home_phone'] = preg_replace( '/[^0-9]/', '', $contact_args['home_phone'] );
    }
    
    return $contact_args;
}, 10, 4 );

/**
 * Filter: gform_jobnimbus_job_args
 * Purpose: Dynamically adjust Job status or priority based on inspection urgency.
 */
add_filter( 'gform_jobnimbus_job_args', function( $job_args, $form, $entry, $feed ) {
    $urgency = rgar( $entry, '9' ); // Urgency dropdown field
    
    if ( $urgency === 'Emergency Leak' ) {
        $job_args['status_name'] = 'Urgent Inspection';
        $job_args['description'] = '🚨 IMMEDIATE ATTENTION REQUIRED: Active roof leak reported.n' . $job_args['description'];
    }
    
    return $job_args;
}, 10, 4 );

7. Frequently Asked Questions