Complete Guide to Integrating WPForms with SendSquared

This guide provides a comprehensive approach to integrating WordPress WPForms with SendSquared, covering both basic contact integration and advanced lead management integration.

Table of Contents

1. Overview
2. Prerequisites
3. Basic Contact Integration
   • Implementation Steps
   • Code Explanation
   • Additional Customization
4. Advanced Lead with Contact Integration
   • Implementation Checklist
   • Gathering Required Information
   • Implementation Steps
   • Code Explanation
   • Understanding the API
   • Customizing Lead Data
5. Troubleshooting
6. Support Resources

Overview

SendSquared offers two primary integration options with WPForms:

1. Basic Contact Integration: Simple integration that sends contact information to SendSquared when a form is submitted.
2. Advanced Lead with Contact Integration: More comprehensive integration that creates both a contact record and a lead record in SendSquared's CRM.

Choose the integration type based on your specific business needs.

Prerequisites

Before implementing either integration, ensure you have:

• WordPress with WPForms plugin installed and activated
• Admin access to both WordPress and SendSquared
• Basic knowledge of PHP or access to a developer
• Access to edit your theme's functions.php file or ability to create a custom plugin

Basic Contact Integration

The basic integration sends form submissions to SendSquared to add contacts to your email list.

Basic Implementation Steps

1. Copy the code snippet below
2. Paste it into your theme's functions.php file or in a custom plugin
3. Replace your-email-field-id with the actual ID of your email field in WPForms
4. Replace your-name-field-id with the actual ID of your name field in WPForms
5. Replace your-list-group-uuid with your actual SendSquared list group UUID
6. Test your form submission to ensure data is being sent to SendSquared

Basic Code Explanation

<?php
add_action( 'wpforms_process_complete', 'custom_form_submission', 10, 4 );
function custom_form_submission( $fields, $entry, $form_data, $entry_id ) {
  // Get the form data
  $email = $fields['your-email-field-id']['value'];
  $name = $fields['your-name-field-id']['value'];

  // Set the API URL with the token
  $token = "your-list-group-uuid";
  $api_url = "https://app-api.sendsquared.com/v1/pub/popup?token=$token";

  // Set up the API data
  $api_data = array(
    "email" => $email,
    "name" => $name,
  );

  // Use wp_remote_post to send the data to the API
  $response = wp_remote_post( $api_url, array(
    "body" => $api_data
  ) );

  // Check the response code
  if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) != 200 ) {
    // Log an error
    error_log( "Error submitting form: " . print_r( $response, true ) );
  }
}

The code hooks into WPForms' wpforms_process_complete action, which is triggered after a form is submitted. It collects the form data, sets up the API data, and uses wp_remote_post to send the data to the API.

Finding Your WPForms Field IDs

To find the field IDs for your WPForms:

1. Go to WPForms → All Forms in your WordPress dashboard
2. Hover over your form and click "Edit"
3. Click on a field to open its settings
4. Look for the "Field ID" in the Field Options panel on the left

Basic Additional Customization

You can modify the code to include additional fields from your WPForms form:

// Example of adding additional fields
$api_data = array(
  "email" => $email,
  "name" => $name,
  "phone" => $fields['your-phone-field-id']['value'],
  "company" => $fields['your-company-field-id']['value'],
  "custom_field" => $fields['your-custom-field-id']['value']
);

Make sure that any additional fields you add are supported by the SendSquared API.

Targeting Specific Forms

If you only want to integrate specific WPForms with SendSquared, you can add a condition to check the form ID:

add_action( 'wpforms_process_complete', 'custom_form_submission', 10, 4 );
function custom_form_submission( $fields, $entry, $form_data, $entry_id ) {
  // Only process submissions from form with ID 123
  if ( $form_data['id'] != 123 ) {
    return;
  }
  
  // Rest of the code remains the same...

Adding Success Logging

You might want to log successful API calls for debugging purposes:

if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) != 200 ) {
  // Log an error
  error_log( "Error submitting form: " . print_r( $response, true ) );
} else {
  // Log success
  error_log( "Successfully submitted form data to SendSquared: " . print_r( $api_data, true ) );
}

