Skip to main content

Integrating Ninja Forms with SendSquared Lead API

warning

IMPORTANT: Before implementing this integration, you will need to gather specific information from both Ninja Forms and SendSquared. Please use the checklist below to ensure you have all required information before you begin.

Implementation Checklist​

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

  • Ninja Forms: Identify your form field keys
  • Ninja Forms: Test your form submission
  • 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

The following code integrates Ninja Forms with SendSquared's Lead With Contact API. When a form is submitted, it collects form data, constructs the necessary contact and lead information, and sends it to SendSquared. This allows you to automatically create leads in your SendSquared CRM directly from form submissions on your WordPress site.

note

You must update the form field keys and API-related IDs with your specific values. See the comments in the code for details on what needs to be updated.

<?php
add_action('ninja_forms_after_submission', 'send_ninja_forms_data_to_sendsquared');

function send_ninja_forms_data_to_sendsquared($form_data)
{
  // Get the submitted form fields
  $fields = $form_data['fields'];
  
  // Initialize variables to store form field values
  $email = '';
  $first_name = '';
  $last_name = '';
  $phone = '';
  $interest_in = '';
  $other_items = '';
  
  // Extract values from the form fields
  // Update these field keys with your actual Ninja Forms field keys
  foreach ($fields as $field) {
    if ($field['key'] == 'email') { // Update with your actual field key
      $email = $field['value'];
    } elseif ($field['key'] == 'first_name') { // Update with your actual field key
      $first_name = $field['value'];
    } elseif ($field['key'] == 'last_name') { // Update with your actual field key
      $last_name = $field['value'];
    } elseif ($field['key'] == 'phone') { // Update with your actual field key
      $phone = $field['value']; // must be in E.164 format
    } elseif ($field['key'] == 'interest') { // Update with your actual field key
      $interest_in = $field['value'];
    } elseif ($field['key'] == 'message') { // Update with your actual field key
      $other_items = $field['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);
  }
}

Gathering Required Information​

Before implementing this integration, you'll need to gather information from both Ninja Forms and SendSquared:

From Ninja Forms:​

  1. Field Keys: In Ninja Forms, each field has a unique key. To find your field keys:
    • Go to Ninja Forms > Dashboard in your WordPress admin
    • Edit your form
    • Click on each field and find its "Key" value in the field settings panel
    • Note down the keys for these fields:
      • Email field
      • First name field
      • Last name field
      • Phone field
      • Interest field
      • Message/notes field

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.

Implementation Steps​

  1. Copy the code snippet above
  2. Paste it into your theme's functions.php file or in a custom plugin
  3. Update all the field keys in the foreach loop to match your Ninja Forms field keys:
    • email
    • first_name
    • last_name
    • phone
    • interest
    • message
  4. Update the SendSquared specific IDs that you gathered earlier:
    • lead_type_id
    • lead_status_id
    • user_id
    • source_id
  5. Replace your-api-key-here with your actual SendSquared API key
  6. Test your form submission to ensure leads are being created in SendSquared

Understanding Ninja Forms Data Structure​

The integration uses the ninja_forms_after_submission hook which is triggered after a form is successfully submitted. Ninja Forms provides the form data as an array where each field contains information like the field key, label, and submitted value.

The data structure looks like this:

$form_data = [
  'fields' => [
    [
      'key' => 'email',
      'label' => 'Email',
      'value' => 'user@example.com'
    ],
    [
      'key' => 'first_name',
      'label' => 'First Name',
      'value' => 'John'
    ],
    // Other fields...
  ],
  // Other form data...
];

In the integration code, we loop through all submitted fields and extract the values based on the field keys.

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' => 1, // Get adults count from form if available
  'quantity_2' => 0, // Get children count from form if available
  'notes' => array(
    "Interest: " . $interest_in,
    "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. Verify that your Ninja Forms field keys match exactly what you've specified in the code
  2. Confirm that your SendSquared API key is correct
  3. Check your WordPress error logs for any API errors
  4. Pay attention to response codes from the SendSquared API:
    • 422 Error: This means validation failed. The response body will contain details about what is missing or incorrect in your request. Check field formats (especially the phone number which must be in E.164 format) and required fields.
  5. Ensure that WordPress can make outgoing HTTP requests (some hosting providers block these)
  6. Verify that the SendSquared API endpoint is accessible from your server

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

add_action('ninja_forms_after_submission', 'debug_ninja_forms_submission');
function debug_ninja_forms_submission($form_data) {
  error_log('Ninja Forms Submission: ' . print_r($form_data, true));
}

For additional support, contact SendSquared support at support@sendsquared.com or +1.855.340.7363.

Frequently Asked Questions​

How do I test the Ninja Forms integration without affecting live data?​

To test safely:

  1. Create a test lead type and status in SendSquared for development
  2. Use test IDs in your integration code during development
  3. Submit test entries 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. Check the WordPress error log for integration issues
  7. Switch to production credentials only after thorough testing

What happens if the SendSquared API is temporarily down?​

The Ninja 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 to Ninja Forms database
  • Not display errors to your site visitors
  • Store the form data in Ninja Forms for manual processing if needed
  • You can implement retry logic or queuing systems for failed API calls

Can I integrate multiple Ninja Forms with different SendSquared configurations?​

Yes! You can modify the integration code to handle multiple forms. First, identify form IDs and then route accordingly:

function send_ninja_forms_data_to_sendsquared($form_data) {
  $form_id = $form_data['form_id'];
  
  // Route different forms to different configurations
  switch($form_id) {
    case 1: // Contact form
      $lead_type_id = 116;
      $lead_status_id = 504;
      $user_id = 1446;
      $source_id = 1;
      break;
    case 2: // Property inquiry form
      $lead_type_id = 120;
      $lead_status_id = 500;
      $user_id = 1450;
      $source_id = 2;
      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 Data: " . print_r($form_data, true));
  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");
  }
}

What data formats are required for SendSquared Lead API fields?​

  • Email: Valid email format (validated by Ninja 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
  • Quantities: Integer values

Is the Ninja 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 Ninja Forms' standard handling
  • Transmits data securely via HTTPS to SendSquared
  • You should add GDPR consent fields to your Ninja Forms as needed
  • Consider adding privacy policy links and consent checkboxes
  • Ninja Forms has built-in GDPR compliance features you can enable

Can I update existing contacts instead of creating duplicates?​

Yes, the SendSquared Lead with Contact API handles this automatically:

  • If a contact with the same email already exists, it updates the contact information
  • A new lead is created and linked to the existing or updated contact
  • This prevents duplicate contacts while tracking multiple lead interactions
  • Email serves as the unique identifier for contact matching

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