WHMCS Developer Documentation

Mon, 01 Jan 0001 00:00:00 +0000

WHMCS Developer Documentation

This is the repository for the WHMCS Developer Documentation located at http://developers.whmcs.com/

We welcome you to create issues and submit pull requests for any suggestions, corrections and improvements you would like to see.

WHMCS | Contact Support | WHMCS.Community

API

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The WHMCS API allows you to perform operations and actions within WHMCS from external third party and custom code.

Getting Started
Learn about how to get started with the API
Authentication
Learn how authentication works for the WHMCS API
Access Control
Learn how IP and Access Key control works for the WHMCS API
Response Types
Learn about the different response types
Sample Code
See sample code for remotely connecting to the WHMCS API
Internal API
See sample code for using the Local WHMCS API
API Index
A complete listing of all available API commands
API Reference
Visit the API Reference Manual

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The WHMCS API provides an interface to allow you to access and perform actions in WHMCS both from external applications and scripts as well as internal modules and addons.

Choose a category from the left to browse the available API commands.

Learn more about the API

About

Mon, 01 Jan 0001 00:00:00 +0000

About WHMCS

WHMCS is a web host billing & automation platform.

Launched in 2005, today WHMCS is the market leading platform of choice for Web Hosting Providers and Domain Registrars to automate and manage their businesses.

Handling the entire customer lifecycle from initial signup, to provisioning, management and support, WHMCS provides a single centralized platform for web hosting businesses to manage their operations, making every day tasks quicker, easier, and more efficient.

With over 10 years experience and development, a large and active developer community, and our commitment to responding to user requests and leading the way with the latest web hosting technologies and developments, WHMCS is a rich and powerful platform that sets the standard in web host billing automation.

WHMCS
2550 North Loop West
Suite 500
Houston, TX 77092
United States

Email us sales@whmcs.com

AcceptOrder

Mon, 01 Jan 0001 00:00:00 +0000

Accepts a pending order

Request Parameters

Parameter	Type	Description	Required
action	string	“AcceptOrder”	Required
orderid	int	The order id to be accepted	Required
serverid	int	The specific server to assign to products within the order	Optional
serviceusername	string	The specific username to assign to products within the order	Optional
servicepassword	string	The specific password to assign to products within the order	Optional
registrar	string	The specific registrar to assign to domains within the order	Optional
sendregistrar	bool	Send the request to the registrar to register the domain.	Optional
autosetup	bool	Send the request to the product module to activate the service. This can override the product configuration.	Optional
sendemail	bool	Send any automatic emails. This can be Product Welcome, Domain Renewal, Domain Transfer etc.	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AcceptOrder',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'orderid' => '1',
            'registrar' => 'enom',
            'autosetup' => true,
            'sendemail' => true,
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AcceptOrder';
$postData = array(
    'orderid' => '1',
    'registrar' => 'enom',
    'autosetup' => true,
    'sendemail' => true,
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success"
}

Error Responses

Possible error condition responses include:

Order ID not found or Status not Pending
Server and/or registrar response message

Version History

Version	Changelog
1.0	Initial Version

AcceptQuote

Mon, 01 Jan 0001 00:00:00 +0000

Accepts a quote

Request Parameters

Parameter	Type	Description	Required
action	string	“AcceptQuote”	Required
quoteid	int	The quote id to be accepted and converted to an invoice	Required

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
invoiceid	int	The newly created invoice id

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AcceptQuote',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'quoteid' => '1',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AcceptQuote';
$postData = array(
    'quoteid' => '1',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success"
}

Error Responses

Possible error condition responses include:

Quote ID Not Found

Version History

Version	Changelog
1.0	Initial Version

ActivateModule

Mon, 01 Jan 0001 00:00:00 +0000

Activates a given module.

Request Parameters

Parameter	Type	Description	Required
action	string	“ActivateModule”	Required
moduleType	string	The module type to be activated	Required
moduleName	string	The module name to be activated	Required
parameters	array	An array of configuration parameters to set for the given module. Use GetModuleConfigurationParameters to obtain a list of fields for a given module.	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'ActivateModule',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'moduleType' => 'gateway',
            'moduleName' => 'paypal',
            'parameters' => array('email' => 'billing@example.com', 'forcesubscriptions' => true),
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'ActivateModule';
$postData = array(
    'moduleType' => 'gateway',
    'moduleName' => 'paypal',
    'parameters' => array('email' => 'billing@example.com', 'forcesubscriptions' => true),
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success"
}

Error Responses

