DEV Community: Rahul Sharma

CF7 to Keap (Infusionsoft) Not Adding Contacts: A Complete Troubleshooting Guide

Rahul Sharma — Fri, 16 Oct 2026 07:15:43 +0000

You have built a Contact Form 7 form. You have connected it to Keap (formerly Infusionsoft) through the "Contact Form to Any API" plugin. You have entered your API credentials and mapped the fields. And yet, when a user submits the form, no contact appears in your Keap CRM.

This is a frustratingly common problem. The good news? The issue is almost always one of four things, and each has a clear fix. This guide walks through the exact debugging process, common error patterns, and verified solutions.

Understanding the Data Flow

When a user submits your CF7 form with Keap contact creation enabled, here is what should happen:

User submits form → Plugin captures data → API request sent to Keap → Contact created

When it breaks, the failure happens at one of the last two stages. Your first diagnostic tool is the plugin's API Logs page. It shows whether a request was sent, the exact JSON payload, and the response from Keap. If no request appears in the logs, the problem is on the WordPress side. For a deeper breakdown of that specific scenario, see this guide on Contact Form 7 data not reaching the API.

Failure #1: The Infusionsoft Field Prefix Is Missing

What you see: The plugin's logs are empty, or Keap returns an error. The form submits successfully, but no contact is created.

Why it happens: Older CF7-to-Infusionsoft integrations require a specific field naming convention. Every form field that should be sent to Infusionsoft must be prefixed with infusionsoft-. If your CF7 field is named your-email but the integration expects infusionsoft-email, the data never reaches the API.

The fix:

Step 1: Rename your CF7 fields. In the CF7 form editor, ensure every field you want to send to Keap uses the infusionsoft- prefix.

For example:

[text* infusionsoft-first-name placeholder "First Name"]
[email* infusionsoft-email placeholder "Email"]
[tel infusionsoft-phone placeholder "Phone"]

Step 2: Update your field mappings. In the API plugin's mapping configuration, match the prefixed CF7 field names to the Keap API parameters.

Step 3: Test with a minimal form. Create a simple test form with only infusionsoft-first-name and infusionsoft-email. Submit it and check Keap for the new contact.

Important context: If you are using the "Contact Form to Any API" plugin rather than a dedicated Infusionsoft add-on, you may be building the JSON payload manually. In that case, the prefix requirement does not apply, but the field mapping to Keap's API parameters must still be exact.

Failure #2: OAuth Authentication Is Not Configured Correctly

What you see: Keap returns a 401 Unauthorized or "Developer Inactive" error. No contact is created.

Why it happens: Keap uses OAuth 2.0 for API authentication . The API token must be valid, and the refresh token must be properly managed. A common issue is that the access token expires, and the integration cannot refresh it automatically.

A Keap developer described this exact problem: "I am creating a new access token manually and replacing daily because I can't seem to figure out this OAuth process for simple API calls" . Another user reported getting "Developer Inactive" errors when trying to use a refreshed token .

The fix:

Step 1: Verify your OAuth credentials. In Keap, navigate to Settings → API Settings. Copy your Client ID and Client Secret .

Step 2: Generate a fresh API token. According to Keap's OAuth documentation, you need to generate an API token through the developer portal .

Step 3: Configure authentication in the plugin. Add the Bearer token to the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Step 4: Handle token refresh. Access tokens expire. If your plugin supports OAuth token refresh, ensure the refresh token is stored and used correctly. Note that when a refresh token is used, both the access and refresh tokens are invalidated, and a new pair is provided .

Alternative: Personal Access Tokens. Keap also supports Personal Access Tokens (PAT), which are simpler for scripting integrations. You can create a PAT from Settings → API Settings .

Failure #3: The API Payload Structure Is Incorrect

What you see: Keap returns a 400 Bad Request error. The response mentions "Field is invalid" or "Bad Request."

Why it happens: Keap's API is strict about payload structure. The contact creation endpoint expects a specific JSON format with nested objects for email addresses and phone numbers.

A Keap developer reported: "The error that I am receiving is only this: {message: 'Field is invalid'}. It does not even say what the 'Field' is that is throwing the error!" .

The fix:

Step 1: Start with a minimal payload. For Keap's REST API, a minimal contact creation payload looks like:

{
  "given_name": "[infusionsoft-first-name]",
  "family_name": "[infusionsoft-last-name]",
  "email_addresses": [
    {
      "email": "[infusionsoft-email]",
      "field": "EMAIL1"
    }
  ]
}

Step 2: Use the correct field names. Keap's API uses specific field identifiers:

given_name for first name
family_name for last name
email_addresses as an array with email and field properties
phone_numbers as an array with number and field properties

For phone numbers, you must include the field property: "field": "PHONE1" .

Step 3: Check the Content-Type header. Ensure your request includes:

Content-Type: application/json

Step 4: Use the correct endpoint. The contact creation endpoint is:

https://api.infusionsoft.com/crm/rest/v1/contacts

Note on region codes: If you include an address, the region field must use ISO region codes (e.g., US-CO for Colorado), not plain text abbreviations .

For a deeper dive into JSON structure mapping, read this guide on Contact Form 7 JSON mapping.

Failure #4: Duplicate Contact Detection Is Blocking Creation

What you see: No new contact appears in Keap. The API returns a 200 OK response instead of 201 Created.

Why it happens: Keap's API may detect that a contact with the same email address already exists and return the existing contact instead of creating a new one. This is by design, but it can appear as a failure if you are checking for a new contact.

The fix:

Step 1: Check the API response body. A 200 response means a duplicate was found and the existing contact was returned. A 201 response means a new contact was created .

Step 2: Use the duplicate_option parameter. Keap's API supports a duplicate_option parameter to control duplicate detection. Available values include EmailAndName and EmailAndNameAndCompany .

Step 3: Verify in Keap directly. Search for the contact by email address. If it already exists, the integration is working correctly — it is just updating an existing record rather than creating a new one.

The Debugging Checklist

Work through this sequence every time a contact fails to create:

Step	Action	What It Tells You
1	Check the plugin's API Logs	Was a request sent? What response code came back?
2	Verify field naming prefix	Are fields prefixed with `infusionsoft-`?
3	Check OAuth token	Is it valid and not expired?
4	Inspect the JSON payload	Does it use the correct nested structure?
5	Check for duplicates	Does the contact already exist in Keap?
6	Test with minimal payload	Hardcode values to isolate structure issues.

For a comprehensive breakdown of authentication errors across different APIs, see this guide on Contact Form 7 API authentication errors.

Beyond Contacts: One Form, Multiple Destinations

Once your Keap integration works, you might want to send the same submission to other tools: a different CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can create a Keap contact, add the lead to HubSpot, and send an SMS via Twilio, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Field naming may require the infusionsoft- prefix. Older integrations expect this convention. Rename your CF7 fields accordingly.

OAuth authentication must be configured correctly. Access tokens expire. Ensure your integration can refresh them, or use a Personal Access Token for simpler setups .

Keap's API expects a specific JSON structure. Use email_addresses and phone_numbers arrays with the correct field identifiers .

Duplicate detection may return 200 instead of 201. Check the response code and verify in Keap whether the contact already exists .

Start with a minimal payload. Hardcode a test contact first. Once that creates a record in Keap, add additional fields one at a time.

With the correct field naming, valid OAuth credentials, and a properly structured payload, your CF7-to-Keap integration will create contacts reliably.

CF7 Multi-Step Forms Not Sending All Fields to the API - Why Step Data Goes Missing

Rahul Sharma — Wed, 14 Oct 2026 10:32:08 +0000

You built a multi-step Contact Form 7 form. It works perfectly for email notifications. Every field arrives in your inbox. But when you connect it to an API through the "Contact Form to Any API" plugin, the data is incomplete. Fields from earlier steps are empty. Or worse, the API payload contains nothing at all.

This is one of the most frustrating problems in CF7 API integrations. The form works. The email works. But the API receives missing or empty data.

The good news is that this problem has a specific cause and a clear fix. This guide explains exactly why step data goes missing and how to ensure every field reaches your API.

Why Multi-Step Forms Break API Integrations

The root cause is how CF7 multi-step plugins work under the hood.

Multi-step form plugins split a single CF7 form across multiple pages. The plugin uses browser cookies to store data from earlier steps and pass it to the final submission. This works fine for email notifications because the final form submission contains all the accumulated data.

But when you connect an API integration plugin, the data flow changes. The API plugin intercepts the form submission at a different point in the process. If the multi-step plugin has not yet assembled all the step data into the final submission, the API receives only the fields from the current step.

A WordPress user described exactly this scenario: "I used to connect Contact Form 7 with Microsoft Flow using the 'CF7 to Zapier' plugin, but after changing my form using Contact Form 7 Multi-Step Forms the data isn't passed through anymore. The API works as it should be, but every field is empty."

The Cookie Storage Limit Problem

There is a second, less obvious cause: browser cookie size limits.

Multi-step plugins store step data in cookies. Cookies have a maximum size of approximately 4KB. If your form has many fields or long text inputs, the cookie can exceed this limit. When that happens, data from earlier steps is silently dropped.

A WordPress support thread documented this exact issue: "This plugin uses cookies to store the information from step to step and cookies do have a limit to the amount of information it can hold." The user reported that fields would go missing at random, sometimes step 6, sometimes step 7, and the pattern depended on how much data was entered in earlier steps.

This is why the problem appears intermittent. Short submissions work. Long submissions fail. The cookie limit is the hidden threshold.

The Hidden Field Trap

Even when the cookie storage works correctly, there is another layer of complexity: conditional fields within multi-step forms.

If your form uses conditional logic, fields that appear based on earlier selections may not be included in the final submission at all. A WordPress user reported: "The multistep can catch all the a-1 and b-1 info, but will get null value with a-2 and b-2 as there is no value display on the confirmation letter."

The solution for conditional fields in multi-step forms is to add hidden fields on the later steps that mirror the conditional field names. This ensures the multi-step plugin has a field to populate with the earlier step's data.