Advanced Lead with Contact Integration

The advanced integration creates both a contact record and a lead record in SendSquared's CRM from a single form submission.

Implementation Checklist

Copy this checklist to your task management system to track your progress:

• WPForms: Identify your form ID
• WPForms: Identify your email field ID
• WPForms: Identify your first name field ID
• WPForms: Identify your last name field ID
• WPForms: Identify your phone field ID
• WPForms: Identify your interest field ID
• WPForms: Identify your notes field ID
• SendSquared: Obtain your API key
• SendSquared: Determine the lead type ID to use
• SendSquared: Determine the lead status ID to use
• SendSquared: Identify the user ID for lead assignment
• SendSquared: Determine the source ID (if applicable)
• Test the integration after implementation

Gathering Required Information

From WPForms:

1. Form ID: Go to WPForms > All Forms in your WordPress admin and note the ID number of your form
2. Field IDs: Navigate to the form builder and click on each field to see its Field Options panel:
   • Look for the "Field CSS Class" option and see the default field ID (e.g., wpforms-123-field_1)
   • Note the field number (the number after "field_") for each field you need:
     • Email field ID
     • First name field ID
     • Last name field ID
     • Phone field ID
     • Interest field ID
     • Notes/comments field ID

From SendSquared:

1. API Key: Go to Settings > API Keys in your SendSquared admin panel to obtain your API key
2. Lead Type ID: Navigate to Settings > Lead Types and note the ID of the appropriate lead type
3. Lead Status ID: Go to Settings > Lead Statuses and identify the status ID you want to use for new leads
4. User ID: This is the ID of the agent who will be assigned these leads. You can find user IDs in the Users section
5. Source ID: If you track lead sources in SendSquared, obtain the appropriate source ID from Settings > Sources

All of these IDs are required for the integration to work properly. If you're unsure about any of these values, contact SendSquared support for assistance in locating them in your account.

Advanced Implementation Steps

1. Copy the code snippet below
2. Paste it into your theme's functions.php file or in a custom plugin
3. Update the form ID ($form_data['id'] != 123) with your actual WPForms form ID
4. Update all the field IDs to match your form fields that you gathered earlier
5. Update the SendSquared specific IDs that you gathered earlier:
   • lead_type_id
   • lead_status_id
   • user_id
   • source_id
6. Replace your-api-key-here with your actual SendSquared API key
7. Test your form submission to ensure leads are being created in SendSquared

Advanced Code Explanation

<?php
add_action('wpforms_process_complete', 'send_wpforms_data_to_sendsquared', 10, 4);

function send_wpforms_data_to_sendsquared($fields, $entry, $form_data, $entry_id)
{
  // Update the form ID to match your lead form
  if ($form_data['id'] != 123) {
    return;
  }

  // Update these field IDs with your actual WPForms field IDs
  $email = isset($fields['your-email-field-id']['value']) ? $fields['your-email-field-id']['value'] : '';
  $first_name = isset($fields['your-first-name-field-id']['value']) ? $fields['your-first-name-field-id']['value'] : '';
  $last_name = isset($fields['your-last-name-field-id']['value']) ? $fields['your-last-name-field-id']['value'] : '';
  $phone = isset($fields['your-phone-field-id']['value']) ? $fields['your-phone-field-id']['value'] : ''; // must be in E.164 format
  $interest_in = isset($fields['your-interest-field-id']['value']) ? $fields['your-interest-field-id']['value'] : '';
  $other_items = isset($fields['your-notes-field-id']['value']) ? $fields['your-notes-field-id']['value'] : '';

  // This constructs the subject line using the interest field
  $subject = 'Interested in ' . $interest_in;
  $now = new DateTime(); 
  $formatted_now = $now->format(DateTime::ATOM);

  // Contact data structure
  $contactData = array(
    'email' => $email,
    'first_name' => $first_name,
    'last_name' => $last_name,
    'mobile_phone' => $phone, // must be in E.164 format (+1XXXXXXXXXX)
  );

  // Lead data structure
  $leadData = array(
    // Update these IDs with your actual SendSquared IDs
    'lead_type_id' => 116, // Update with your lead type ID
    'lead_status_id' => 504, // Update with your lead status ID
    'subject' => $subject,
    'interest_start_at' => $formatted_now,
    'interest_end_at' => $formatted_now,
    'quantity_1' => 1, // Number of adults - customize as needed
    'quantity_2' => 0, // Number of children - customize as needed
    'notes' => array($other_items),
    'user_id' => 1446, // Update with your agent user ID
    'source_id' => 0,  // Update with your source ID if needed
  );

  // Prepare request data
  $requestData = json_encode(array(
    'contact' => $contactData,
    'lead' => $leadData,
  ));

  // Send data to the SendSquared API
  $response = wp_remote_post('https://api.sendsquared.com/v1/leads/lead-with-contact', array(
    'method' => 'POST',
    'headers' => array(
      'Content-Type' => 'application/json',
      // Update with your actual API key
      'x-api-key' => 'your-api-key-here',
    ),
    'body' => $requestData,
  ));

  // Error handling
  if (is_wp_error($response) || wp_remote_retrieve_response_code($response) != 200) {
    $response_code = wp_remote_retrieve_response_code($response);
    $response_body = wp_remote_retrieve_body($response);
    error_log("Error submitting lead to SendSquared (Code: {$response_code}): " . $response_body);
  }
}