Possible error condition responses include:

Invalid module type provided. Supported module types include: xxx
Invalid module name provided.
Module activation not supported by module type.
Failed to activate: xxx
An unexpected error occurred: xxx

Version History

Version	Changelog
7.0.0-beta.1	Initial Version

AddAnnouncement

Mon, 01 Jan 0001 00:00:00 +0000

Adds an announcement.

Request Parameters

Parameter	Type	Description	Required
action	string	“AddAnnouncement”	Required
date	\datetime	Date in the format YYYY-MM-DD HH:MM:SS	Required
title	string		Required
announcement	string	Announcement text	Required
published	bool	Pass as true to publish	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
announcementid	int	The id of the new announcement

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddAnnouncement',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'date' => '2016-01-01 15:30:00',
            'title' => 'Sample announcement',
            'announcement' => 'Text goes here...',
            'published' => '1',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddAnnouncement';
$postData = array(
    'date' => '2016-01-01 15:30:00',
    'title' => 'Sample announcement',
    'announcement' => 'Text goes here...',
    'published' => '1',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "announcementid": "1"
}

Version History

Version	Changelog
1.0	Initial Version

AddBannedIp

Mon, 01 Jan 0001 00:00:00 +0000

Adds an IP to the ban list.

Request Parameters

Parameter	Type	Description	Required
action	string	“AddBannedIp”	Required
ip	string		Required
reason	string	Admin only reason	Required
days	int	If passed, expires date is auto calculated	Required
expires	\datetime	YYYY-MM-DD HH:MM:SS	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
banid	int	The id of the new ban entry

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddBannedIp',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'ip' => '1.2.3.4',
            'reason' => 'Abuse',
            'days' => '30',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddBannedIp';
$postData = array(
    'ip' => '1.2.3.4',
    'reason' => 'Abuse',
    'days' => '30',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "banid": "1"
}

Version History

Version	Changelog
1.0	Initial Version

AddBillableItem

Mon, 01 Jan 0001 00:00:00 +0000

Adds a Billable Item

Request Parameters

Parameter	Type	Description	Required
action	string	“AddBillableItem”	Required
clientid	int	The client to add the item to.	Required
description	string	The description of the Billable Item. This will appear on the invoice.	Required
amount	float	The total amount to invoice for.	Required
unit	string	Either ‘hours’ or ‘quantity’.	Required
quantity	float	The number of units the billable items represents. Defaults to 0.	Optional
invoiceaction	string	One of ‘noinvoice’, ‘nextcron’, ‘nextinvoice’, ‘duedate’, or ‘recur’.	Optional
recur	int	When `$invoiceaction=recur`. The frequency of the recurrence.	Optional
recurcycle	string	How often to recur the Billable Item. Days, Weeks, Months or Years.	Optional
recurfor	int	How many times the Billable Item should create an invoice.	Optional
duedate	string	Date the invoice should be due (only required for due date and recur invoice actions). YYYY-mm-dd	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
billableid	int	The ID of the newly created billable item.

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddBillableItem',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'clientid' => '1',
            'description' => 'This is a billable item',
            'amount' => '10.00',
            'invoiceaction' => 'recur',
            'recur' => '1',
            'recurcycle' => 'Months',
            'recurfor' => '12',
            'duedate' => '2021-01-01',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddBillableItem';
$postData = array(
    'clientid' => '1',
    'description' => 'This is a billable item',
    'amount' => '10.00',
    'invoiceaction' => 'recur',
    'recur' => '1',
    'recurcycle' => 'Months',
    'recurfor' => '12',
    'duedate' => '2021-01-01',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "status": "success",
    "billableid": 1
}

Error Responses

Possible error condition responses include:

Client ID not Found
You must provide a description
Invalid Invoice Action
Recurring must have a unit, cycle and limit
Due date is required
Invalid Unit, please specify either ‘hours’ or ‘quantity’
Invalid Date Format - Expected: ‘YYYY-mm-dd’

Version History

Version	Changelog
1.0	Initial Version
8.2	Renamed ‘hours’ parameter to `quantity`. Now Required
8.2	Added `unit` parameter.

AddCancelRequest

Mon, 01 Jan 0001 00:00:00 +0000

Adds a Cancellation Request

Request Parameters

Parameter	Type	Description	Required
action	string	“AddCancelRequest”	Required
serviceid	int	The Service ID to cancel	Required
type	string	The type of cancellation. ‘Immediate’ or ‘End of Billing Period’	Optional
reason	string	The customer reason for cancellation	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
serviceid	int	The id of the service the request was for
userid	int	The id of the user the service belongs to

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddCancelRequest',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'serviceid' => '1',
            'type' => 'Immediate',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddCancelRequest';
