Complete Guide to Integrating Gravity Forms with SendSquared

This guide provides a comprehensive approach to integrating WordPress Gravity Forms 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 Gravity Forms:

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 Gravity Forms 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-from-a-form-here with the field ID of your email field
4. Replace your-name-from-a-form-here with the field ID of your name field
5. Replace your-send-squared-token with your actual SendSquared token
6. Replace 123 with the ID of your Gravity Form
7. Test your form submission

Basic Code Explanation

<?php 

add_action( "gform_after_submission", "post_to_send_squared", 10, 2 );

function post_to_send_squared( $entry, $form ) {
  // Only proceed if the form ID is 123
  if ( $form['id'] != 123 ) {
    return;
  }

  // API token
  $token = "your-send-squared-token";

  // Form data
  $email = rgar( $entry, "your-email-from-a-form-here" );
  $name = rgar( $entry, "your-name-from-a-form-here" );

  // API URL
  $api_url = "https://app-api.sendsquared.com/v1/pub/popup?token=" . $token;

  // API data
  $api_data = [
    "email" => $email,
    "name" => $name
  ];

  // Send the data to the API
  $response = wp_remote_post( $api_url, [ "body" => $api_data ] );

  // Check the response status
  if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) != 200 ) {
    error_log( "Error submitting form to SendSquared: " . print_r( $response, true ) );
  }
}

The code hooks into Gravity Forms' gform_after_submission action, which triggers after a form is submitted. It checks if the form ID matches your specified form, then collects the form data and sends it to SendSquared's API.

Basic Additional Customization

You can modify the code to include additional fields:

// Example of adding additional fields
$api_data = [
  "email" => $email,
  "name" => $name,
  "phone" => rgar( $entry, "your-phone-field-id" ),
  "-custom_field_1" => rgar( $entry, "your-custom-field-1-id" ),
  "-custom_field_2" => rgar( $entry, "your-custom-field-2-id" )
];

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

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

• Gravity Forms: Identify your form ID
• Gravity Forms: Identify your email field ID
• Gravity Forms: Identify your first name field ID
• Gravity Forms: Identify your last name field ID
• Gravity Forms: Identify your phone field ID
• Gravity Forms: Identify your interest field ID
• Gravity Forms: 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 Gravity Forms:

1. Form ID: Go to Forms > All Forms in WordPress admin and note the ID number
2. Field IDs: Navigate to the form editor and hover over each field to see its ID:
   • Email field ID
   • First name field ID
   • Last name field ID
   • Phone field ID
   • Interest field ID
   • Notes/comments field ID
   • Any other fields you want to capture

From SendSquared:

1. API Key: Go to Settings > API Keys in SendSquared admin panel
2. Lead Type ID: Navigate to Settings > Lead Types
3. Lead Status ID: Go to Settings > Lead Statuses
4. User ID: Found in the Users section
5. Source ID: If tracking lead sources, found in Settings > Sources

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 with your actual Gravity Form ID
4. Update all field IDs to match your form fields
5. Update the SendSquared specific IDs:
   • 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

Advanced Code Explanation

<?php
add_action("gform_after_submission", "post_to_send_squared_lead_form", 10, 2);

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

  // Update these field IDs with your actual Gravity Forms field IDs
  $email = rgar($entry, "your-email-field-id"); 
  $first_name = rgar($entry, "your-first-name-field-id"); 
  $last_name = rgar($entry, "your-last-name-field-id"); 
  $phone = rgar($entry, "your-phone-field-id"); // must be in E.164 format
  $interest_in = rgar($entry, "your-interest-field-id"); 
  $other_items = rgar($entry, "your-notes-field-id"); 

  // 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
    'followup_at' => $formatted_now, // Optional - but may be required if set by the client
  );

  // 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);
  }
}

This code also hooks into the gform_after_submission action but creates both a contact and a lead record in SendSquared.

Understanding the rgar() Function

The rgar() function retrieves values from form entries:

• Simple fields (text, email, etc.): rgar($entry, "field_id")
• Name fields: First name is .3, last name is .6
• Address fields: Street is .1, city is .3, state is .4, zip is .5

Example:

// Get the value for field ID 3
$email = rgar($entry, "3");

// Get the value for a specific input in a complex field
$first_name = rgar($entry, "14.3");

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:

// 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,
  'followup_at' = $formatted_now, // Optional - but may be required if set by the client
  'quantity_1' => intval(rgar($entry, "your-adults-field-id")), // Get adults count from form
  'quantity_2' => intval(rgar($entry, "your-children-field-id")), // Get children count from form
  'notes' => array(
    "Interest: " . $interest_in,
    "Budget: " . rgar($entry, "your-budget-field-id"),
    "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 Gravity Forms 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

For debugging API responses, modify the error logging to include the response body:

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 to SendSquared (Code: {$response_code}): " . $response_body);
}

Support Resources

For additional support, contact SendSquared support at:

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

For Gravity Forms support, refer to their documentation at:

• https://docs.gravityforms.com/

Frequently Asked Questions

How do I test the Gravity Forms 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 Gravity Forms' built-in test mode if available
7. Switch to production credentials only after thorough testing

What happens if the SendSquared API is temporarily down?

The Gravity Forms 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 Gravity Forms database for manual processing if needed
• You can implement retry logic or queuing systems for failed API calls

Can I integrate multiple Gravity Forms with different SendSquared configurations?

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

function post_to_send_squared( $entry, $form ) {
  // Route different forms to different configurations
  switch($form['id']) {
    case 123: // Newsletter form
      $token = "newsletter-list-uuid";
      $api_url = "https://app-api.sendsquared.com/v1/pub/popup?token=$token";
      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";
      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['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 Gravity Forms)
• Phone: Must be in E.164 format (+1XXXXXXXXXX for US numbers)
• 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 Gravity Forms integration GDPR compliant?

The integration respects GDPR requirements:

• Only processes data after explicit form submission by the user
• Doesn't store additional data beyond Gravity Forms' standard handling
• Transmits data securely via HTTPS to SendSquared
• You should add GDPR consent fields to your Gravity Forms as needed
• Consider adding privacy policy links and consent checkboxes
• Gravity Forms 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