The WHMCS API is a powerful tool that allows you to build scripts and integrations with 3rd party products that perform actions and operations within the WHMCS system.

There are over 140 API functions split over 15 different areas of functionality that can be used with WHMCS. These range from actions such as listing clients, invoices and tickets, to creating orders, generating bills, opening tickets and provisioning and managing provisioned services.

In this blog post I will cover some of the basics that are important to know when embarking on a project involving our API.

The WHMCS API can be accessed in one of two ways:

• Internal API - Recommended for modules and code that are local to the WHMCS installation, the API can be accessed using the Local API methods that avoid the overhead of opening a TCP connection. See https://developers.whmcs.com/api/internal-api/ for sample code.
• External API - Must be employed for code and integrations that are external from the WHMCS installation. Works by sending requests to the API endpoint located at `/includes/api.php` within the WHMCS root installation directory.

Use of the WHMCS External API always requires Authentication. In some cases, the Internal API may also require authentication if the call relates to actions specific to an admin user.

We recommend creating API Authentication Credentials as best practice for use when building API integrations. API Authentication Credentials can be setup and managed in Setup > Staff Management > Manage API Credentials and allow you to setup individual client identifiers and secrets for each API integration you create. Combined with API Roles, you can also limit the actions that a given API Authentication Credential can access and use allowing for secure and robust management of API access.

For more information, please refer to https://docs.whmcs.com/API_Authentication_Credentials

Access to the External API is IP restricted by default.

To configure the IP addresses that are allowed to access and use the WHMCS API, login to your WHMCS admin area and navigate to Setup > General Settings > Security. From there you can add, remove and manage the allowed IPs. Each allowed IP you add also allows you to add a note useful for notating who/what/why the IP has been authorized for access.

For cases where IP restriction is not feasible, an access key method is available instead. Please see https://developers.whmcs.com/api/access-control/ for further information.

The External API supports 3 response types: JSON (recommended), XML and NVP (name/value pairs).

Some API functions, specifically those that return complex data structures such as lists, do not support the NVP response type.

You define the response type you wish to receive by including a responsetype parameter in each API request you make. For example, responsetype=json. Note that this parameter is not supported in Internal API calls as the response you receive will be an array object.

Now we've covered the basics above, we're ready to go ahead and make our first API call.

For our first call, let's try listing clients. We can do that using the following code snippet. Copy and paste the below code into your favourite editor, and then edit lines 7, 8 and 9 inserting the URL to your WHMCS installation (the root directory/client area url), and your API Authentication Credentials (see the Authentication section above).

Then save the file with a name, upload it to your web server and invoke the script either via the CLI or a web browser to run it.

<?php 
/** 
* Getting started with the WHMCS API Tutorial 
*/ 
 
// Set your WHMCS URL and API Authentication Credentials 
$whmcsUrl = "https://www.example.com/path/to/whmcs/"; 
$apiIdentifier = "your_api_credential_identifier"; 
$apiSecret = "your_api_credential_secret"; 
 
// Build post values 
$postfields = array( 
'identifier' => $apiIdentifier, 
'secret' => $apiSecret, 
'action' => 'GetClients', 
'responsetype' => 'json', 
); 
 
// Call the API 
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, $whmcsUrl . 'includes/api.php'); 
curl_setopt($ch, CURLOPT_POST, 1); 
curl_setopt($ch, CURLOPT_TIMEOUT, 30); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 1); 
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2); 
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields)); 
$response = curl_exec($ch); 
if (curl_error($ch)) { 
die('Unable to connect: ' . curl_errno($ch) . ' - ' . curl_error($ch)); 
} 
curl_close($ch); 
 
// Decode response 
$jsonData = json_decode($response, true); 
 
// Dump array structure for inspection 
var_dump($jsonData); 

Now you've got your first API call working, you can try experimenting with the other API functions that are available in the WHMCS API.

For a complete listing of available API functions, please refer to https://developers.whmcs.com/api/api-index/

I hope you found this introduction useful and if you have any problems getting started with the API, I welcome you to post in the comments below or get in touch with our friendly technical support team.

Thanks for reading!