$postData = array(
    'serviceid' => '1',
    'type' => 'Immediate',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "serviceid": "1",
    "userid": "1"
}

Error Responses

Possible error condition responses include:

Service ID Not Found
Existing Cancellation Request Exists

Version History

Version	Changelog
1.0	Initial Version

AddClient

Mon, 01 Jan 0001 00:00:00 +0000

Adds a client.

Request Parameters

Parameter	Type	Description	Required
action	string	“AddClient”	Required
owner_user_id	int	The ID of the user that should own the client. Optional. When not provided, a new user will be created.	Optional
firstname	string	First name of the client to be created. Also used for the first name of the user when `owner_user_id` is not specified.	Required
lastname	string	Last name of the client to be created. Also used for the last name of the user when `owner_user_id` is not specified.	Required
companyname	string		Optional
email	string	Email address of the client to be created. Also used for the email of the user when `owner_user_id` is not specified.	Required
address1	string		Required
address2	string		Optional
city	string		Required
state	string		Required
postcode	string		Required
country	string	2 character ISO country code.	Required
phonenumber	string		Required
tax_id	string	The client’s tax ID.	Optional
password2	string	The password for the newly-created user account. Required when `owner_user_id` is not specified.	Optional
securityqid	int	The ID of the security question in `tbladminsecurityquestions`. Required when `owner_user_id` is not specified.	Optional
securityqans	string	The security question answer for a newly-created user.	Optional
currency	int	Currency ID from `tblcurrencies`.	Optional
groupid	int	Client Group ID from `tblclientgroups`.	Optional
customfields	string	Base64 encoded serialized array of custom field values.	Optional
language	string	Default language setting. Also used for the language of the user when `owner_user_id` is not specified. Provide the full name: ‘english’, ‘french’, etc….	Optional
clientip	string	The originating IP address for the request.	Optional
notes	string	Admin only notes.	Optional
marketingoptin	bool	Whether the client should opt-in to receiving marketing emails.	Optional
noemail	bool	Whether to send the client a welcome email. A true value will not send the email.	Optional
skipvalidation	bool	Whether to enforce required fields. A true value will not enforce required fields. This does not apply to `email` and `password2` when `owner_user_id` is not specified.	Optional
~~cardtype~~	~~string~~	~~Credit card type. Provide full name: Visa, Mastercard, American Express, etc….~~	Deprecated
~~cardnum~~	~~string~~	~~Credit card number.~~	Deprecated
~~expdate~~	~~string~~	~~Format: MMYY.~~	Deprecated
~~startdate~~	~~string~~	~~Format: MMYY (if applicable).~~	Deprecated
~~issuenumber~~	~~string~~	~~Credit card issue number (if applicable).~~	Deprecated
~~cvv~~	~~string~~	~~Credit card CVV number (will not be stored).~~	Deprecated

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddClient',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'firstname' => 'John',
            'lastname' => 'Doe',
            'email' => 'john.doe@example.com',
            'address1' => '123 Main Street',
            'city' => 'Anytown',
            'state' => 'State',
            'postcode' => '12345',
            'country' => 'US',
            'phonenumber' => '800-555-1234',
            'password2' => 'password',
            'clientip' => '1.2.3.4',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddClient';
$postData = array(
    'firstname' => 'John',
    'lastname' => 'Doe',
    'email' => 'john.doe@example.com',
    'address1' => '123 Main Street',
    'city' => 'Anytown',
    'state' => 'State',
    'postcode' => '12345',
    'country' => 'US',
    'phonenumber' => '800-555-1234',
    'password2' => 'password',
    'clientip' => '1.2.3.4',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "clientid": "1"
}

Warning Responses

Warning responses are returned when using API functionality that has been removed or marked as deprecated. We suggest following any recommended actions in the warning to ensure future compatibility.

Possible warning messages include:

Credit card related parameters are now deprecated and may be removed in a future version. Use AddPayMethod instead.

Error Responses

Possible error condition responses include:

Invalid Owner User ID
You did not enter your first name
You did not enter your last name
You did not enter your email address
The email address you entered was not valid
You did not enter your email address
You did not enter your address line 1
You did not enter your city
You did not enter your state
You did not enter your postcode
Valid country required
You did not enter your phone number
Invalid telephone phone number
You did not provide required custom field value for
The email address entered is not available for use.
A user already exists with that email address