How the API Plugin Handles This

The "Contact Form to Any API" plugin provides conditional field logic in its API configuration settings. This allows you to define which fields appear in the API payload based on conditions.

However, the plugin cannot fix a problem that occurs before the form submission reaches it. If the multi-step plugin fails to assemble the full data due to cookie limits or missing hidden fields, the API plugin has nothing to work with.

The integration requires two layers of configuration.

Layer 1: The CF7 Multi-Step Form. Ensure all fields are properly carried through steps using hidden fields where needed.

Layer 2: The API Plugin. Configure conditional field logic to include only the fields that are actually populated for each submission path.

The Debugging Checklist

Work through this sequence when multi-step form fields are missing from the API payload:

Step	Action	What It Tells You
1	Check the plugin's API Logs	Does the logged payload show missing fields?
2	Test with a short submission	If short submissions work, the cookie limit is the issue
3	Test with a long submission	If long submissions fail, cookie storage is the bottleneck
4	Add hidden fields to later steps	Ensures conditional field data is carried through
5	Verify field names are unique	Duplicate names cause data overwrites
6	Check for page caching	Caching can prevent form data from passing correctly

For a deeper dive into JSON structure mapping and conditional payload construction, read this guide on Contact Form 7 JSON mapping.

Solutions That Work

Solution 1: Reduce Form Data Volume

If you are hitting the cookie limit, reduce the amount of data stored per step. Use shorter field names, limit textarea lengths, and avoid storing unnecessary data in the form.

Solution 2: Use Hidden Fields for Conditional Data

For conditional fields within multi-step forms, add hidden fields on the final step that mirror the conditional field names. The multi-step plugin will populate these hidden fields with the earlier step's data.

Example hidden field on the final step:

[hidden tour-bhutan]
[hidden tour-nepal]

This ensures the conditional field values are included in the final submission.

Solution 3: Switch to a Database-Backed Multi-Step Plugin

Some multi-step plugins save submission data to the WordPress database instead of cookies. This eliminates the cookie size limit entirely. The API plugin can then retrieve the full submission data from the database.

Solution 4: Disable Page Caching for Form Pages

Caching plugins can interfere with multi-step form data flow. Exclude pages containing multi-step forms from caching.

The Two-Layer Configuration Approach

Once the form data is flowing correctly, configure the API plugin's conditional logic.

In the CF7 form: Use conditional fields and hidden fields to ensure all data is captured.

In the API plugin: Use conditional field logic (Equals / Not Equals) to include only populated fields in the payload. This prevents empty fields from cluttering your CRM.

For a comprehensive breakdown of authentication and error handling across different APIs, see this guide on Contact Form 7 API authentication errors.

Beyond Multi-Step: One Form, Multiple Destinations

Once your multi-step form data flows correctly to your API, you might want to send the same submission to other tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Multi-step plugins store step data in cookies. Cookies have a size limit. Long forms or many fields can exceed it, causing silent data loss.

Conditional fields need hidden field mirrors. Add hidden fields on later steps to ensure conditional field data is carried through to the final submission.

The API plugin cannot fix missing form data. It can only map what the form submission provides. Ensure the multi-step plugin delivers complete data first.

Page caching can break multi-step data flow. Exclude form pages from caching.

Test with short and long submissions. If short works and long fails, you are hitting the cookie limit.

With the right hidden fields, reduced data volume, and proper conditional mapping in the API plugin, your multi-step CF7 forms will deliver complete data to your API on every submission.

CF7 eCommerce Contact Form to Order/ERP API: A Complete Implementation Guide

Rahul Sharma — Tue, 13 Oct 2026 11:26:07 +0000

An eCommerce store often needs more than just a standard "contact us" form. Customers submit custom order requests, ask about bulk pricing, or inquire about product availability. Manually copying this data from form submission emails into your ERP or order management system is slow, error-prone, and does not scale.

This guide walks through how to automate the process using Contact Form 7 and the "Contact Form to Any API" plugin, sending eCommerce inquiries directly into your order or ERP API as structured records.

Why eCommerce Forms Need ERP Integration

eCommerce contact forms generate data that belongs in your order pipeline, not in an inbox.

Custom order requests. A customer filling out a form for a custom product needs that request to become an order or a quote in your system, with all the product details attached.

Bulk and B2B inquiries. Wholesale customers often submit forms with quantity requests. This data needs to flow into your ERP for pricing, inventory checks, and fulfillment planning.

Product-specific questions. When a customer asks about a specific SKU, that inquiry should be linked to the product record in your ERP for the sales team to follow up.

Without automation, every inquiry is a manual data entry task. With automation, every submission becomes a structured record ready for processing.

The Architecture: CF7 → API Plugin → ERP/Order API

The integration follows a straightforward path:

CF7 Form → Contact Form to Any API → ERP/Order API → Record Created

The plugin sends form submissions directly to your API endpoint using secure methods. It supports any endpoint that accepts POST or GET requests with structured data, including ERP systems like Odoo, Sage CRM, and custom order management APIs.

eCommerce Form Fields That Matter

A custom order or product inquiry form needs specific fields that map to your ERP or order API. Here is a field set designed for eCommerce integration:

CF7 Field	Purpose	ERP/Order API Mapping
`your-name`	Customer name	`contact_name` or `customer_name`
`your-email`	Email address	`email_from` or `customer_email`
`your-phone`	Phone number	`phone`
`product-sku`	Product identifier	`product_id` or `item_code`
`quantity`	Requested quantity	`product_qty`
`product-notes`	Customization details	`description` or `note`
`budget`	Budget indication (for quotes)	`expected_revenue`
`your-message`	Additional message	`description`

These fields map directly to standard order and ERP lead fields.

Setting Up the API Integration

Step 1: Configure the ERP/Order API Endpoint

In the "Contact Form to Any API" plugin settings, enter your ERP's API endpoint. For Odoo, this is typically the JSON-RPC or XML-RPC endpoint. For other systems, consult the API documentation for the order or lead creation endpoint.

Step 2: Map CF7 Fields to ERP Fields

The plugin provides field mapping between CF7 form fields and the API payload parameters. The mapping syntax follows this pattern:

Form Fields → API Parameters

[your-name]    → contact_name
[your-email]   → email_from
[product-sku]  → product_id
[quantity]     → product_qty

For a deeper dive into JSON structure mapping, read this guide on Contact Form 7 JSON mapping.

Step 3: Configure Authentication

ERP systems often require robust authentication. The plugin supports Basic Auth, API Key, and Bearer Token headers. For OAuth 2.0 flows, the PRO add-on handles automatic token renewal, ensuring integrations continue running without interruption.

A critical note on Basic Auth: The plugin's header field is a static textarea. PHP functions like base64_encode() do not execute when placed directly in this field. You must manually encode your credentials before pasting them into the header.

Step 4: Build the JSON Payload

The payload structure depends on your ERP's API requirements. A typical custom order or quote request payload might look like:

{
  "name": "Custom Order - [product-sku]",
  "contact_name": "[your-name]",
  "email_from": "[your-email]",
  "phone": "[your-phone]",
  "product_id": "[product-sku]",
  "product_qty": "[quantity]",
  "description": "[product-notes]",
  "type": "lead"
}

eCommerce Specific Considerations

Product SKU as Order Context

When a customer submits an inquiry about a specific product, the SKU should be included in the record. This allows your ERP to link the inquiry to the correct product for pricing, inventory, and fulfillment checks. Map a hidden CF7 field containing the product SKU to the ERP's product field.

Example hidden field in CF7:

[hidden product-sku default:get "sku"]

This captures the SKU from the page URL or a shortcode parameter.

Quantity and Pricing Logic

For bulk or custom orders, the quantity field is critical. Your ERP may need to calculate pricing based on quantity tiers or check available inventory. The API payload should include the requested quantity so the ERP can perform these calculations automatically.

Order vs Lead: Which Record Type?

Some ERP systems distinguish between a "lead" (unqualified inquiry) and an "order" (confirmed purchase). For eCommerce contact forms, the appropriate record type depends on your workflow.

Lead/Quote: If the customer is inquiring about a product and needs a price quote before committing.

Order: If the form is a direct order submission with all required payment and shipping details.

The payload's type field determines which record is created in the ERP.

Common Challenges and Solutions

ERP integrations have specific pitfalls. Here are the most common ones and how to avoid them.

Authentication Failures. ERP systems often use OAuth 2.0 or token-based access. If tokens expire or are misconfigured, data transmission halts without warning. Solution: Use token refresh logic and test authentication during setup.

ERP System Downtime. If your ERP goes offline for maintenance, form submissions cannot be delivered. Solution: Set up a retry mechanism that queues failed submissions and resends them once the ERP is back online.

Field Mapping Errors. Data gets lost or misrouted when fields between CF7 and the ERP are not accurately mapped. Solution: Perform field audits before going live.

Format Mismatches. ERPs have strict requirements for data format. Dates might need ISO standards, or dropdown values must match predefined codes. Solution: Use transformation logic to sanitize and validate data before submission.

Missing Required Fields. If the ERP API requires a field that is not mapped or is left empty, the request fails. Solution: Ensure all required fields are mapped and never empty.

The Debugging Checklist

Work through this sequence when an eCommerce form fails to create an ERP record:

Step	Action	What It Tells You
1	Check the plugin's API Logs	Was a request sent? What response code came back?
2	Inspect the response code	401 = Auth issue. 422 = Payload issue. 500 = ERP server error.
3	Verify Basic Auth encoding	Is the header manually Base64 encoded?
4	Check the endpoint URL	Does it target the correct ERP API endpoint?
5	Verify field mapping	Are all required fields mapped and populated?
6	Test with minimal payload	Hardcode values to isolate structure issues from mapping issues.
7	Test credentials in Postman	Isolates plugin issues from API issues.

For a comprehensive breakdown of authentication errors across different APIs, see this guide on Contact Form 7 API authentication errors.

Beyond ERP: One Form, Multiple Destinations

Once your ERP integration works, you might want to send the same submission to other tools: an email marketing platform, a help desk system, or a notification service.

