ClientFence API
The ClientFence module holds the features ClientFence adds: the admin dashboard cards, system health checks, update checks, sign-in and network security, database backups and maintenance, imports from other billing systems, chat alerts, the store gate, the setup wizard and the notification bell. Every staff member may call the module; each call checks its own permission, and many are for Super Administrators only. See Quick setup and System health.
Admin calls need no module access: every staff account may make them, subject to each call’s own permission below. See Authentication.
Admin calls
Section titled “Admin calls”dashboard_get
Section titled “dashboard_get”POST /api/admin/clientfence/dashboard_get
Returns the small counters of the admin dashboard. Each part the caller may not see is null.
Permission: None for the call. domains_expiring needs View orders (order.view), invoices_overdue needs View invoices (invoice.view), cron_last and email_queue need Manage System Settings (system.manage_settings).
No parameters.
Returns: An object: domains_expiring (domains whose active order expires within 30 days), invoices_overdue (unpaid invoices past their due date), cron_last (the last cron run) and email_queue (emails waiting to be sent), each null when the caller lacks its permission.
dashboard_today
Section titled “dashboard_today”POST /api/admin/clientfence/dashboard_today
Returns today’s figures hour by hour for one dashboard chart.
Permission: View statistics (stats.view). The clients, orders, invoices and tickets counts also need the view permission of that module.
| Parameter | Type | Description |
|---|---|---|
metric |
string | income (default: paid invoices, refunds taken off), or the number of new clients, orders, invoices or tickets. |
Returns: A list of [time, value] pairs, one per hour from midnight to the current hour, where time is a Unix timestamp in milliseconds. Income is in the default currency.
Errors:
- Unknown metric.
dashboard_billing
Section titled “dashboard_billing”POST /api/admin/clientfence/dashboard_billing
Returns the income totals of the dashboard’s billing card.
Permission: View statistics (stats.view) and View invoices (invoice.view)
No parameters.
Returns: An object: today, this_month, this_year and total.
dashboard_totals
Section titled “dashboard_totals”POST /api/admin/clientfence/dashboard_totals
Returns the totals of the dashboard’s top row.
Permission: View statistics (stats.view)
No parameters.
Returns: An object: active_clients, pending_orders, unpaid (what the unpaid invoices ask for, tax included, in the default currency), mrr (monthly recurring revenue in the default currency, before tax) and mrr_orders (the orders counted in it).
dashboard_latest_orders
Section titled “dashboard_latest_orders”POST /api/admin/clientfence/dashboard_latest_orders
Returns the 5 newest orders by order date. Add-on orders are left out when the order settings hide them.
Permission: View orders (order.view)
No parameters.
Returns: A list of up to 5 orders, with the same fields as the rows of order get_list.
dashboard_latest_invoices
Section titled “dashboard_latest_invoices”POST /api/admin/clientfence/dashboard_latest_invoices
Returns the 5 newest invoices by invoice date.
Permission: View invoices (invoice.view)
No parameters.
Returns: A list of up to 5 invoices, with the same fields as the rows of invoice get_list.
dashboard_clients
Section titled “dashboard_clients”POST /api/admin/clientfence/dashboard_clients
Returns the dashboard’s client activity card: active clients and who was seen lately.
Permission: View Client Details (client.view). A client counts as seen when they signed in (needs the client module’s View login history) or did something logged as themselves (needs View activity log, activity.view).
No parameters.
Returns: An object: active (clients with the Active status), active_hour (clients seen in the last hour, null when neither source is allowed) and recent (up to 6 clients seen in the last 30 days: id, name, company, ip, at).
health_get
Section titled “health_get”POST /api/admin/clientfence/health_get
Returns the last system health report, as on the dashboard’s health card.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: null before the first run, otherwise the report: ran_at, started_at, version, checks (each with group, id, title, state (ok, warn or bad), detail, url, params, fails), counts (ok, warn, bad, total), passed (a percentage) and rating (attention, good or excellent).
The cron runs the checks every hour. See System health.
update_check_get
Section titled “update_check_get”POST /api/admin/clientfence/update_check_get
Returns the update check settings and the result of the last check.
Permission: View System Information (system.view)
No parameters.
Returns: An object: enabled, channel (stable or beta), checked_at (or null), error (the last check’s error, or null) and feed (the release feed address).
See Update ClientFence.
update_changes
Section titled “update_changes”POST /api/admin/clientfence/update_changes
Lists the ClientFence files changed on this server, which an update would replace.
Permission: Update ClientFence (system.system_update)
No parameters.
Returns: An object: checked (false when the installed version has no file list) and files (the changed files).
update_channel_save
Section titled “update_channel_save”POST /api/admin/clientfence/update_channel_save
Chooses the release channel and checks the feed again.
Permission: Update ClientFence (system.system_update)
| Parameter | Type | Description |
|---|---|---|
channel |
string, required | stable or beta. Beta is opt-in and not meant for production. |
Returns: true.
Errors:
- Unknown release channel.
update_check_save
Section titled “update_check_save”POST /api/admin/clientfence/update_check_save
Turns the daily check for new versions on or off.
Permission: Update ClientFence (system.system_update)
| Parameter | Type | Description |
|---|---|---|
enabled |
boolean | 1 to check, 0 or left out to stop checking. |
Returns: true.
health_page
Section titled “health_page”POST /api/admin/clientfence/health_page
Returns what the System Health tab shows: the last report and the check groups.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: An object: report (as health_get, or null) and groups (core, security, integrity, services and server, with their titles).
health_run
Section titled “health_run”POST /api/admin/clientfence/health_run
Runs the system health checks now and saves the report. Blocked-script warnings the last run already showed are cleared first.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: The new report, as health_get.
dashboard_layout_get
Section titled “dashboard_layout_get”POST /api/admin/clientfence/dashboard_layout_get
Returns the caller’s dashboard card order: the order a Super Administrator saved, or the default.
No parameters.
Returns: An object: cols (two lists of card ids), can_arrange (whether the caller is a Super Administrator) and saved (whether the caller saved an order of their own).
dashboard_layout_save
Section titled “dashboard_layout_save”POST /api/admin/clientfence/dashboard_layout_save
Saves the caller’s own dashboard card order.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
layout |
string, required | JSON of two lists of card ids, one per column. The cards are income, billing, paypal, orders, activity, products, health, invoices and clients. |
Returns: true.
Errors:
- Only Super Administrators can arrange the dashboard.
- The card order could not be read.
Example
Request parameters:
{ "layout": "[[\"income\",\"billing\",\"paypal\",\"orders\",\"activity\"],[\"products\",\"health\",\"invoices\",\"clients\"]]"}result:
truedashboard_layout_reset
Section titled “dashboard_layout_reset”POST /api/admin/clientfence/dashboard_layout_reset
Removes the caller’s saved card order, so the default order shows again.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: true.
Errors:
- Only Super Administrators can arrange the dashboard.
backup_access
Section titled “backup_access”POST /api/admin/clientfence/backup_access
Tells whether the caller may manage database backups and the other Super Administrator tools.
No parameters.
Returns: true for a Super Administrator, otherwise false.
db_tables
Section titled “db_tables”POST /api/admin/clientfence/db_tables
Lists the database tables with their size, as on the Database tab.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: A list of tables: name, rows, size and free (unused space, in bytes).
Errors:
- Only Super Administrators can manage the database.
See Database.
db_optimize
Section titled “db_optimize”POST /api/admin/clientfence/db_optimize
Optimizes every table with unused space, one at a time.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: The number of tables optimized.
Errors:
- Only Super Administrators can manage the database.
- These tables could not be optimized:
db_cleanup
Section titled “db_cleanup”POST /api/admin/clientfence/db_cleanup
Runs the cron’s clean-ups now, with the retention settings as they are saved.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: The number of ticket files removed.
Errors:
- Only Super Administrators can manage the database.
signin_security_get
Section titled “signin_security_get”POST /api/admin/clientfence/signin_security_get
Returns the sign-in security settings, every country, and the caller’s address and country.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: pin (off, staff, clients or both), countries_on, countries, ips_on, ips, staff_reset, pin_when (every or new), history, twofactor (which clients must use two-factor sign-in: off, all or groups), twofactor_groups (client group ids), passkeys (off, clients, staff or both), and all_countries, ip (the caller’s address), ip_country, ip_listed (whether it is on the staff address list) and geoip_ready (whether countries can be looked up).
Errors:
- Only Super Administrators can change security settings.
See Sign-in security.
signin_security_save
Section titled “signin_security_save”POST /api/admin/clientfence/signin_security_save
Saves the sign-in security settings. Turning the staff email PIN on takes two calls: the first sends a PIN to the caller, the second confirms it.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
pin |
string | Email PIN at sign-in: off, staff, clients or both. Left out means off. |
pin_when |
string | every sign-in or only from a new device. Left out keeps it. |
countries_on |
boolean | Allow staff sign-in only from the listed countries. Leave out both countries_on and countries to keep the country rule as it is; when only countries is sent, a missing countries_on means off. |
countries |
array | Country codes, such as US. |
ips_on |
boolean | Allow staff sign-in only from the listed addresses. Left out keeps the address rule and list as they are. |
ips |
string | The allowed IP addresses, separated by spaces, commas or new lines (or a list). Only read with ips_on. |
staff_reset |
boolean | Whether staff may reset a forgotten password by email. Left out keeps it. |
history |
boolean | Keep a sign-in history. Left out keeps it. |
twofactor |
string | Which clients must use two-factor sign-in: off, all or groups. Left out keeps it. |
twofactor_groups |
array | Client group ids when twofactor is groups. |
passkeys |
string | Who may sign in with a passkey: off, clients, staff or both. Passkeys need the portal on HTTPS. Left out keeps it. |
confirm_pin |
string | The PIN emailed by the first call, to finish turning the staff PIN on. |
Returns: {"saved": true}, or {"saved": false, "confirm": true, "email": "..."} (the caller’s address, partly masked) when a PIN was sent and the same call must be repeated with confirm_pin.
Errors:
- Only Super Administrators can change security settings.
- The PIN is not correct.
- Too many wrong PINs. Save again for a new one.
- Choose at least one country staff may sign in from.
- Add at least one IP address staff may sign in from.
- Not an IP address:
- Unknown country code:
Settings that would lock the caller out are refused with a message that says why: an address list without the caller’s own address, or a country list without the caller’s country (unless the caller’s address is on the staff address list). Turning the staff PIN on happens in the caller’s session, so both calls must use the same session.
security_settings_get
Section titled “security_settings_get”POST /api/admin/clientfence/security_settings_get
Returns the proxy, access, session, network and API log settings of the Proxies and access page.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: proxies_on, proxies, headers (aws_elb, x_forwarded, forwarded), cloudflare, cloudflare_listed, remote_addr, client_ip, whitelist, api_ips, fingerprint, networks (mode off, hold or block, always, never, listed) and api_log (sources, days).
Errors:
- Only Super Administrators can change security settings.
See Proxies and access.
security_settings_save
Section titled “security_settings_save”POST /api/admin/clientfence/security_settings_save
Saves one section of the security settings.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
section |
string, required | proxies (with proxies_on, proxies, headers), access (with whitelist, api_ips), sessions (with fingerprint), networks (with mode, always, never) or apilog (with api_key, webhook, staff, client and days, 1 to 3650). |
Returns: true.
Errors:
- Only Super Administrators can change security settings.
- Unknown settings section.
Each section saves only its own settings.
fraud_check_get
Section titled “fraud_check_get”POST /api/admin/clientfence/fraud_check_get
Returns the order fraud check settings. The API key itself is never returned.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: has_key (whether a key is saved), provider (off, maxmind or fraudlabs), account_id, limit (the risk score above which an order is held) and skip_active (skip clients with an active order, default true).
Errors:
- Only Super Administrators can change the fraud check.
fraud_check_save
Section titled “fraud_check_save”POST /api/admin/clientfence/fraud_check_save
Saves the order fraud check settings, or tests the typed details with one sample request (nothing is saved then).
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
provider |
string | off (default), maxmind or fraudlabs. |
account_id |
string | The MaxMind account ID, a number. Required for maxmind. |
key |
string | The licence key or API key. Empty keeps the saved key of the same service. |
limit |
number, required | The risk score above which an order is held, above 0 and below 100, such as 20. |
skip_active |
boolean | Skip the check for clients who already have an active order. |
do |
string | test to test the details without saving. |
Returns: true, or with do=test an object {tested: text} with the service’s answer (the score and the credit left).
Errors:
- Only Super Administrators can change the fraud check.
- Choose the fraud check service.
- Enter a score limit above 0 and below 100, such as 20.
- Enter the MaxMind account ID (a number).
- The licence key or API key is not valid.
- Enter the licence key or API key.
- Choose the fraud check service to test.
- The service did not answer:
The settings are saved in the config file. See Orders.
whmcs_import_get
Section titled “whmcs_import_get”POST /api/admin/clientfence/whmcs_import_get
Returns the state of the Import page: saved details, the plan, the run and its warnings.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: settings (no passwords or keys, with has_* flags instead), plan, target (fresh and counts: whether this install is still empty), run, archive, warnings, and upmind, blesta, clientexec, fossbilling and paymenter (which source is chosen).
Errors:
- Only Super Administrators can import from WHMCS.
Despite the whmcs_ names, the import calls serve every source system. See Import from WHMCS.
whmcs_import_save
Section titled “whmcs_import_save”POST /api/admin/clientfence/whmcs_import_save
Saves and tests the WHMCS database details.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
host |
string, required | The database host. |
port |
integer | 1 to 65535. Default 3306. |
database |
string, required | The database name. |
username |
string, required | The database user. |
password |
string | The database password. Empty keeps the saved one; required the first time. |
encryption_key |
string | WHMCS’s cc_encryption_hash, to read saved passwords and keys. |
attachments_dir |
string | WHMCS’s attachments folder on this server (absolute path). |
paypal_agreements |
boolean | Import PayPal billing agreements. |
Returns: An object: version (the WHMCS version found).
Errors:
- Only Super Administrators can import from WHMCS.
- Enter a port from 1 to 65535.
- Enter the WHMCS database host, name, username and password.
whmcs_import_upmind_save
Section titled “whmcs_import_upmind_save”POST /api/admin/clientfence/whmcs_import_upmind_save
Chooses Upmind as the source and saves and tests its API token.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
upmind_token |
string | The Upmind API token. Empty keeps the saved one. |
Returns: An object: clients (the number of clients found).
Errors:
- Only Super Administrators can import from WHMCS.
See Import from Upmind.
whmcs_import_upmind_fetch
Section titled “whmcs_import_upmind_fetch”POST /api/admin/clientfence/whmcs_import_upmind_fetch
Reads Upmind for about 8 seconds and returns how far it got. Call it again until it finishes.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
restart |
integer | 1 to read it again from the start. |
Returns: The read state: started_at, finished_at, sorted, step, offset and steps (per step: label, done, finished).
Errors:
- Only Super Administrators can import from WHMCS.
- The import has started: Upmind can no longer be read again.
whmcs_import_blesta_save
Section titled “whmcs_import_blesta_save”POST /api/admin/clientfence/whmcs_import_blesta_save
Chooses Blesta as the source and saves and tests its database details.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
host |
string, required | The database host. |
port |
integer | Default 3306. |
database |
string, required | The database name. |
username |
string, required | The database user. |
password |
string | Empty keeps the saved one; required the first time. |
blesta_key |
string, required | Blesta’s system key, as its config/blesta.php shows it. |
Returns: An object: version and clients.
Errors:
- Only Super Administrators can import from WHMCS.
- Enter Blesta’s system key as config/blesta.php shows it.
- This database has no Blesta tables. Check the database name.
See Import from Blesta.
whmcs_import_blesta_fetch
Section titled “whmcs_import_blesta_fetch”POST /api/admin/clientfence/whmcs_import_blesta_fetch
Reads Blesta for about 8 seconds and returns how far it got. Call it again until it finishes.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
restart |
integer | 1 to read it again from the start. |
Returns: The read state, as whmcs_import_upmind_fetch.
Errors:
- Only Super Administrators can import from WHMCS.
- The import has started: Blesta can no longer be read again.
whmcs_import_clientexec_save
Section titled “whmcs_import_clientexec_save”POST /api/admin/clientfence/whmcs_import_clientexec_save
Chooses ClientExec as the source and saves and tests its database details.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
host |
string, required | The database host. |
port |
integer | Default 3306. |
database |
string, required | The database name. |
username |
string, required | The database user. |
password |
string | Empty keeps the saved one; required the first time. |
attachments_dir |
string | The attachments folder on this server (absolute path). |
Returns: An object: version and clients.
Errors:
- Only Super Administrators can import from WHMCS.
- This database has no ClientExec tables. Check the database name.
whmcs_import_clientexec_fetch
Section titled “whmcs_import_clientexec_fetch”POST /api/admin/clientfence/whmcs_import_clientexec_fetch
Reads ClientExec for about 8 seconds and returns how far it got. Call it again until it finishes.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
restart |
integer | 1 to read it again from the start. |
Returns: The read state, as whmcs_import_upmind_fetch.
Errors:
- Only Super Administrators can import from WHMCS.
- Save the ClientExec database details first.
- The import has started: ClientExec can no longer be read again.
whmcs_import_fossbilling_save
Section titled “whmcs_import_fossbilling_save”POST /api/admin/clientfence/whmcs_import_fossbilling_save
Chooses FOSSBilling as the source and saves and tests its database details.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
host |
string, required | The database host. |
port |
integer | Default 3306. |
database |
string, required | The database name. |
username |
string, required | The database user. |
password |
string | Empty keeps the saved one; required the first time. |
Returns: An object: version and clients.
Errors:
- Only Super Administrators can import from WHMCS.
- This database has no FOSSBilling tables. Check the database name.
whmcs_import_fossbilling_fetch
Section titled “whmcs_import_fossbilling_fetch”POST /api/admin/clientfence/whmcs_import_fossbilling_fetch
Reads FOSSBilling for about 8 seconds and returns how far it got. Call it again until it finishes.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
restart |
integer | 1 to read it again from the start. |
Returns: The read state, as whmcs_import_upmind_fetch.
Errors:
- Only Super Administrators can import from WHMCS.
- Save the FOSSBilling database details first.
- The import has started: FOSSBilling can no longer be read again.
whmcs_import_paymenter_save
Section titled “whmcs_import_paymenter_save”POST /api/admin/clientfence/whmcs_import_paymenter_save
Chooses Paymenter (1.4 or newer) as the source and saves and tests its database details.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
host |
string, required | The database host. |
port |
integer | Default 3306. |
database |
string, required | The database name. |
username |
string, required | The database user. |
password |
string | Empty keeps the saved one; required the first time. |
Returns: An object: version and clients.
Errors:
- Only Super Administrators can import from WHMCS.
- This database has no Paymenter tables. Check the database name.
- The import reads Paymenter 1.4 or newer. Update Paymenter first, then try again.
whmcs_import_paymenter_fetch
Section titled “whmcs_import_paymenter_fetch”POST /api/admin/clientfence/whmcs_import_paymenter_fetch
Reads Paymenter for about 8 seconds and returns how far it got. Call it again until it finishes.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
restart |
integer | 1 to read it again from the start. |
Returns: The read state, as whmcs_import_upmind_fetch.
Errors:
- Only Super Administrators can import from WHMCS.
- Save the Paymenter database details first.
- The import has started: Paymenter can no longer be read again.
whmcs_import_plan
Section titled “whmcs_import_plan”POST /api/admin/clientfence/whmcs_import_plan
Reads the source and makes the import plan: what will be imported and what needs attention first.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: The plan: version, major, supported, areas, money, credit_clients, modules, gateways, server_modules, warnings, preflight and made_at.
Errors:
- Only Super Administrators can import from WHMCS.
whmcs_import_apply
Section titled “whmcs_import_apply”POST /api/admin/clientfence/whmcs_import_apply
Imports for about 8 seconds and returns how far it got. Call it again until finished_at is set.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: The run state: started_at, updated_at, finished_at, archive, version, step, steps (per step: label, total, done, after, finished), warnings and error.
Errors:
- Only Super Administrators can import from WHMCS.
The import runs only into a fresh install, and only one run at a time.
whmcs_import_verify
Section titled “whmcs_import_verify”POST /api/admin/clientfence/whmcs_import_verify
Compares what the source holds with what was imported.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: A list of rows: step, label, whmcs (the count in the source) and imported.
Errors:
- Only Super Administrators can import from WHMCS.
- Nothing was imported yet.
backup_get
Section titled “backup_get”POST /api/admin/clientfence/backup_get
Returns the database backup settings and the status of the last backups.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: the ftp, email and local settings (no passwords), status, max_email_mb (20), the local folder and its files, and cloud (the cloud copy settings).
Errors:
- Only Super Administrators can manage database backups.
See Backups.
backup_ftp_save
Section titled “backup_ftp_save”POST /api/admin/clientfence/backup_ftp_save
Tests FTP or SFTP backup details, or saves them and turns FTP backups on.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
host |
string, required | The server name. |
port |
integer | The port. |
username |
string, required | The user name. |
password |
string | Empty keeps the saved one. |
path |
string | The folder on the server. |
secure |
boolean | Use a secure connection. |
passive |
boolean | Use passive mode. |
do |
string | activate to save and turn FTP backups on. Anything else only tests. |
Returns: true when activated; {"tested": true} after a test.
Errors:
- Only Super Administrators can manage database backups.
backup_email_save
Section titled “backup_email_save”POST /api/admin/clientfence/backup_email_save
Saves the address that receives database backups by email.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
address |
string, required | The email address. |
do |
string | activate to also turn email backups on. |
Returns: true.
Errors:
- Only Super Administrators can manage database backups.
Backups larger than 20 MB are not sent by email.
backup_local_save
Section titled “backup_local_save”POST /api/admin/clientfence/backup_local_save
Turns local backups on and sets how many days of them to keep.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
days |
integer, required | 1 to 365. |
Returns: true.
Errors:
- Only Super Administrators can manage database backups.
backup_cloud_save
Section titled “backup_cloud_save”POST /api/admin/clientfence/backup_cloud_save
Tests cloud backup details, saves them, or saves them and turns cloud copies on.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
provider |
string, required | s3 (any S3-compatible storage), bunny, gdrive or onedrive. |
endpoint |
string | The storage endpoint. |
region |
string | The region. |
bucket |
string | The bucket or storage zone. |
key |
string | The access key. Empty keeps the saved one. |
secret |
string | The secret key. Empty keeps the saved one. |
folder |
string | The folder for the copies. |
db_every |
string | hourly, daily or weekly. |
db_keep |
integer | Database copies to keep, 1 to 1000. |
files_every |
string | daily, weekly or never. |
files_keep |
integer | Files copies to keep, 1 to 1000. |
encrypt |
boolean | Encrypt the copies. |
passphrase |
string | The encryption passphrase, at least 8 characters. |
do |
string | test sends a test file with the typed details and saves nothing, save saves them, and anything else (or left out) tests, saves and turns the copies on. |
Returns: {"tested": true} after a test, otherwise true.
Errors:
- Only Super Administrators can manage database backups.
Google Drive and OneDrive must first be connected in the browser on the Backups page.
backup_deactivate
Section titled “backup_deactivate”POST /api/admin/clientfence/backup_deactivate
Turns one backup method off. Files already kept stay.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
method |
string, required | ftp, email, local or cloud. |
Returns: true.
Errors:
- Only Super Administrators can manage database backups.
backup_run
Section titled “backup_run”POST /api/admin/clientfence/backup_run
Makes a backup now. The cron also makes one every day.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
targets |
array | Where the backup goes: any of local, ftp, email, cloud_db and cloud_files. Left out: the database, by every method that is on. |
Returns: Without targets: the run’s status. With targets: an object backup (the run’s status, or null) and cloud (the cloud copies started: db, files).
Errors:
- Only Super Administrators can manage database backups.
- Choose where the backup goes.
- Unknown backup method.
- Cloud copies are off: turn them on first.
Cloud copies start after the answer is sent; a files copy can take minutes.
chat_alerts_get
Section titled “chat_alerts_get”POST /api/admin/clientfence/chat_alerts_get
Lists the chat alert destinations and the alert kinds.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: destinations (each with id, name, type, enabled, hint (the last 4 characters of the webhook address or token, never the whole secret), chat_id, kinds, error, error_at) and kinds (every alert kind).
Errors:
- Only Super Administrators can manage chat alerts.
See Chat alerts.
chat_alert_save
Section titled “chat_alert_save”POST /api/admin/clientfence/chat_alert_save
Adds a chat alert destination, or changes one.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
id |
integer | The destination to change. Left out: a new one. |
name |
string, required | Up to 100 characters. |
type |
string, required | slack, discord or telegram. |
enabled |
boolean | Send alerts to it. |
webhook_url |
string | The Slack or Discord webhook address. Empty keeps the saved one. |
bot_token |
string | The Telegram bot token. Empty keeps the saved one. |
chat_id |
string | The Telegram chat id. |
kinds |
array | The alert kinds to send. |
Returns: The destination’s id.
Errors:
- Only Super Administrators can manage chat alerts.
chat_alert_delete
Section titled “chat_alert_delete”POST /api/admin/clientfence/chat_alert_delete
Deletes a chat alert destination.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The destination id. |
Returns: true.
Errors:
- Only Super Administrators can manage chat alerts.
- This chat destination no longer exists.
chat_alert_test
Section titled “chat_alert_test”POST /api/admin/clientfence/chat_alert_test
Sends a test message to a chat alert destination now.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The destination id. |
Returns: true when the message was sent.
Errors:
- Only Super Administrators can manage chat alerts.
- The test message was not sent: <the service’s reason>
store_update
Section titled “store_update”POST /api/admin/clientfence/store_update
Saves who may see and use the store, and its title, subtitle and opening billing cycle.
Permission: The order module’s Manage settings (order.manage_settings)
| Parameter | Type | Description |
|---|---|---|
store_mode |
string, required | closed, testers (one client group only) or public. |
store_testers_group |
integer | The client group that may order. Required for testers. |
store_title |
string | One line, up to 80 characters. |
store_subtitle |
string | One line, up to 200 characters. |
store_cycle |
string | The billing cycle the store opens on, such as 1M or 1Y. Empty: monthly, or the first cycle offered. |
Returns: true.
Errors:
- Choose who can see the store.
- The client group that can order was not found.
- Choose the client group that can order.
- The store title can have 80 characters and the subtitle 200.
- The store title and subtitle are one line of plain text each.
- Choose a billing cycle for the store.
See Who can order.
Example
Request parameters:
{ "store_mode": "testers", "store_testers_group": 2, "store_title": "Example Hosting store"}result:
truestore_preview_update
Section titled “store_preview_update”POST /api/admin/clientfence/store_preview_update
Makes a new store preview link or turns the preview off. Either way every open preview session ends.
Permission: The order module’s Manage settings (order.manage_settings)
| Parameter | Type | Description |
|---|---|---|
action |
string, required | new or off. |
Returns: The new preview token (32 hex characters), or an empty string when turned off.
Errors:
- Choose whether to make a new preview link or turn it off.
setup_allowed
Section titled “setup_allowed”POST /api/admin/clientfence/setup_allowed
Tells whether the caller may run the setup wizard.
No parameters.
Returns: true for a Super Administrator, otherwise false.
setup_company
Section titled “setup_company”POST /api/admin/clientfence/setup_company
Setup wizard: saves the company name, email, phone and address.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
company_name |
string, required | The business name. |
company_email |
string | The business email address. |
company_tel |
string | The phone number. |
company_address_1 |
string | Address line 1. |
company_address_2 |
string | Address line 2. |
company_address_3 |
string | Address line 3. |
Returns: true when saved.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
- Enter your business name.
- Enter a valid business email address.
See Quick setup.
Example
Request parameters:
{ "company_name": "Example Hosting", "company_email": "billing@example.com"}result:
truesetup_brand_asset
Section titled “setup_brand_asset”POST /api/admin/clientfence/setup_brand_asset
Setup wizard: uploads a logo or the site icon. Send it as a multipart form.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
kind |
string, required | logo, logo_dark, logo_email or icon. |
file |
file, required | The image, up to 2 MB. |
Returns: An object: kind and url (the saved image).
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
setup_brand
Section titled “setup_brand”POST /api/admin/clientfence/setup_brand
Setup wizard: saves the brand color and the sign-in page style.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
color |
string | The brand color, such as #2563eb. |
login_style |
string | dark, brand or light. |
Returns: An object: color, custom, login_style and css_url.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
setup_email
Section titled “setup_email”POST /api/admin/clientfence/setup_email
Setup wizard: saves how email is sent and the sender address.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
mailer |
string | sendmail (default), smtp, or keep to leave the sending method as it is. |
from_email |
string, required | The address emails are sent from. |
from_name |
string | The sender name. |
smtp_host |
string | Required for smtp. |
smtp_port |
integer | Required for smtp, usually 587 or 465. |
smtp_username |
string | The SMTP user. |
smtp_password |
string | Empty keeps the saved one. |
Returns: true.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
- Choose how email is sent.
- Enter the address emails are sent from.
- Enter the SMTP server name.
- Enter the SMTP port (usually 587 or 465).
setup_test_email
Section titled “setup_test_email”POST /api/admin/clientfence/setup_test_email
Setup wizard: sends a test email to the caller.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: true when sent.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
setup_payments
Section titled “setup_payments”POST /api/admin/clientfence/setup_payments
Setup wizard: turns on manual payment (bank transfer), PayPal and Stripe, and can set the main currency.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
manual_enabled |
boolean | Turn on manual payment. |
manual_text |
string | The payment instructions clients see. Required with manual payment. |
paypal_enabled |
boolean | Turn on PayPal. |
paypal_email |
string | The PayPal address that receives payments. |
stripe_enabled |
boolean | Turn on Stripe. |
stripe_pub_key |
string | Starts with pk_. |
stripe_api_key |
string | Starts with sk_ (or rk_ for a restricted key). |
stripe_webhook_secret |
string | Starts with whsec_. |
currency |
string | The main currency code, such as EUR. Only while no invoice, quote or order exists. |
Returns: true.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
- Turn on at least one payment method; you can change them later in System → Payment Gateways.
- Enter the payment instructions clients see (for example your bank details).
- Enter the PayPal email address that receives payments.
- Choose your main currency.
- Invoices, quotes or orders exist already: change the main currency in System → Currencies.
Everything is checked first, so a refused call changes nothing.
setup_stripe_webhook
Section titled “setup_stripe_webhook”POST /api/admin/clientfence/setup_stripe_webhook
Setup wizard: returns the address to give Stripe for its webhook. Stripe is installed, switched off, when it is not yet.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: An object: url.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
setup_security
Section titled “setup_security”POST /api/admin/clientfence/setup_security
Setup wizard: saves the CAPTCHA, the staff email PIN, the staff country rule and the admin address.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
captcha_provider |
string | none (leave as is), recaptcha_v2, hcaptcha or turnstile. |
captcha_site_key |
string | Required with a CAPTCHA. |
captcha_secret_key |
string | Empty keeps the saved one. |
admin_path |
string | A new admin address: 4 to 40 letters, digits or dashes, such as /team-7k2. Empty keeps it. |
staff_pin |
boolean | Ask staff for an email PIN at sign-in. |
countries_on |
boolean | Allow staff sign-in only from the listed countries. |
countries |
array | Country codes. |
confirm_pin |
string | The PIN emailed by the first call, to finish turning the staff PIN on. |
Returns: {"confirm": true, "email": "..."} when a PIN was sent and the call must be repeated with confirm_pin; otherwise {"admin_url": ...}, the new admin address to go to, or null when it did not change.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
- Choose a captcha service.
- Enter the captcha site key and secret key.
- The admin address is 4 to 40 letters, digits or dashes, for example /team-7k2.
- Choose an admin address of your own: that one is used by the site or is the first bots try.
notifications_get
Section titled “notifications_get”POST /api/admin/clientfence/notifications_get
Returns the caller’s newest notifications and the unread count, as the bell in the admin header shows them.
No parameters.
Returns: An object: unread and items (up to 20, each with id, kind, text, url, created_at, age (seconds since it was made) and read).
notifications_read
Section titled “notifications_read”POST /api/admin/clientfence/notifications_read
Marks one of the caller’s notifications, or all of them, as read.
| Parameter | Type | Description |
|---|---|---|
id |
integer | The notification. Left out: all of them. |
Returns: The number of notifications marked.
notifications_dismiss
Section titled “notifications_dismiss”POST /api/admin/clientfence/notifications_dismiss
Hides one of the caller’s notifications from the bell.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The notification. |
Returns: The number of notifications hidden (0 when id is missing).
settings_index
Section titled “settings_index”POST /api/admin/clientfence/settings_index
Returns what the settings search (Ctrl+K) finds: the settings pages the caller may open, with their tabs and options, in the caller’s language.
No parameters.
Returns: A list of entries: label, kind, page, tab, words (extra search words) and url.
setup_store
Section titled “setup_store”POST /api/admin/clientfence/setup_store
Setup wizard: saves who sees the store.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
store_mode |
string, required | closed, testers or public. |
store_testers_group |
integer | The client group that may order. Required for testers. |
Returns: true.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
- Choose who can see the store.
- Choose the client group that can order.
setup_product
Section titled “setup_product”POST /api/admin/clientfence/setup_product
Setup wizard: adds a first product or service, enabled, in the first product category.
Permission: Only a Super Administrator may call it.
| Parameter | Type | Description |
|---|---|---|
title |
string, required | The name. |
description |
string | The description. |
price |
number | 0 or more. |
billing |
string | once (default) or recurrent. |
period |
string | For recurrent: 1M (default), 3M, 6M, 1Y or 2Y. |
Returns: The new product’s id.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
- Give the product or service a name.
- Enter a price of 0 or more.
- Choose how often the client pays.
Example
Request parameters:
{ "title": "Website care plan", "price": "29.00", "billing": "recurrent", "period": "1M"}result:
7setup_finish
Section titled “setup_finish”POST /api/admin/clientfence/setup_finish
Finishes or skips the setup wizard, so it no longer opens by itself.
Permission: Only a Super Administrator may call it.
No parameters.
Returns: true.
Errors:
- Only Super Administrators can run the setup wizard. (code 403)
Client calls
Section titled “Client calls”notifications_get (client)
Section titled “notifications_get (client)”POST /api/client/clientfence/notifications_get
Returns the client’s newest notifications and the unread count, as the bell in the client area shows them.
No parameters.
Returns: An object: unread and items (up to 20, each with id, kind, text, url, created_at, age (seconds since it was made) and read). Notifications about pages the user may not open are left out.
Example
Request parameters:
{}result:
{ "unread": 1, "items": [ { "id": 42, "kind": "invoice_due", "text": "Invoice EH-0031 is due on 2026-11-20", "url": "https://example.com/invoice/9d3f", "created_at": "2026-11-17 08:00:00", "age": 7200, "read": false } ]}notifications_read (client)
Section titled “notifications_read (client)”POST /api/client/clientfence/notifications_read
Marks one of the client’s notifications, or all of them, as read.
| Parameter | Type | Description |
|---|---|---|
id |
integer | The notification. Left out: all of them. |
Returns: The number of notifications marked.
notifications_dismiss (client)
Section titled “notifications_dismiss (client)”POST /api/client/clientfence/notifications_dismiss
Hides one of the client’s notifications from the bell.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The notification. |
Returns: The number of notifications hidden.
tax (client)
Section titled “tax (client)”POST /api/client/clientfence/tax
Returns the tax the client’s invoices get, so a checkout can show the amount the invoice will ask for.
No parameters.
Returns: An object: name, rate (0 when tax is off or the client is exempt), inclusive (whether prices include tax) and deduct. With prices that include tax, an exempt client pays the price less deduct, the tax rate of their location.
Guest calls
Section titled “Guest calls”brand (guest)
Section titled “brand (guest)”POST /api/guest/clientfence/brand
Returns the sign-in page style and the address of the brand stylesheet.
No parameters.
Returns: An object: login_style (dark, brand or light) and css_url (the brand stylesheet, or null with the default color).
store_open (guest)
Section titled “store_open (guest)”POST /api/guest/clientfence/store_open
Tells whether the store is open to the visitor or the signed-in client.
No parameters.
Returns: true or false.
store_info (guest)
Section titled “store_info (guest)”POST /api/guest/clientfence/store_info
Returns what the store page shows above the products, whether this session is a store preview, and whether a new customer may sign up at checkout.
No parameters.
Returns: An object: title, subtitle, cycle (the billing cycle the store opens on, or empty), preview (whether this session is a store preview) and signup (whether sign-up is open).
signup_info (guest)
Section titled “signup_info (guest)”POST /api/guest/clientfence/signup_info
Returns whether sign-up is open and the links the sign-up form shows.
No parameters.
Returns: An object: open (whether a visitor may sign up now), terms_url and privacy_url (the Terms and Conditions and Privacy Policy addresses of the Google sign-in settings). Both addresses are empty strings unless both are set.
tax_enabled (guest)
Section titled “tax_enabled (guest)”POST /api/guest/clientfence/tax_enabled
Tells whether invoices get tax.
No parameters.
Returns: true or false.
eu_vat (guest)
Section titled “eu_vat (guest)”POST /api/guest/clientfence/eu_vat
Tells whether EU VAT numbers are checked. Sign-up forms then ask for one.
No parameters.
Returns: true or false.
wallet_limits (guest)
Section titled “wallet_limits (guest)”POST /api/guest/clientfence/wallet_limits
Returns the smallest and largest amount a client may add to their wallet, in a currency.
| Parameter | Type | Description |
|---|---|---|
currency |
string | A currency code, such as EUR, to get the limits in that currency. Left out: the default currency. |
Returns: An object: min and max, each null when no limit is set.
See Wallet and credit.
Example
Request parameters:
{ "currency": "EUR"}result:
{ "min": 10, "max": null}store_preview (guest)
Section titled “store_preview (guest)”POST /api/guest/clientfence/store_preview
Opens the store preview for this browser session for 12 hours, when the token matches the preview link.
| Parameter | Type | Description |
|---|---|---|
token |
string, required | The 32-character preview token from the preview link. |
Returns: true when the preview opened, otherwise false.