Version History

Version	Changelog
1.0	Initial Version
7.7	Added `tax_id` parameter.
7.8	Credit card related parameters are now deprecated and may be removed in a future version. Use AddPayMethod instead.
8.0	Added ‘owner_user_id’ parameter.

AddClientNote

Mon, 01 Jan 0001 00:00:00 +0000

Adds a Client Note

Request Parameters

Parameter	Type	Description	Required
action	string	“AddClientNote”	Required
userid	int	The Client ID to apply the note to	Required
notes	string	The note to add	Required
sticky	bool	Should the note be made sticky. Makes the note ‘sticky’ and displays the note throughout the client’s account and on any tickets they submit in the admin area	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
noteid	int	The id of the newly created note

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddClientNote',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'userid' => '1',
            'notes' => 'Note to add',
            'sticky' => true,
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddClientNote';
$postData = array(
    'userid' => '1',
    'notes' => 'Note to add',
    'sticky' => true,
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "noteid": "1"
}

Error Responses

Possible error condition responses include:

Client ID not found
Notes can not be empty

Version History

Version	Changelog
1.0	Initial Version

AddContact

Mon, 01 Jan 0001 00:00:00 +0000

Adds a contact to a client account.

Request Parameters

Parameter	Type	Description	Required
action	string	“AddContact”	Required
clientid	int		Required
firstname	string		Optional
lastname	string		Optional
companyname	string		Optional
email	string	Email address to identify the contact. This should be unique if the contact will be a sub-account	Optional
address1	string		Optional
address2	string		Optional
city	string		Optional
state	string		Optional
postcode	string		Optional
country	string	2 character ISO country code	Optional
phonenumber	string		Optional
tax_id	string		Optional
email_preferences[general]	bool	Should the client receive general emails	Optional
email_preferences[product]	bool	Should the client receive product emails	Optional
email_preferences[domain]	bool	Should the client receive domain emails	Optional
email_preferences[invoice]	bool	Should the client receive invoice emails	Optional
email_preferences[support]	bool	Should the client receive support emails	Optional
email_preferences[affiliate]	bool	Should the client receive affiliate emails	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
contactid	int	The id of the newly added contact.

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddContact',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'clientid' => '1',
            'firstname' => 'Jane',
            'lastname' => 'Doe',
            'email' => 'jane.doe@example.com',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddContact';
$postData = array(
    'clientid' => '1',
    'firstname' => 'Jane',
    'lastname' => 'Doe',
    'email' => 'jane.doe@example.com',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "contactid": "1"
}

Warning Responses

Warning responses are returned when using API functionality that has been removed or marked as deprecated. We suggest following any recommended actions in the warning to ensure future compatibility.

Possible warning messages include:

Sub Accounts are no longer supported. Please use AddUser and CreateClientInvite

Error Responses

Possible error condition responses include:

Client ID Not Found
Duplicate Email Address

Version History

Version	Changelog
1.0	Initial Version
7.7	Added `tax_id` parameter.
7.9	Added `affiliateemails` parameter.
7.10	Added email preferences parameters
8.0	Removed sub-account functionality

AddCredit

Mon, 01 Jan 0001 00:00:00 +0000

Adds credit to a given client.

Request Parameters

Parameter	Type	Description	Required
action	string	“AddCredit”	Required
clientid	int		Required
description	string	Admin only notes for credit justification	Required
amount	float	The amount of credit to add or remove. Must be a positive value.	Required
date	string	The date the credit was added. YYYY-mm-dd format.	Optional
adminid	int	The active admin id to be associated with the credit record. Defaults to current admin.	Optional
type	string	Whether to add or remove credit. One of ‘add’ or ‘remove’	Optional

Response Parameters

Parameter	Type	Description
result	string	The result of the operation: success or error
newbalance	float	The new total credit balance

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddCredit',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'clientid' => '1',
            'description' => 'Adding funds via api',
            'amount' => '12.34',
            'adminid' => '1',
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddCredit';
$postData = array(
    'clientid' => '1',
    'description' => 'Adding funds via api',
    'amount' => '12.34',
    'adminid' => '1',
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "newbalance": "123.45"
}

Error Responses

Possible error condition responses include:

Type can only be add or remove
Client ID Not Found
Admin ID Not Found
No Amount Provided
Amount must be in decimal format: ### or ###.##
Date Format is not Valid

Version History

Version	Changelog
1.0	Initial Version