A good connector plugin supports multiple API integrations from a single form submission. You can create an ERP record, subscribe the contact to Mailchimp, and send an SMS notification via Twilio, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

eCommerce form data belongs in your ERP, not your inbox. Automate the flow from CF7 submission to ERP record.

Authentication is the most fragile part of the integration. Use token refresh for OAuth systems, and manually Base64-encode Basic Auth credentials before pasting them into the plugin's header field.

Field mapping must be exact. Match CF7 field names to your ERP's API field names precisely. Perform field audits before going live.

Start with a minimal payload. Hardcode a test record first. Once that works, add product-specific fields one at a time.

Plan for failures. ERP downtime and API errors will happen. Implement retry logic and monitor the plugin's logs to catch issues early.

With the correct API configuration, field mapping, and authentication, your CF7 eCommerce forms will deliver custom order requests and product inquiries directly into your ERP pipeline. No manual data entry, no missed opportunities, no delay.

CF7 Real Estate Lead Capture to CRM: A Complete Implementation Guide

Rahul Sharma — Sat, 10 Oct 2026 08:02:04 +0000

Real estate websites live and die by lead response time. When a potential buyer submits an inquiry about a property, every minute of delay reduces the chance of conversion. Manual copy-pasting from form submission emails into a CRM is not just inefficient; it directly costs you deals.

This guide walks through how to build an automated real estate lead capture pipeline using Contact Form 7 and the "Contact Form to Any API" plugin, sending every submission directly into your CRM as a structured lead.

Why Real Estate Lead Capture Needs Automation

Real estate lead generation has unique characteristics that make automation essential.

Volume and urgency. A single property listing can generate dozens of inquiries per day. Each inquiry needs a timely response. Manual processing cannot scale.

Structured data requirements. Real estate leads need specific fields: name, email, phone, property ID, inquiry type (schedule a viewing, request information, make an offer), budget range, and timeline. Sending this as an unstructured email means manual data entry into the CRM.

Team assignment. Most real estate teams route leads by property type, price range, or location. Automated CRM creation allows immediate assignment rules to fire.

The Architecture: CF7 → API Plugin → CRM

The cleanest approach for real estate lead capture uses three components:

CF7 Form (property inquiry) → Contact Form to Any API → CRM Lead Creation

This is the recommended practical approach for eliminating manual data entry. The setup is straightforward: add your CRM API endpoint in the plugin settings, map your form fields like name, email, and phone to CRM lead fields, and every form submission automatically creates a lead.

Real Estate Form Fields That Matter

A real estate inquiry form should capture more than just name and email. Here is a field set that supports CRM lead creation and routing:

CF7 Field	Purpose	CRM Mapping
`your-name`	Lead name	`contact_name`
`your-email`	Email address	`email_from`
`your-phone`	Phone number	`phone`
`property-id`	Which property they inquired about	`description` or custom field
`inquiry-type`	Schedule viewing / Request info / Make offer	`lead_source` or `description`
`budget-range`	Budget indication	Custom field
`timeline`	How soon they want to buy or rent	Custom field
`your-message`	Free-text message	`description`

These fields map directly to standard CRM lead fields: name, contact_name, email_from, phone, and description.

Setting Up the API Integration

Step 1: Configure the CRM Endpoint

In the "Contact Form to Any API" plugin settings, enter your CRM's API endpoint. For most CRMs, this is the REST API endpoint for lead creation. Consult your CRM's API documentation for the exact URL.

Step 2: Map CF7 Fields to CRM Fields

The plugin provides field mapping between CF7 form fields and the API payload parameters. The mapping works like this:

Form Fields → API Parameters

[your-name]    → contact_name
[your-email]   → email_from
[your-phone]   → phone
[your-message] → description

For real estate, you would extend this with property-specific fields like property-id, inquiry-type, and budget-range.

Step 3: Configure Authentication

Most CRM APIs require authentication. The plugin supports Bearer Token, API Key, and Basic Auth headers. Check your CRM's documentation for the required method. For a full breakdown of authentication options, see this guide on Contact Form 7 API authentication errors.

Step 4: Build the JSON Payload

The payload structure depends on your CRM's API requirements. A typical lead creation payload for real estate would look like:

{
  "name": "Website Lead - [your-name]",
  "contact_name": "[your-name]",
  "email_from": "[your-email]",
  "phone": "[your-phone]",
  "description": "[your-message]",
  "type": "lead"
}

For a deeper dive into JSON structure mapping, read this guide on Contact Form 7 JSON mapping.

Real Estate Specific Considerations

Property ID as Lead Context

When a visitor inquires about a specific property, the property ID should be included in the lead. In the CRM, this allows the sales team to see exactly which property the lead is interested in. Map a hidden CF7 field containing the property ID to a CRM custom field or the description field.

Example hidden field in CF7:

[hidden property-id default:get "property-id"]

This captures the property ID from the page URL or a shortcode parameter.

Inquiry Type Routing

Different inquiry types require different follow-up. A "schedule viewing" request needs a calendar link. A "make offer" request needs immediate escalation. By mapping inquiry-type to a CRM field, you can configure CRM automation rules to route leads appropriately.

Duplicate Prevention

Real estate leads often submit multiple inquiries. You can add a hidden CF7 field with a unique timestamp or use CRM-side deduplication rules to prevent duplicate records.

Beyond Lead Creation: What Happens Next

Once leads are in the CRM, real estate teams need:

Instant assignment. CRM automation rules assign leads to agents based on property type, location, or round-robin.

Follow-up sequences. Email and SMS sequences trigger based on lead source and inquiry type.

Pipeline tracking. Leads move through stages: New → Contacted → Viewing Scheduled → Offer Made → Closed.

Reporting. Which properties generate the most leads? Which agents convert best? What is the average response time?

All of these depend on clean, structured lead data entering the CRM. That is what the CF7 → API integration delivers.

Common Challenges and Solutions

Challenge	Solution
API authentication fails	Verify the correct auth method (Bearer vs API Key vs Basic)
Required fields missing	Ensure all CRM-required fields are mapped and never empty
Wrong data format	Match the payload structure to CRM API documentation
Property ID not captured	Add a hidden CF7 field populated from the page URL or shortcode parameter
Duplicate leads	Use unique identifiers or CRM-side deduplication rules

Beyond Real Estate: One Form, Multiple Destinations

Once your real estate lead capture works, you might want to send the same form submission to other tools: an email marketing platform, a help desk system, or an SMS notification service.

A good connector plugin supports multiple API integrations from a single form submission. You can create a CRM lead, subscribe the contact to Mailchimp, and send an SMS notification via Twilio, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Real estate lead capture requires structured data, not email text. Map name, email, phone, property ID, and inquiry type to CRM fields.

The CF7 → API → CRM architecture eliminates manual data entry. Every form submission creates a CRM lead automatically.

Field mapping is the core configuration. Match CF7 field names to your CRM's API field names exactly.

Start with a minimal payload. Hardcode a test lead first. Once that creates a CRM record, add property-specific fields one at a time.

CRM automation depends on clean data. Assignment rules, follow-up sequences, and reporting all require structured lead fields from the form.

With the correct API configuration, field mapping, and property-specific context, your CF7 real estate forms will deliver leads directly into your CRM pipeline. No manual data entry, no missed inquiries, no delay.

CF7 to Agile CRM Integration Breaking: A Complete Troubleshooting Guide

Rahul Sharma — Fri, 09 Oct 2026 12:31:19 +0000

You have built a Contact Form 7 form. You have connected it to Agile CRM through the "Contact Form to Any API" plugin. You have entered your domain, email, and API key. And yet, when a user submits the form, nothing happens. No contact appears in Agile CRM. The integration is broken.

Understanding the Data Flow

When a user submits your CF7 form with Agile CRM integration enabled, here is what should happen:

User submits form → Plugin captures data → POST request sent to Agile CRM → Contact created

When it breaks, the failure happens at one of the last two stages. Your first diagnostic tool is the plugin's API Logs page. It shows whether a request was sent, the exact JSON payload, and the response from Agile CRM. If no request appears in the logs, the problem is on the WordPress side. For a deeper breakdown of that specific scenario, see this guide on Contact Form 7 data not reaching the API.

Failure 1: The Basic Auth Header Is Incorrectly Formatted

What you see: The plugin's logs are empty, or Agile CRM returns a 401 Unauthorized error.

Why it happens: The "Contact Form to Any API" plugin provides a static textarea for request headers. PHP functions like base64_encode() do not execute when placed directly in this textarea . If you paste Authorization: Basic ' . base64_encode( YOUR_USERNAME . ':' . YOUR_PASSWORD ) into the header field, the plugin sends that literal string to Agile CRM. The credentials are never encoded, and authentication fails.

The fix:

You must manually encode your credentials before pasting them into the plugin.

Step 1: Generate a Base64-encoded string from your username:password combination. You can use any online Base64 encoder or a local tool.

For example, if your Agile CRM email is admin@example.com and your API key is abc123, you would encode admin@example.com:abc123.

Step 2: Copy the resulting Base64 string (for example, YWRtaW5AZXhhbXBsZS5jb206YWJjMTIz).

Step 3: In the plugin's header field, paste:

Authorization: Basic YWRtaW5AZXhhbXBsZS5jb206YWJjMTIz
Content-Type: application/json

How to verify: After saving, submit a test form. Check the plugin's API Logs. A 200 OK response means authentication succeeded.

Failure 2: The Endpoint URL or Request Method Is Wrong

What you see: Agile CRM returns a 404 Not Found or 405 Method Not Allowed error.

Why it happens: Agile CRM has a specific endpoint for contact creation. Using the wrong URL or HTTP method will cause the request to fail.

The fix:

Step 1: Verify the endpoint URL. According to Agile CRM's API documentation, the endpoint for creating contacts is:

https://yourdomain.agilecrm.com/dev/api/contacts

