CF7 to Agile CRM Integration Breaking: A Complete Troubleshooting Guide

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.

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 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 [e-mail] and your API key is abc123, you would encode [e-mail]: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.