Understanding WPForms Field Data

The integration uses the wpforms_process_complete hook which provides access to the form data. WPForms structures the submitted data differently than other form plugins:

Basic usage:

// Access field value by field ID
$email = $fields['1']['value']; // Field ID 1
$name = $fields['2']['value']; // Field ID 2

When working with different field types:

• Simple fields (text, email, etc.): $fields['field_id']['value']
• For Name fields (with multiple inputs):
  • First name: $fields['field_id']['first']
  • Last name: $fields['field_id']['last']
• For Address fields:
  • Street: $fields['field_id']['address1']
  • City: $fields['field_id']['city']
  • State: $fields['field_id']['state']
  • ZIP: $fields['field_id']['postal']

Always use the isset() check to avoid PHP errors if a field doesn't exist or wasn't filled out.

Understanding the Lead with Contact API

The SendSquared Lead With Contact API creates both a contact record and a lead record in a single API call, linking them together automatically. This is useful when:

• You want to capture new leads from your website
• You need to track interest in specific properties or services
• You want to automate the lead capture process

Customizing the Lead Data

You can customize various aspects of the lead data to fit your specific needs:

// Example of additional lead customization
$leadData = array(
  'lead_type_id' => 116,
  'lead_status_id' => 504,
  'subject' => $subject,
  'interest_start_at' => $formatted_now,
  'interest_end_at' => $formatted_now,
  'quantity_1' => isset($fields['adults-field-id']['value']) ? intval($fields['adults-field-id']['value']) : 1,
  'quantity_2' => isset($fields['children-field-id']['value']) ? intval($fields['children-field-id']['value']) : 0,
  'notes' => array(
    "Interest: " . $interest_in,
    "Budget: " . (isset($fields['budget-field-id']['value']) ? $fields['budget-field-id']['value'] : ''),
    "Additional notes: " . $other_items
  ),
  'user_id' => 1446, // The agent who will handle this lead
  'source_id' => 123, // Your website source ID
);

Troubleshooting

If your integration isn't working properly, check these common issues:

1. Field ID Mismatch: Verify that your WPForms field IDs match exactly what you've specified in the code
2. API Credentials: Confirm that your SendSquared token or API key is correct
3. Error Logs: Check your WordPress error logs for any API errors
4. Response Codes: Pay attention to response codes from the SendSquared API:
   • 422 Error: This means validation failed. Check field formats (especially phone numbers) and required fields.
5. Network Issues: Ensure that WordPress can make outgoing HTTP requests (some hosting providers block these)
6. API Accessibility: Verify that the SendSquared API endpoint is accessible from your server

To debug WPForms submissions, you can add this code temporarily to see the structure of your form data:

add_action('wpforms_process_complete', 'debug_wpforms_submission', 10, 4);
function debug_wpforms_submission($fields, $entry, $form_data, $entry_id) {
  error_log('WPForms Submission: ' . print_r($fields, true));
}

