Configuration

After installing and activating the WHMCS Integration module, you need to configure the connection to your WHMCS instance and define how data flows into Perfex CRM. This page covers API setup, sync preferences, field mapping, and automated scheduling.

Connecting to WHMCS

The module communicates with WHMCS through its official API. You will need valid API credentials before proceeding.

Generating WHMCS API Credentials

1. Log in to your WHMCS Admin Area.
2. Navigate to Setup > Staff Management > Manage API Credentials.
3. Click Generate New API Credential.
4. Enter a description (e.g., "Perfex CRM Integration").
5. Copy the API Identifier and API Secret — you will need both in the next step.

warning

Store your API credentials securely. The API Secret is only displayed once during creation. If lost, you will need to generate new credentials.

Entering Credentials in Perfex CRM

1. In Perfex CRM, navigate to the WHMCS Integration module settings.
2. Enter the following details:
   • WHMCS URL — the full URL to your WHMCS installation (e.g., https://billing.example.com)
   • API Identifier — the identifier generated in the previous step
   • API Secret — the secret key generated in the previous step
3. Click Test Connection to verify that Perfex CRM can successfully communicate with your WHMCS instance.
4. Click Save Settings once the connection test passes.

tip

If the connection test fails, ensure that your Perfex CRM server's IP address is whitelisted in WHMCS under Setup > General Settings > Security > API IP Access Restriction. Also verify that HTTPS is configured and the WHMCS URL is correct.

Sync Settings

The sync settings panel lets you control which data is imported and how it is handled within Perfex CRM.

Data Types

Data Type	Description
Clients	Sync client profiles including name, email, phone, address, and company details
Invoices	Sync invoices with line items, totals, tax, payment status, and due dates
Contacts	Sync additional contacts associated with each WHMCS client account

Toggle each data type on or off depending on your needs. At minimum, Clients should be enabled since invoices and contacts are linked to client records.

Duplicate Handling

When a synced record matches an existing Perfex CRM customer (matched by email address), you can choose how to handle the conflict:

• Skip — do not import the record if a match already exists
• Update — overwrite the existing Perfex CRM record with WHMCS data
• Create New — create a separate record regardless of duplicates

info

The recommended setting is Update, which keeps your Perfex CRM data in sync with WHMCS while avoiding duplicate customer entries.

Field Mapping

The field mapping section lets you define how WHMCS fields correspond to Perfex CRM fields. The module ships with sensible defaults, but you can customize mappings for:

• Standard fields — name, email, phone, address, company, city, state, zip, country
• Custom fields — map WHMCS custom fields to Perfex CRM custom fields

To edit field mappings:

1. Go to WHMCS Integration > Settings > Field Mapping.
2. For each WHMCS field, select the corresponding Perfex CRM field from the dropdown.
3. Click Save Mapping.

Automated Sync Schedule

Rather than running syncs manually, you can configure an automated schedule using a server-side cron job.

Setting Up the Cron Job

Add the following entry to your server's crontab to run the sync at your desired interval:

# Run WHMCS sync every 6 hours
0 */6 * * * php /path/to/perfex/index.php whmcs_integration sync >/dev/null 2>&1

Adjust the cron timing based on how frequently your WHMCS data changes. Common intervals include:

Interval	Cron Expression	Use Case
Every hour	0 * * * *	High-volume billing environments
Every 6 hours	0 */6 * * *	Standard usage (recommended)
Once daily	0 2 * * *	Low-volume environments

warning

Running the sync too frequently on large datasets may increase server load. Monitor your server resources after enabling automated sync and adjust the interval accordingly.

What's Next?

• Usage Guide — learn how to run manual syncs, manage imported clients and invoices, and use bots, templates, and bulk contacts