Replace yourdomain with your actual Agile CRM subdomain (for example, mycompany for https://mycompany.agilecrm.com).

Step 2: Verify the request method. Contact creation requires POST, not GET or PUT.

Step 3: Check the plugin settings. In the "Contact Form to Any API" integration settings, ensure:

The API Endpoint field contains the correct URL
The Request Method is set to POST

Failure 3: The JSON Payload Structure Is Invalid

What you see: Agile CRM returns a 400 Bad Request error. The response mentions invalid JSON or missing required fields.

Why it happens: Agile CRM's API expects a specific JSON structure. Sending flat key-value pairs instead of the expected nested format will cause the request to fail.

The fix:

Agile CRM's contact creation endpoint expects a payload with a properties array. Each property has a type, name, and value.

Correct structure:

{
  "properties": [
    {
      "type": "SYSTEM",
      "name": "first_name",
      "value": "[your-name]"
    },
    {
      "type": "SYSTEM",
      "name": "email",
      "value": "[your-email]"
    },
    {
      "type": "SYSTEM",
      "name": "phone",
      "value": "[your-phone]"
    }
  ]
}

Key requirements:

The root key must be properties.
Each property must have type, name, and value.
Common type values are SYSTEM for built-in fields and CUSTOM for custom fields.
Field names must match Agile CRM's system field names exactly.

For a deeper dive into JSON structure mapping and payload construction, read this guide on Contact Form 7 JSON mapping.

Failure 4: The API Key or User Permissions Are Incorrect

What you see: Agile CRM returns a 401 Unauthorized or 403 Forbidden error.

Why it happens: Agile CRM requires the REST API key, not your login password. Additionally, the user account associated with the API key must have sufficient permissions .

The fix:

Step 1: Get the correct API key. In Agile CRM, navigate to Admin Settings → Developers & API. Copy the REST API key from this page. Do not use your account password.

Step 2: Use the correct email. The username in your Basic Auth header must be the email address you use to log in to Agile CRM, not a display name or alias .

Step 3: Check user permissions. The API key must belong to a user with admin-level or appropriate role permissions. Non-admin users may have restricted API access, causing a 403 error .

How to verify: Test your credentials in Postman or a similar tool before configuring the plugin. If authentication fails there, it will fail in the plugin too.

For a comprehensive breakdown of authentication errors across different APIs, see this guide on Contact Form 7 API authentication errors.

The Debugging Checklist

Work through this sequence every time an Agile CRM integration fails:

Step	Action	What It Tells You
1	Check the plugin's API Logs	Was a request sent? If empty, the problem is in WordPress.
2	Inspect the response code	401 = Auth issue. 400 = Payload issue. 404 = Endpoint issue.
3	Verify Base64 encoding	Is the Authorization header properly encoded?
4	Check the endpoint URL	Does it target `/dev/api/contacts`?
5	Verify request method is POST	Agile CRM expects POST for contact creation.
6	Inspect the JSON structure	Does it use the `properties` array format?
7	Test credentials in Postman	Isolates plugin issues from API issues.

Beyond Agile CRM: One Form, Multiple Destinations

Once your Agile CRM integration works, you might want to send the same form submission to other tools: a different CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can create an Agile CRM contact, add the lead to HubSpot, and send an SMS via Twilio, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Base64 encoding must be done manually. The plugin's header textarea does not execute PHP functions. Encode your credentials externally before pasting them into the header field .

The endpoint is /dev/api/contacts. Use POST, not GET or PUT.

Agile CRM expects a properties array. Flat JSON objects will not work. Each field needs type, name, and value.

Use the REST API key, not your password. The username must be your Agile CRM login email. Admin permissions are recommended for full API access .

The plugin's API Logs show exactly what was sent. Use them to compare your request against Agile CRM's requirements.

With the correct Base64 encoding, proper endpoint, and a valid properties array payload, your CF7-to-Agile CRM integration will create contacts reliably.

CF7 to Pipedrive Organization Not Being Created: A Complete Troubleshooting Guide

Rahul Sharma — Thu, 08 Oct 2026 04:57:45 +0000

You have built a Contact Form 7 form. You have connected it to Pipedrive through the "Contact Form to Any API" plugin. You have entered your API token and mapped the fields. And yet, when a user submits the form, no organization appears in your Pipedrive account.

Understanding Pipedrive's Data Model

Before debugging, you need to understand that Pipedrive separates data into distinct objects. Organizations are not the same as Persons (Contacts) or Deals.

According to Pipedrive's official documentation, each object lives in a different part of the CRM:

Object	What It Is	API Endpoint
Person (Contact)	A CRM contact record - name, email, phone	POST /v1/persons
Organization	A company record that groups contacts	POST /v1/organizations
Deal	An active sales opportunity	POST /v1/deals
Lead	A pre-qualified prospect	POST /v1/leads

If your integration is targeting the wrong endpoint, you will create the wrong object or nothing at all.

Failure #1: The Endpoint URL Is Wrong

What you see: No organization is created. The API logs show a successful request (200 OK), but the data lands in the wrong place — or nowhere.

Why it happens: The "Contact Form to Any API" plugin requires you to manually enter the API endpoint URL. If you paste the URL for persons or deals instead of organizations, the plugin will create a person or deal, not an organization.

The fix:

Verify your endpoint URL in the plugin settings. For creating organizations, it must be:

https://{COMPANYDOMAIN}.pipedrive.com/api/v2/organizations?api_token=YOUR_API_TOKEN

Replace {COMPANYDOMAIN} with your actual Pipedrive company domain.

How to verify: After submitting a test form, check your Pipedrive account. Navigate to the Organizations section (sometimes labeled "Companies" or under the Contacts menu). If no new organization appears, the endpoint is wrong.

For a deeper dive into JSON structure mapping and payload construction, read this guide on Contact Form 7 JSON mapping.

Failure #2: The Required "Name" Field Is Missing

What you see: The API returns a 400 Bad Request error. The response mentions a missing required field.

Why it happens: Pipedrive's API requires only one field for organization creation: name. According to Pipedrive's official tutorial, "When adding an Organization, there's only one required parameter you have to give a value to - the Organization name" .

If your CF7 form does not include a field mapped to name, or if that field is left empty, Pipedrive will reject the request.

The fix:

Step 1: Verify your mapping. In the plugin's JSON Payload section, ensure at least one CF7 field is mapped to the Pipedrive name field. This could be a company name field, or a concatenation of first and last name.

Step 2: Use a hidden field if needed. If your form does not have a natural field for the organization name, add a hidden field with a default value:

[hidden organization-name default:get "Website Lead"]

Step 3: Check the payload structure. Your JSON should look like:

{
  "name": "[your-company]"
}

Even if you want to send additional fields like address or phone, name must always be present.

Failure #3: The API Token Is Invalid or Missing

What you see: The API returns a 401 Unauthorized or 403 Forbidden error. No organization is created.

Why it happens: Pipedrive requires authentication for all API requests. The "Contact Form to Any API" plugin needs your API token to be correctly configured.

The fix:

Step 1: Get a fresh API token. In Pipedrive, click your profile icon, open Personal Preferences, and go to the API section. Copy your API token.

Step 2: Configure authentication in the plugin. In the plugin's authentication settings, add your API token. Depending on the plugin version, this may be a dedicated field or part of the request headers.

Step 3: Check permissions. According to Pipedrive's documentation, users need the can_add_organizations permission to create organizations via the API. If this permission is disabled for your user, the API returns a 403 error.

For a comprehensive breakdown of authentication errors across different APIs, see this guide on Contact Form 7 API authentication errors.

Failure #4: The Payload Structure Is Incorrect

What you see: The API returns a 400 Bad Request error with a message about invalid JSON or unexpected fields.

Why it happens: Pipedrive's API expects a specific JSON structure. If your payload includes fields that don't exist on the Organization object, or if the JSON is malformed, the request will fail.

The fix:

Step 1: Start with a minimal payload. Use only the required name field:

{
  "name": "[your-company]"
}

Step 2: Add fields one at a time. Once the minimal payload works, add additional fields like address, phone, or custom fields. Test after each addition.

Step 3: Use the correct field names. Pipedrive's Organization object supports fields like name, owner_id, visible_to, address, and custom fields. Field names must match exactly.

Step 4: Check Content-Type header. Ensure your request includes:

Content-Type: application/json

Without this header, Pipedrive may not parse the payload correctly.

The Debugging Checklist

Work through this sequence every time an organization fails to create:

Step	Action	What It Tells You
1	Check the plugin's API Logs	Was a request sent? What response code came back?
2	Verify the endpoint URL	Does it target `/organizations`?
3	Confirm `name` field is mapped	Is the required field present in the payload?
4	Check API token	Is it valid and does it have `can_add_organizations` permission?
5	Test with minimal payload	Hardcode a `name` value to isolate mapping issues.
6	Inspect the JSON structure	Is it valid JSON? Are field names correct?

Beyond Organizations: Creating Related Records

Once you can create organizations reliably, you may want to create related records. Pipedrive's data model connects these objects:

Organization → Person: A person can be linked to an organization via org_id.
Organization → Deal: A deal can be linked to an organization via org_id.
Person → Deal: A deal can be linked to a person via person_id.

If you want to create a deal and associate it with an organization, you need to:

Create the organization first.
Capture the returned organization_id.
Use that ID when creating the deal.

This requires either multiple API calls in sequence or a plugin that supports multi-step API workflows. For a cost comparison of automation options, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Pipedrive separates Organizations, Persons, and Deals into distinct API endpoints. Using the wrong endpoint creates the wrong object or nothing at all.

The name field is the only required field for organization creation. Ensure it is mapped and never empty.

API tokens must have the can_add_organizations permission. Without it, Pipedrive returns a 403 error.

Start with a minimal payload. Hardcode the name value first. Once that works, add additional fields one at a time.

The plugin's API Logs show exactly what was sent. Use them to compare your request against Pipedrive's requirements.

With the correct endpoint, a valid API token, and a properly structured payload containing the required name field, your CF7-to-Pipedrive integration will create organizations reliably.

CF7 Conditional Logic + API: Send Different Data Based on Field Value

Rahul Sharma — Wed, 07 Oct 2026 04:44:20 +0000

You have built a Contact Form 7 form with conditional logic. When a user selects "Support" from a dropdown, additional fields appear asking for their order number. When they select "Sales," different fields appear asking about their company size.

But when the form submits, all this data regardless of which fields were visible gets sent to your API. The CRM receives empty fields for the hidden questions, and your team has to manually sort through irrelevant data.

This is where conditional API logic comes in. Instead of sending everything, you can configure your integration to send only the data that matters, based on what the user actually selected.

The Problem with Sending Everything

Contact Form 7's conditional fields plugin hides fields visually, but it does not remove them from the form submission. This means every field is always submitted, even if the user never saw it.

For a CRM integration, this creates several problems:

Empty fields clutter your CRM. A lead record shows "Order Number: (empty)" and "Company Size: (empty)" alongside the fields that actually matter.
Automation triggers incorrectly. If your CRM workflow is based on field values, empty fields can cause the wrong automation to fire.
Data quality suffers. Your team cannot distinguish between "the user skipped this field" and "this field was not applicable."

How Conditional API Logic Solves This

The solution is to configure your API integration so that different conditions produce different payloads.

The "Contact Form to Any API" plugin supports conditional field logic in its API configuration. This means you can define rules like:

If inquiry-type equals "Support", send order-number and issue-description to the API.
If inquiry-type equals "Sales", send company-size and budget-range instead.
If budget-range is greater than 10000, send the lead to a different API endpoint entirely.

The result: your CRM receives clean, relevant data for every submission.

Setting Up Conditional Logic: The Two Layers

Conditional logic in a CF7-to-API integration involves two distinct layers.

Layer 1: CF7 Form Conditional Fields

First, you need conditional fields in your form itself. This is handled by a plugin like Conditional Fields for Contact Form 7.

This plugin lets you wrap form fields in [group] tags. Fields inside a group are hidden by default and only appear when a condition is met.

Example:

[select* inquiry-type "Support" "Sales" "Billing"]

[group support-fields]
[text* order-number placeholder "Order Number"]
[textarea* issue-description placeholder "Describe the issue"]
[/group]

[group sales-fields]
[text company-size placeholder "Company Size"]
[text budget-range placeholder "Budget Range"]
[/group]

You then configure conditions in the Conditional Fields tab: support-fields shows when inquiry-type equals "Support", and sales-fields shows when inquiry-type equals "Sales".

Layer 2: API Conditional Logic

This is where the API plugin's conditional feature comes in. In the "Contact Form to Any API" plugin settings, you configure which fields to send based on the same conditions.

The plugin's version 5.1.1 changelog confirms: "New - Added conditional field logic functionality in API configuration".

You define a condition in the API settings: "Only include order-number in the payload when inquiry-type equals 'Support'."

The plugin then evaluates this condition at submission time and builds the JSON payload accordingly.

A Practical Example: Routing Leads by Inquiry Type

Imagine you run a service business with two distinct offerings: residential and commercial. You want residential leads to go to your standard CRM, and commercial leads to go to a separate enterprise CRM.

Your CF7 form:

[select* customer-type "Residential" "Commercial"]

[group residential-fields]
[text* home-address placeholder "Home Address"]
[select* service-type "Cleaning" "Repair" "Installation"]
[/group]

[group commercial-fields]
[text* company-name placeholder "Company Name"]
[text* employee-count placeholder "Number of Employees"]
[select* contract-type "Monthly" "Annual" "Project-Based"]
[/group]

Your API integration setup:

Endpoint 1 (Residential CRM):

Condition: customer-type equals "Residential"
Payload: name, email, phone, home-address, service-type

Endpoint 2 (Commercial CRM):

Condition: customer-type equals "Commercial"
Payload: name, email, phone, company-name, employee-count, contract-type

With this configuration, a residential lead triggers a clean API call with only residential data. A commercial lead triggers a separate call with only commercial data. The CRMs never receive irrelevant empty fields.

Common Mistakes with Conditional API Logic

Using the same field name in multiple groups.

All field names in a CF7 form must be unique, even if they are in different conditional groups. If you have two groups both containing a field named your-email, the last group's value will overwrite the others, and your API will receive the wrong data.

Correct approach: Use unique names like residential-email and commercial-email, or map a single shared field outside the groups.

Forgetting that hidden fields are still submitted.

CF7's conditional fields plugin hides fields but does not remove them from the form submission. This means your API plugin will see all fields, including the hidden ones. You must configure the API plugin's conditional logic to exclude hidden fields from the payload.

Assuming the API plugin inherits CF7's conditional settings.

The "Contact Form to Any API" plugin has its own conditional logic settings. These are separate from the CF7 Conditional Fields plugin settings. You must configure both: one controls what the user sees, the other controls what the API receives.

Debugging Conditional API Issues

If your conditional API logic is not working, check these points:

Symptom	Likely Cause	Fix
All fields sent regardless of condition	API conditional logic not configured	Add conditions in the API plugin settings
Wrong field values sent	Duplicate field names across groups	Rename fields to be unique
Condition never triggers	Field name mismatch	Verify the exact field name used in the condition
Empty payload sent	Condition syntax error	Check Equals / Not Equals syntax in plugin settings

For a deeper dive into JSON structure mapping and conditional payload construction, read this guide on Contact Form 7 JSON mapping.

Beyond Basic Conditions: Advanced Routing

Once you have basic conditional logic working, you can build more sophisticated routing rules:

Multi-condition rules: Send a lead to Endpoint A only when customer-type equals "Commercial" AND employee-count is greater than 500.

Nested conditions: If service-type equals "Installation", include a site-survey-required field. If service-type equals "Repair", include a warranty-number field instead.

Fallback payloads: Define a default payload that sends when no other condition matches. This prevents empty API calls when the user's input does not fit any predefined pattern.

The plugin's conditional field support uses Equals and Not Equals operators, which covers the majority of routing scenarios. For more complex comparisons like greater than or less than, you may need the PRO version or a custom hook.

Beyond Conditional Logic: One Form, Multiple Destinations

Once your conditional routing works, you might want to send different subsets of data to multiple tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can route commercial leads to Salesforce, residential leads to HubSpot, and send an SMS notification via Twilio, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

CF7 conditional fields hide fields but do not remove them from submission. You need API-level conditional logic to control what actually gets sent.

The "Contact Form to Any API" plugin supports conditional field logic. Version 5.1.1 added "conditional field logic functionality in API configuration".

Two layers of configuration are required. One in the CF7 form to show/hide fields, and one in the API plugin to include/exclude fields from the payload.

Field names must be unique across all conditional groups. Duplicate names cause data overwrites and incorrect API payloads.

Conditional API logic prevents empty fields from cluttering your CRM. This improves data quality and makes CRM automation more reliable.

With conditional logic configured at both the form and API layers, your integration sends exactly the data that matters for each submission. No more, no less.

CF7 to Custom REST API Returning 415 Unsupported Media Type: A Complete Troubleshooting Guide

Rahul Sharma — Tue, 06 Oct 2026 11:32:54 +0000

You have built a Contact Form 7 form. You have connected it to your custom REST API through a connector plugin. You have mapped the fields and configured the endpoint. And yet, the API returns a 415 Unsupported Media Type error.

This is one of the most common HTTP errors when integrating CF7 with custom APIs. The good news? It has a single root cause and a straightforward fix. This guide explains exactly what triggers a 415 error and how to resolve it.

What Does 415 Unsupported Media Type Mean?

A 415 error means the server refuses to process the request because the payload format is not supported. In plain terms: the API expects data in one format, but your form is sending it in another.

The server is saying: "I understand your request, but I cannot read the body because the Content-Type you declared does not match what I accept."

The Root Cause: Missing or Incorrect Content-Type Header

The 415 error occurs when the Content-Type header in your API request does not match what the endpoint expects.

Every HTTP request that includes a body must declare what kind of data it contains. This declaration is the Content-Type header. Common values include:

application/json for JSON payloads
multipart/form-data for form submissions with files
application/x-www-form-urlencoded for simple form data

If you omit this header, or if you set it to the wrong value, the API rejects the request with a 415 error.

A concrete example from CF7's own REST API: Contact Form 7's feedback endpoint expects multipart/form-data. If you send a POST request with Content-Type: application/json, the endpoint returns exactly this error:

{
  "code": "wpcf7_unsupported_media_type",
  "message": "The request payload format is not supported.",
  "data": {
    "status": 415
  }
}

This is the same problem you will encounter with any custom REST API that has specific content-type requirements.

The Fix: Add the Correct Content-Type Header

The solution is to explicitly declare the content type your API expects. In the "Contact Form to Any API" plugin, you configure this in the Header Request section of your API integration settings.

Step 1: Determine What Your API Expects

Check your API documentation. Look for the Content-Type it accepts. Common scenarios:

API Type	Expected Content-Type
REST API accepting JSON	`application/json`
Legacy form endpoint	`application/x-www-form-urlencoded`
CF7 native feedback endpoint	`multipart/form-data`
File upload endpoint	`multipart/form-data`

Step 2: Add the Header in the Plugin

In your plugin's integration settings, navigate to the Header Request or Request Headers field. Add the header:

Content-Type: application/json

Replace application/json with whatever your API actually expects.

The plugin supports custom header configuration, so you can add any Content-Type value your API requires.

Step 3: Match the Payload Format to the Header

Adding the Content-Type header is only half the fix. Your actual payload must match what you declared.

If you set Content-Type: application/json, your body must be valid JSON:

{
  "name": "[your-name]",
  "email": "[your-email]",
  "message": "[your-message]"
}

If you set Content-Type: application/x-www-form-urlencoded, your body should be URL-encoded key-value pairs.

A mismatch between the declared Content-Type and the actual payload format will still result in errors, even if the header is technically correct.

For a deeper dive into JSON structure mapping and payload formatting, read this guide on Contact Form 7 JSON mapping.

Common Scenarios and Their Fixes

Scenario 1: Sending JSON to an API That Expects multipart/form-data

Symptom: 415 error with a message about "request payload format not supported."

Fix: Either change the API's expected format (if you control it) or change your request to send multipart/form-data. Note that sending multipart data from a connector plugin is more complex and may require the plugin's PRO version for file upload support.

Scenario 2: Sending Form Data to a JSON API

Symptom: 415 error, often with a message about "unsupported media type" or "cannot parse request."

Fix: Set Content-Type: application/json in the header, and ensure your body is valid JSON, not form-encoded key-value pairs.

Scenario 3: Missing Content-Type Header Entirely

Symptom: 415 error with no additional context.

Fix: Add the Content-Type header explicitly. Some servers default to a content type that the API does not accept when the header is absent.

The Debugging Checklist

Work through this sequence every time you encounter a 415 error:

Step	Action	What It Tells You
1	Check the plugin's API Logs	Does the log show the request body and headers sent?
2	Verify the Content-Type header	Is it present? Does it match what the API expects?
3	Inspect the payload format	Is it JSON, form data, or something else?
4	Compare with API documentation	What Content-Type does the API explicitly require?
5	Test with Postman	Send the same request with the correct header. Does it succeed?
6	Test a minimal payload	Hardcode values and a single field. Does the 415 persist?

The plugin's API Logs feature is particularly valuable here. It shows the exact request sent, including headers and body, so you can compare what you sent against what the API expects.

For a comprehensive breakdown of authentication and error handling across different APIs, see this guide on Contact Form 7 API authentication errors.

Beyond the 415: Related Errors You Might Encounter

If you fix the Content-Type header but still see errors, check for these related issues:

400 Bad Request: The Content-Type is correct, but the payload structure is wrong. This often means a required field is missing or a value is in the wrong format.

401 Unauthorized: The Content-Type is correct, but your authentication credentials are wrong or missing.

404 Not Found: The endpoint URL is wrong. This can happen if you change the API but forget to update the URL in the plugin settings.

Beyond Error Handling: One Form, Multiple Destinations

Once your Content-Type header is configured correctly, you might want to send the same form submission to multiple tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission, without Zapier. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

A 415 error means the API cannot process the request body because the Content-Type does not match what it expects.

The fix is always the same: add the correct Content-Type header. Check your API documentation to determine whether it expects application/json, multipart/form-data, or another format.

Your payload must match your declared Content-Type. Sending JSON while declaring multipart/form-data will still fail.

The plugin's API Logs show exactly what was sent. Use them to compare your request against the API's requirements.

Test with Postman first. If Postman succeeds with the correct Content-Type and your plugin fails, the problem is in the plugin's header configuration.

With the correct Content-Type header and a matching payload format, your CF7-to-API integration will stop returning 415 errors and start delivering data reliably.

CF7 to Make (Integromat) Webhook Not Activating: A Complete Troubleshooting Guide

Rahul Sharma — Mon, 05 Oct 2026 05:24:53 +0000

You have built a Contact Form 7 form. You have created a scenario in Make. You have pasted the webhook URL into your WordPress dashboard. And yet, when a user submits the form, nothing happens in Make. The scenario never activates.

Understanding the Data Flow

When a user submits your CF7 form with a Make webhook enabled, here is what should happen:

User submits form → CF7 processes submission → Webhook URL called → Make captures data → Scenario runs

When it breaks, the failure happens at one of the last three stages. Your first diagnostic tool is the Make scenario history. It shows whether a webhook request was received at all, and if so, what data was captured.

If no request appears in Make, the problem is on the WordPress side. For a deeper breakdown of data not reaching your endpoint, see this guide on Contact Form 7 data not reaching the API.

Failure #1: The Webhook URL Was Not Saved in the Database

What you see: Make shows no incoming data. The webhook URL appears to save in the WordPress admin, but after refreshing the page, the field is blank again.

Why it happens: This is a known bug with the CF7 Redirections, Integrations, and Database plugin. The webhook URL is actually being saved to the database, but it is not appearing in the admin interface. This gives the false impression that the save failed.

The fix:

Step 1: Access your WordPress database using phpMyAdmin or a similar tool.

Step 2: Navigate to the wp_postmeta table. Search for the meta key _cf7rid_integromat.

Step 3: Check the meta_value column for that key. If the webhook URL is present, the data was saved correctly.

Step 4: Even if the admin shows a blank field, the webhook should still fire. Submit a test form and check Make for incoming data.

How to verify: If the webhook fires successfully despite the admin showing a blank field, the issue is purely cosmetic. The integration is working.

Failure #2: The CF7 Integration Plugin Is Not Compatible

What you see: No webhook request is sent at all. Make remains empty.

Why it happens: Make's official documentation acknowledges "ongoing issues" with certain CF7 integration plugins. The recommended solution is to use a different plugin that is known to work reliably with Make.

The fix:

Step 1: Check which plugin you are using. Make's documentation specifically recommends the CF7 to Webhook plugin as a reliable alternative.

Step 2: Switch plugins if necessary. Deactivate your current integration plugin and install CF7 to Webhook. Reconfigure the webhook URL in the new plugin's settings.

Step 3: Verify the webhook fires. Submit a test form and confirm that Make receives the data.

Pro tip: The Redirection for Contact Form 7 plugin (from Themeisle) also supports Make integration reliably, but it requires the Marketer plan or higher.

Failure #3: The Scenario Is Not Active or Listening

What you see: The webhook URL is configured correctly, but Make does not capture the first submission.

Why it happens: Make scenarios must be running or listening to receive webhook data. If the scenario is turned off, or if you have not clicked "Run once" to put it in listening mode, the webhook will not be processed.

The fix:

Step 1: Open your Make scenario. Click the "Run once" button to put the scenario in listening mode.

Step 2: While Make is listening, submit your CF7 form with test data.

Step 3: Return to Make. You should see the captured data appear in the webhook module. Click the bubble to inspect the data.

Step 4: Once you have confirmed the data structure, save the scenario and toggle it ON using the switch in the bottom left corner.

Common mistake: Submitting the form before the scenario is active. A WordPress user reported that they had to activate the Make scenario before submitting the form, otherwise it returned an error because the webhook was not ready.

Failure #4: The Request Method or Payload Format Is Wrong

What you see: Make receives a request, but the data is empty or malformed. Or Make returns an error.

Why it happens: Make's webhook endpoint expects data in a specific format. If the request method is not POST, or if the Content-Type header is missing, Make may reject or ignore the payload.

The fix:

Step 1: Verify the request method. In your plugin integration settings, ensure the HTTP method is set to POST.

Step 2: Set the Content-Type header. In the Request Headers section, add:

Content-Type: application/json

Step 3: Check the payload structure. Ensure your field mapping produces valid JSON. A common mistake is sending flat key-value pairs without proper JSON formatting. Your payload should look like:

{
  "name": "[your-name]",
  "email": "[your-email]",
  "message": "[your-message]"
}

For a deeper dive into JSON structure mapping, read this guide on Contact Form 7 JSON mapping.

The Debugging Checklist

Work through this sequence every time a webhook fails to activate:

Step	Action	What It Tells You
1	Check Make scenario history	Was a request received? If not, the problem is in WordPress.
2	Check the database for `_cf7rid_integromat`	Confirms whether the webhook URL was actually saved.
3	Click "Run once" in Make	Puts the scenario in listening mode for test data.
4	Submit a test form while Make is listening	Confirms the connection end-to-end.
5	Verify request method is POST	Make expects POST, not GET.
6	Check Content-Type header	Missing `application/json` can cause parsing failures.
7	Check CF7 email settings	Rules out earlier-stage submission failures.

For a comprehensive breakdown of authentication and error handling across different APIs, see this guide on Contact Form 7 API authentication errors.

Beyond Make: One Form, Multiple Destinations

Once your Make webhook works, you might want to send the same form submission to other tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations and webhooks from a single form submission. You can trigger a Make scenario, create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

The webhook URL may save to the database even if the admin shows it as blank. Check the wp_postmeta table for _cf7rid_integromat to verify.

Make's documentation recommends the CF7 to Webhook plugin. Some CF7 integration plugins have known compatibility issues with Make.

The scenario must be listening before you submit a test form. Click "Run once" in Make, then submit your form.

Make expects POST with JSON. Set the method to POST and add the Content-Type: application/json header.

Make's scenario history is your first diagnostic tool. If no request appears there, the problem is on the WordPress side.

With the correct URL, a compatible plugin, and a scenario that is actively listening, your CF7-to-Make integration will fire reliably on every form submission.

CF7 to Pabbly Connect Webhook Not Triggering: A Complete Troubleshooting Guide

Rahul Sharma — Fri, 02 Oct 2026 12:08:08 +0000

You have built a Contact Form 7 form. You have created a workflow in Pabbly Connect. You have pasted the webhook URL into your WordPress dashboard. And yet, when a user submits the form, nothing happens in Pabbly. The workflow never triggers.

Understanding the Data Flow

When a user submits your CF7 form with a Pabbly webhook enabled, here is what should happen:

User submits form → CF7 processes submission → Webhook URL called → Pabbly captures data → Workflow triggers

When it breaks, the failure happens at one of the last three stages. Your first diagnostic tool is the Pabbly Connect workflow dashboard. It shows whether a webhook request was received at all, and if so, what data was captured.

If no request appears in Pabbly, the problem is on the WordPress side. For a deeper breakdown of data not reaching your endpoint, see this guide on Contact Form 7 data not reaching the API.

Failure #1: The Webhook URL Was Not Saved Correctly

What you see: Pabbly shows "Waiting for Webhook Response" indefinitely. No data is captured.

Why it happens: The webhook URL from Pabbly must be pasted exactly as provided. A single missing character, a trailing space, or an incorrect protocol (HTTP instead of HTTPS) will prevent the request from reaching Pabbly.

The fix:

Step 1: In Pabbly Connect, click on your Webhook trigger step. Copy the generated webhook URL again. It should look similar to:

https://connect.pabbly.com/workflow/webhook-data/xxxxx

Step 2: In your WordPress dashboard, navigate to the integration settings where you pasted the URL. Delete the existing value and paste the copied URL fresh. Do not add any spaces before or after.

Step 3: Save the integration settings. Then submit a test form and check Pabbly for the captured data.

How to verify: After submitting a test form, return to Pabbly Connect. The workflow should show "Response Received" or similar, and the captured data should appear in the trigger step.

Failure #2: The Request Method or Headers Are Misconfigured

What you see: Pabbly receives a request, but the data is empty or malformed. Or Pabbly returns a 400 Bad Request error.

Why it happens: Pabbly's webhook endpoint expects data in a specific format. If the request method is not POST, or if the Content-Type header is missing, Pabbly may reject or ignore the payload.

The fix:

Step 1: Verify the request method. In your plugin integration settings, ensure the HTTP method is set to POST. Pabbly webhooks for CF7 expect POST requests.

Step 2: Add the Content-Type header. In the Request Headers section, add:

Content-Type: application/json

This tells Pabbly that the incoming data is JSON formatted. Without this header, Pabbly may not parse the payload correctly.

Step 3: Check the payload structure. Ensure your field mapping produces valid JSON. A common mistake is sending flat key-value pairs without proper JSON formatting. Your payload should look like:

{
  "name": "[your-name]",
  "email": "[your-email]",
  "message": "[your-message]"
}

For a deeper dive into JSON structure mapping, read this guide on Contact Form 7 JSON mapping.

Failure #3: The Webhook Trigger Is Waiting for Test Data

What you see: Pabbly shows "Waiting for Webhook Response" and never captures data, even though you have submitted multiple test forms.

Why it happens: Pabbly Connect's webhook trigger must receive at least one request to "learn" the data structure before it can process subsequent requests. If the trigger is still in "listening" mode, it may not capture your first submission.

The fix:

Step 1: In Pabbly Connect, click the "Capture Webhook Response" button in your webhook trigger step.

Step 2: While Pabbly is listening, submit your CF7 form with test data. Use realistic values so you can verify field mapping later.

Step 3: Return to Pabbly. You should see the captured response with all field values. Click "Save & Send Test Request" to confirm.

Step 4: Once saved, the webhook is ready. Submit another test form to verify that the trigger fires automatically.

Pro tip: If Pabbly does not capture your first test submission, click "Capture Webhook Response" again and resubmit. Some workflows require a fresh listening state.

Failure #4: The Form Submission Is Failing Before the Webhook Fires

What you see: The form appears to submit, but no webhook request is sent. Pabbly remains empty.

Why it happens: Contact Form 7 may be failing at an earlier stage email notification failure, spam filtering, or validation errors which prevents the webhook from being triggered. The form submission never completes, so the webhook is never called.

The fix:

Step 1: Check for CF7 email errors. A common issue is that CF7's built-in email notification fails, but the form still appears to submit. This can prevent the webhook from firing. Install an SMTP plugin like WP Mail SMTP to ensure emails are sent correctly.

Step 2: Check for spam filtering. If you are using a spam protection plugin (like Akismet or reCAPTCHA), a false positive may block the submission entirely. Temporarily disable spam filtering to test if the webhook fires.

Step 3: Verify the integration is enabled. In your plugin settings, ensure the integration is active and connected to the correct form. If you have multiple forms, confirm that the webhook is configured for the specific form you are testing.

Step 4: Check the plugin logs. If your integration plugin has an API Logs page, review it. If the log is empty, the request was never sent. This confirms the problem is on the WordPress side, not Pabbly.

The Debugging Checklist

Work through this sequence every time a webhook fails to trigger:

Step	Action	What It Tells You
1	Check Pabbly workflow dashboard	Was a request received? If not, the problem is in WordPress.
2	Re-copy and re-paste the webhook URL	Eliminates URL truncation or whitespace issues.
3	Verify request method is POST	Pabbly expects POST, not GET.
4	Check Content-Type header	Missing `application/json` can cause parsing failures.
5	Click "Capture Webhook Response" in Pabbly	Puts the trigger in listening mode for test data.
6	Submit a test form and check Pabbly	Confirms the connection end-to-end.
7	Check CF7 email and spam settings	Rules out earlier-stage submission failures.

For a comprehensive breakdown of authentication and error handling across different APIs, see this guide on Contact Form 7 API authentication errors.

Beyond Pabbly: One Form, Multiple Destinations

Once your Pabbly Connect webhook works, you might want to send the same form submission to other tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations and webhooks from a single form submission. You can trigger a Pabbly workflow, create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

The webhook URL must be exact. Copy and paste it fresh. Even a trailing space can break the connection.

Pabbly expects POST with JSON. Set the method to POST and add the Content-Type: application/json header.

The trigger must "learn" the data first. Click "Capture Webhook Response" and submit a test form to establish the data structure.

CF7 failures prevent webhooks from firing. If the form submission fails (email error, spam block), the webhook is never called.

Pabbly's dashboard is your first diagnostic tool. If no request appears there, the problem is on the WordPress side.

With the correct URL, proper request headers, and a trigger that has captured test data, your CF7-to-Pabbly integration will fire reliably on every form submission.

CF7 Bearer Token vs API Key vs Basic Auth: When to Use Which

Rahul Sharma — Thu, 01 Oct 2026 07:19:21 +0000

You are configuring your Contact Form 7 form to send data to an external API. You open the plugin's authentication settings and see three options: Basic Auth, API Key, and Bearer Token.

Which one do you choose?

The answer depends entirely on what the target API expects. Using the wrong method is one of the most common causes of 401 errors, and it is entirely preventable. This guide explains each method, when to use it, and how to configure it correctly.

The Three Authentication Methods at a Glance

Method	How It Works	Security Level	Best For
Basic Auth	Username and password encoded in Base64	Low	Legacy systems, simple integrations, testing
API Key	A static key passed in a header or query parameter	Medium	Internal APIs, simple token-based auth
Bearer Token	A token (often JWT) passed in the Authorization header	Medium-High	Modern APIs, OAuth 2.0 flows, expiring tokens

Basic Auth: Simple but Limited

Basic Auth is the oldest and simplest authentication method. You send a username and password with every request, encoded in Base64.

How it works:

The credentials are combined as username:password and encoded. The request header looks like this:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

When to use it:

Basic Auth is appropriate for legacy systems that were built before modern authentication standards existed. It is also useful for quick testing and debugging because it requires no token generation or refresh logic.

When to avoid it:

Basic Auth is not inherently secure. The Base64 encoding is not encryption. Anyone who intercepts the request can decode the credentials in seconds. For production integrations, especially those handling sensitive customer data, a more secure method is strongly recommended.

Common use case in CF7 integrations:

Zendesk uses Basic Auth for its API. The username format is email/token, and the password is your API token. This is a case where Basic Auth is the required method, not a choice. For a full walkthrough of Zendesk authentication, see this guide on Contact Form 7 API authentication errors.

API Key: Simple and Static

An API Key is a static token that identifies your application or account. Unlike Bearer tokens, API keys typically do not expire. You generate them once and use them indefinitely.

How it works:

The key can be passed in several ways, depending on the API. Common locations include:

Authorization header: Authorization: YOUR_API_KEY
Custom header: X-API-Key: your-key-here
Query parameter: ?api_key=your-key-here

The plugin supports custom header configuration, so you can place the API key wherever the target API expects it.

When to use it:

API Keys are common for internal APIs, simple integrations, and services where the key identifies the application rather than a specific user. HubSpot private apps, for example, use an access token that functions like an API key.

Security considerations:

API keys provide authorization but not authentication. This means the key grants access to resources, but it does not verify who is making the request. If the key is intercepted, anyone can use it. Store API keys in environment variables or secure configuration, never in version control.

Bearer Token: Modern and Expiring

Bearer Token authentication is the most common method for modern APIs. The token is typically a JSON Web Token (JWT) or an OAuth 2.0 access token.

How it works:

You first obtain a token from the API's authentication endpoint. Then you include that token in the Authorization header:

Authorization: Bearer your-token-here

The word "Bearer" means that whoever holds the token can use it. The token itself is a cryptic string that proves your identity.

When to use it:

Bearer Tokens are the standard for OAuth 2.0 flows. If the API documentation mentions OAuth, access tokens, or token expiration, you need Bearer Token authentication. This is common with enterprise platforms like Salesforce, Google Workspace, and Microsoft 365.

Token expiration:

Unlike API keys, Bearer tokens expire. HubSpot access tokens, for example, expire after 30 minutes (1800 seconds). When a token expires, you need to refresh it using a refresh token.

This is where the plugin's OAuth add-on becomes valuable. The free version does not support automatic token renewal. The PRO add-on handles this automatically, refreshing tokens in the background so your integrations continue running without interruption.

Common use case in CF7 integrations:

HubSpot private apps use Bearer Token authentication. You generate a token in HubSpot's private app settings and paste it into the plugin's Bearer Token field. The Community forum confirms this is the standard approach for HubSpot integrations.

How to Choose: A Decision Framework

Step 1: Check the API documentation.

This is non-negotiable. The API documentation tells you exactly which authentication method it requires. Look for sections labeled "Authentication," "Authorization," or "API Keys."

Step 2: Match the method to the API's requirements.

API Says	Use This Method
"Basic Auth" or "username/password"	Basic Auth
"API Key" or "X-API-Key"	API Key
"Bearer Token" or "OAuth 2.0"	Bearer Token
"JWT" or "access token"	Bearer Token

Step 3: Consider the security requirements.

If the API supports multiple methods, choose the most secure one. Bearer Tokens with expiration are generally more secure than static API keys, which are more secure than Basic Auth.

Step 4: Test with the simplest method first.

If you are debugging a connection issue, start with Basic Auth or API Key. These are easier to configure and have fewer moving parts. Once the connection works, switch to the more secure method if needed.

Configuring Authentication in the Plugin

The plugin provides header input fields where you configure authentication manually.

For Basic Auth:

You need to Base64-encode your credentials before pasting them into the header field. The plugin does not execute PHP code in the header textarea, so you must encode the string externally.

For API Key:

Add a custom header with the API key. The exact header name depends on the API. Some use Authorization, others use X-API-Key, and some use api-key.

For Bearer Token:

Add the Authorization header with the value Bearer your-token-here. If your token expires, you will need to update it manually unless you use the PRO add-on with automatic token refresh.

Common Mistakes to Avoid

Using Bearer Token for an API that expects Basic Auth.

This is the most common 401 error cause. If the API documentation says "Basic Auth" and you send Authorization: Bearer, the request will be rejected.

Forgetting the "Bearer" prefix.

The header value must be Bearer token-here, not just token-here. The prefix tells the API how to interpret the token.

Using an expired token.

Bearer tokens expire. If your integration suddenly stops working after previously working fine, the token may have expired. Check the token's expiration settings in the API's dashboard.

Hardcoding credentials in the header without encoding.

For Basic Auth, the credentials must be Base64 encoded. Sending plain username:password will fail.

For a deeper dive into JSON structure mapping and header configuration, read this guide on Contact Form 7 JSON mapping.

Beyond Authentication: One Form, Multiple Destinations

Once your authentication is configured correctly, you might want to send the same form submission to multiple tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission, without Zapier. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Check the API documentation first. The API tells you which method it requires. Guessing leads to 401 errors.

Basic Auth is for legacy systems and testing. It is simple but not secure. Use it when the API requires it, not by choice.

API Keys are for static integrations. They do not expire, which is convenient but less secure. Store them carefully.

Bearer Tokens are for modern APIs. They expire, which is more secure but requires refresh logic. The PRO add-on handles this automatically.

Match the header format exactly. Bearer, Basic, and custom prefixes are not interchangeable. One wrong character means a failed request.

With the right authentication method, correct header formatting, and an understanding of token lifecycle, your CF7 form will connect to any API reliably.

CF7 Submit Button Stays Disabled After 422 API Response: A Complete Troubleshooting Guide

Rahul Sharma — Wed, 30 Sep 2026 08:08:48 +0000

You have built a Contact Form 7 form. You have connected it to an external API through a connector plugin. When the API returns a successful response, everything works perfectly the form submits, the button resets, and the user sees a confirmation message.

But when the API returns a 422 Unprocessable Entity error, something strange happens. The form appears to hang. The submit button stays greyed out and disabled. The user cannot retry. They cannot correct their input. They are stuck.

This is a frustrating and often misunderstood problem. The good news is that it has a clear cause and several possible fixes. This guide walks through the exact debugging process and verified solutions.

Understanding What Happens on a 422 Response

When a user clicks the CF7 submit button, several things happen in sequence:

CF7 validates the form fields on the client side.
CF7 sends the submission to WordPress via AJAX.
The connector plugin intercepts the submission and sends a request to your external API.
The API returns a response — either success or an error.
CF7 receives the result and updates the UI accordingly.

A 422 response means the API received the request but could not process it. This is common when a required field is missing, a value is in the wrong format, or a validation rule fails on the API side.

The problem occurs at step 5. CF7 expects a clean success or failure signal. When the connector plugin passes through a 422 response without properly translating it into CF7's expected format, CF7 does not know how to reset the form. The submit button remains in its disabled state.

Failure #1: The Plugin Passes Through the Raw 422 Response

What you see: The form hangs. The submit button stays disabled. No error message appears. The browser console may show a failed AJAX request with a 422 status code.

Why it happens: CF7 expects a JSON response with a specific structure. It looks for a status property with a value of mail_sent, mail_failed, validation_failed, or spam. When the connector plugin passes through the raw API response which has a different structure CF7 does not recognize it. The JavaScript that re-enables the submit button never runs.

The fix:

Option A: Check your plugin's error handling settings. Some connector plugins have an option to "Return CF7-compatible response" or "Handle API errors gracefully." Enable this option if available. This tells the plugin to translate API errors into a format CF7 understands.

Option B: Use a custom hook to normalize the response. If your plugin does not have this option, you can add a filter to intercept the API response and reformat it before CF7 processes it. Add this to your theme's functions.php:

add_filter('cf7_to_api_response', 'normalize_422_response', 10, 2);
function normalize_422_response($response, $form_data) {
    if (isset($response['code']) && $response['code'] === 422) {
        return [
            'status' => 'validation_failed',
            'message' => 'The form could not be submitted. Please check your input.',
            'invalid_fields' => []
        ];
    }
    return $response;
}

Note: The exact filter name depends on your connector plugin. Check the plugin documentation for the correct hook.

For a deeper dive into JSON structure mapping and error response handling, read this guide on Contact Form 7 JSON mapping.

Failure #2: JavaScript Error Prevents Button Reset

What you see: The form hangs. The browser console shows a JavaScript error, often related to undefined or cannot read property of null.

Why it happens: When the API returns a 422, the connector plugin may attempt to display error messages for specific fields. If the API response references a field name that does not exist in the CF7 form, the JavaScript fails. This prevents the button reset code from running.

The fix:

Step 1: Open your browser's developer console. Look for red error messages. Note the exact error and the file where it occurs.

Step 2: Check field name alignment. Compare the field names in your API request with the field names in your CF7 form. A common mistake is using your-email in the form but email in the API mapping. When the API returns an error about email, the plugin cannot find a matching field and crashes.

Step 3: Disable error message display temporarily. In your connector plugin settings, turn off the option to display API error messages inline. This prevents the JavaScript from attempting to map errors to fields. The form will still fail, but the button should reset.

Failure #3: The API Returns 422 Without a Recognized Error Format

What you see: The form hangs. The plugin logs show a 422 response, but the response body does not contain field-specific errors.

Why it happens: Some APIs return a generic 422 response without specifying which field caused the problem. The connector plugin may expect a structured error format and fail when it does not receive one.

The fix:

Option A: Configure a fallback error message. In your plugin settings, set a generic error message to display when the API returns an unrecognized error format. This gives the user feedback and allows the form to reset.

Option B: Add a timeout to the AJAX request. If the API does not return a recognizable response, the JavaScript may wait indefinitely. Add a timeout to force the form to reset after a set period. This can be done with a small JavaScript snippet:

document.addEventListener('wpcf7submit', function(event) {
    setTimeout(function() {
        var submitButton = document.querySelector('.wpcf7-submit');
        if (submitButton && submitButton.disabled) {
            submitButton.disabled = false;
            submitButton.removeAttribute('disabled');
        }
    }, 5000);
}, false);

This snippet waits five seconds after a submit event and force-enables the button if it is still disabled. It is a workaround, not a fix, but it prevents users from being permanently stuck.

Failure #4: The Plugin Does Not Reset the Form on API Failure

What you see: The form hangs specifically when the API returns an error. When the API succeeds, the form resets correctly.

Why it happens: Some connector plugins only handle the success path. They do not have logic to reset the form when the API call fails. This is a plugin limitation, not a configuration issue.

The fix:

Option A: Update the plugin. Check if a newer version of your connector plugin addresses this issue. Many plugin developers fix error handling in later releases.

Option B: Report the issue. If the plugin is actively maintained, report the problem with specific details: the API endpoint, the 422 response body, and the observed behavior. Include screenshots of the console error.

Option C: Use a different submission mode. Some plugins offer a "redirect" mode instead of AJAX. In redirect mode, the form submission navigates to a new page. If the API fails, the user sees the error on the new page and can navigate back. This avoids the disabled button problem entirely.

The Debugging Checklist

Work through this sequence every time the submit button stays disabled:

Step	Action	What It Tells You
1	Open browser console	Is there a JavaScript error? Note the exact message.
2	Check the plugin's API Logs	What response did the API return? Is it a 422?
3	Inspect the 422 response body	Does it contain field-specific errors?
4	Compare field names	Do API error field names match CF7 field names?
5	Disable inline error display	Does the button reset when errors are not mapped to fields?
6	Check plugin documentation	Is there a setting for "CF7-compatible response"?
7	Test with a successful API call	Does the button reset correctly on success?

For a comprehensive breakdown of authentication and error handling across different APIs, see this guide on Contact Form 7 API authentication errors.

Preventing the Problem: Best Practices for API Error Handling

The best way to avoid the disabled button problem is to ensure your API integration is configured to handle errors gracefully.

1. Always map API errors to CF7-compatible responses. Your connector plugin should translate 422 responses into CF7's validation_failed status. If it does not, use a filter to do it manually.

2. Use consistent field names. Align your CF7 field names with the API's expected field names. This makes error mapping straightforward and prevents JavaScript crashes.

3. Test error scenarios explicitly. Do not just test the happy path. Submit forms with missing required fields, invalid email formats, and values that violate API rules. Verify that the submit button resets in every case.

4. Set a fallback error message. Even if the API returns an unrecognized error format, the user should see a generic message and be able to retry.

5. Monitor your plugin logs. The API Logs page shows every request and response. Review it regularly to catch error handling issues before users report them.

Beyond Error Handling: One Form, Multiple Destinations

Once your error handling is solid, you might want to send the same form submission to multiple tools: a CRM, an email marketing platform, or a help desk system.

A good connector plugin supports multiple API integrations from a single form submission. You can create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission, without Zapier. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

A 422 response means the API received the request but could not process it. This is a validation error, not a connection error.

CF7 expects a specific response structure. When the connector plugin passes through a raw API error, CF7 does not know how to reset the form.

JavaScript errors can prevent the button from re-enabling. Check the browser console for errors related to field mapping.

A fallback error message and a timeout script can prevent users from being permanently stuck. These are workarounds, not fixes, but they improve the user experience.

The best fix is to configure your plugin to return CF7-compatible responses. Check the plugin settings for an option like "Return CF7-compatible response" or use a filter to normalize the response.

Test error scenarios explicitly. Do not assume the form will behave correctly when the API fails. Verify it.

With proper error handling configuration, consistent field naming, and a fallback mechanism, your CF7 form will reset correctly after a 422 response. Users will see a clear error message and be able to retry, instead of being stuck with a disabled button.