Support Resources

For additional support, contact SendSquared support at:

• Email: support@sendsquared.com
• Phone: +1.855.340.7363

For WPForms support, refer to their documentation at:

• https://wpforms.com/docs/

Frequently Asked Questions

How do I test the WPForms integration without affecting live data?

To test safely:

1. Create a test list in SendSquared for development purposes
2. Use test lead type and status IDs during development
3. Submit test data with obvious test names (e.g., "Test User Test")
4. Enable WordPress debug logging to monitor API responses
5. Use a staging/development WordPress environment when possible
6. Use WPForms' test mode or preview functionality
7. Switch to production credentials only after thorough testing

What happens if the SendSquared API is temporarily down?

The WPForms integration includes error handling that will:

• Log errors to your WordPress error log without breaking the form submission
• Allow the form to still submit normally and send confirmation emails
• Not display errors to your site visitors
• Store the form data in WPForms database for manual processing if needed
• You can implement retry logic or queuing systems for failed API calls

Can I integrate multiple WPForms with different SendSquared configurations?

Yes! You can modify the integration code to handle multiple forms with different settings:

function send_wpforms_data_to_sendsquared($fields, $entry, $form_data, $entry_id) {
  // Route different forms to different configurations
  switch($form_data['id']) {
    case 123: // Newsletter form
      $token = "newsletter-list-uuid";
      $api_url = "https://app-api.sendsquared.com/v1/pub/popup?token=$token";
      // Handle basic contact integration
      break;
    case 124: // Lead form
      $lead_type_id = 116;
      $lead_status_id = 504;
      $user_id = 1446;
      $api_url = "https://api.sendsquared.com/v1/leads/lead-with-contact";
      // Handle lead integration
      break;
    default:
      return; // Don't process other forms
  }
  // Rest of integration code...
}

How do I handle form validation errors from the SendSquared API?

The integration includes error logging, but you can enhance it for better debugging:

if (is_wp_error($response) || wp_remote_retrieve_response_code($response) != 200) {
  $response_code = wp_remote_retrieve_response_code($response);
  $response_body = wp_remote_retrieve_body($response);
  
  // Log detailed error information
  error_log("SendSquared API Error - Form ID: {$form_data['id']}, Entry ID: {$entry_id}");
  error_log("Response Code: {$response_code}");
  error_log("Response Body: {$response_body}");
  
  // Handle specific error types
  if ($response_code == 422) {
    error_log("Validation failed - check phone format and required fields");
  } elseif ($response_code == 401) {
    error_log("Authentication failed - check API key or token");
  }
}

What data formats are required for SendSquared API fields?

• Email: Valid email format (validated by WPForms)
• Phone: Must be in E.164 format (+1XXXXXXXXXX for US numbers) for Lead API
• Names: String values, can handle Unicode characters
• Dates: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) - automatically handled by DateTime::ATOM
• IDs: Integer values (lead_type_id, lead_status_id, user_id, source_id)
• Notes: Array of strings for lead API, string for basic contact API
• Quantities: Integer values

Is the WPForms integration GDPR compliant?

The integration respects GDPR requirements:

• Only processes data after explicit form submission by the user
• Doesn't store additional data beyond WPForms' standard handling
• Transmits data securely via HTTPS to SendSquared
• You should add GDPR consent fields to your WPForms as needed
• Consider adding privacy policy links and consent checkboxes
• WPForms has built-in GDPR compliance features you can enable

Can I update existing contacts instead of creating duplicates?

Yes, both SendSquared APIs handle this automatically:

• Basic Contact API: Updates existing contacts with matching email addresses
• Lead with Contact API: Updates existing contacts and creates new leads linked to them
• Email serves as the unique identifier for contact matching
• Multiple leads can be associated with the same contact

What are the API rate limits for SendSquared?

SendSquared API limits:

• 1000 requests per hour per API key
• 10 concurrent requests maximum
• For high-volume forms, consider implementing:
  • Request queuing for peak times
  • Exponential backoff for failed requests
  • Contact SendSquared support for higher limits if needed
• The integration handles rate limiting gracefully through error logging