System API
The system module holds the general settings, the company details, the cache and maintenance mode settings, and ClientFence updates. Its guest calls return shared data that pages need, such as the company, countries, billing periods and time zones. See Company and branding, Update ClientFence and Maintenance mode.
Admin calls need Module access on the System card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”get_params
Section titled “get_params”POST /api/admin/system/get_params
Returns every system setting saved in the settings table.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: An object: setting name => value (as text), such as company_name, company_email, invoice_starting_number, last_cron_exec.
Example
Request parameters:
{}result:
{ "company_name": "Example Hosting", "company_email": "billing@example.com", "company_tel": "+1 555 0100", "invoice_starting_number": "1043", "last_cron_exec": "2026-11-17 10:05:02"}localization_settings
Section titled “localization_settings”POST /api/admin/system/localization_settings
Returns the default language and whether the client area picks the visitor’s language on its own.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: An object: locale (such as en_US) and auto_detect_locale (boolean).
update_params
Section titled “update_params”POST /api/admin/system/update_params
Saves system settings: each key you send is saved as a setting, and a key that does not exist yet is created.
Permission: Update System Parameters (system.update_params). Company details also need Manage Company Details (system.manage_company_details); the terms, privacy policy and company note need Manage Company Legal (system.manage_company_legal); accounting_* settings need the invoice module’s Manage settings; servicedomain_pinned_tlds needs the domain module’s Manage TLDs.
| Parameter | Type | Description |
|---|---|---|
(settings) |
mixed | Setting name => value, such as company_name, company_email, company_tel, company_address_1, company_vat_number, company_tos, invoice_starting_number (a whole number from 1). |
Returns: true
Errors:
- You do not have permission to update the parameter
(nothing is saved) - Next invoice number must be a positive whole number no greater than
.
Fires onBeforeAdminSettingsUpdate and onAfterAdminSettingsUpdate. Any setting name is accepted, so check the spelling.
Example
Request parameters:
{ "company_name": "Example Hosting", "company_tel": "+1 555 0100"}result:
trueupdate_localization_settings
Section titled “update_localization_settings”POST /api/admin/system/update_localization_settings
Saves the default language and the language auto-detection in the configuration file.
Permission: Update System Parameters (system.update_params)
| Parameter | Type | Description |
|---|---|---|
locale |
string | The default language code, such as en_US. It must be an enabled language. Empty or missing: unchanged. |
auto_detect_locale |
boolean | Pick the visitor’s browser language when it is turned on. Default true when missing. |
Returns: true
Errors:
- Invalid locale code:
cache_settings
Section titled “cache_settings”POST /api/admin/system/cache_settings
Returns the cache settings. The Redis password is never returned.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: An object: driver (filesystem, redis or memcached), redis_host, redis_port, redis_password_set, redis_database, redis_tls_enabled, redis_tls_verify_peer, redis_tls_verify_peer_name, redis_tls_allow_self_signed, redis_tls_cafile, memcached_host and memcached_port.
update_cache_settings
Section titled “update_cache_settings”POST /api/admin/system/update_cache_settings
Saves the cache settings after testing the connection to Redis or Memcached, then clears the old cache. Every setting is replaced, so send them all.
Permission: Update System Parameters (system.update_params), and only a Super Administrator may call it
| Parameter | Type | Description |
|---|---|---|
driver |
string | filesystem (default), redis or memcached. |
redis_host |
string | Default 127.0.0.1. |
redis_port |
integer | Default 6379. |
redis_password |
string | Empty keeps the saved password while host and port stay the same. |
redis_password_clear |
boolean | true to remove the saved password. |
redis_database |
integer | Default 0. |
redis_tls_enabled |
boolean | Connect with TLS. Default false. |
redis_tls_verify_peer |
boolean | Default true. |
redis_tls_verify_peer_name |
boolean | Default true. |
redis_tls_allow_self_signed |
boolean | Default false. |
redis_tls_cafile |
string | Path of a CA file on the server. |
memcached_host |
string | Default 127.0.0.1. |
memcached_port |
integer | Default 11211. |
Returns: true
Errors:
- Only Super Administrators can change the cache settings. (code 403)
- Unsupported cache driver:
(code 5001) - The connection error when Redis or Memcached cannot be reached (nothing is saved).
maintenance_get
Section titled “maintenance_get”POST /api/admin/system/maintenance_get
Returns the maintenance mode settings.
Permission: Manage System Settings (system.manage_settings)
No parameters.
Returns: An object: enabled, message, redirect_url, allowed_ips (one per line) and my_ip (the caller’s IP address, to add to the list).
Example
Request parameters:
{}result:
{ "enabled": false, "message": "We are upgrading our systems and will be back soon.", "redirect_url": "", "allowed_ips": "203.0.113.20", "my_ip": "203.0.113.20"}maintenance_update
Section titled “maintenance_update”POST /api/admin/system/maintenance_update
Turns maintenance mode on or off and saves its settings. Every setting is replaced, so send them all.
Permission: Update System Parameters (system.update_params)
| Parameter | Type | Description |
|---|---|---|
enabled |
boolean | true closes the client area, the store and the API to everyone who is not on allowed_ips and not a signed-in staff member (API calls then fail with code 503, admin calls made with an API key too). The admin area stays open. Default false. |
allowed_ips |
string | IP addresses or ranges (203.0.113.0/24) that still get in, separated by spaces, commas or new lines. Add your own. |
message |
string | The message visitors see, up to 2000 characters. |
redirect_url |
string | Send visitors to this https:// or http:// address on another site instead. |
Returns: true
Errors:
- “
” is not an IP address or range. - The redirect address must be a full address starting with https:// or http://.
- The redirect address must be on another site: this portal is closed during maintenance.
- The message can be at most 2000 characters.
Example
Request parameters:
{ "enabled": true, "allowed_ips": "203.0.113.20", "message": "We are upgrading our systems and will be back soon."}result:
truemessages
Section titled “messages”POST /api/admin/system/messages
Returns the alerts the admin dashboard shows: an available update, pending database patches, cron not running, the installer folder still present, broken email templates and failed order actions.
Permission: Manage System Settings (system.manage_settings). Without it the call returns an empty list instead of an error.
| Parameter | Type | Description |
|---|---|---|
type |
string | Only alerts of this type: danger, warning, info or success. |
Returns: A list of alerts, each with type, title, message, buttons (each with link, text, type) and dismissible.
Example
Request parameters:
{}result:
[ { "type": "danger", "title": "Failed Order Actions", "message": "1 order action(s) failed: a hosting panel, registrar or other service refused or could not finish them.", "buttons": [ { "link": "https://billing.example.com/admin/order/failed-actions", "text": "View Failed Actions", "type": "danger" } ], "dismissible": true }]cas_messages
Section titled “cas_messages”POST /api/admin/system/cas_messages
Returns the alerts the central alert service sent to this installation.
Permission: Manage System Settings (system.manage_settings). Without it the call returns an empty list instead of an error.
No parameters.
Returns: A list of alerts. When they cannot be fetched, one warning alert with the reason.
Not checked in a live run: the alert fields come from the remote service.
template_exists
Section titled “template_exists”POST /api/admin/system/template_exists
Says whether an admin theme template file exists, for example a module’s optional page part.
Permission: Every staff account may call it, even without access to the System module.
| Parameter | Type | Description |
|---|---|---|
file |
string, required | A template file name, such as mod_order_manage_custom.html.twig. Letters, digits, _, - and / only, ending in .html.twig. |
Returns: true or false (also false for a missing or invalid file).
POST /api/admin/system/env
Returns the server checks: writable folders and files, PHP extensions and the last database patch. With ip, returns the server’s public IP address instead.
Permission: Manage System Settings (system.manage_settings)
| Parameter | Type | Description |
|---|---|---|
ip |
boolean | true to return only the server’s public IP address (empty when it cannot be found). |
Returns: Without ip: an object with folders and files (path => writable), required_extensions (name => loaded), suggested_extensions (name => loaded and message, for the ones missing) and last_patch. With ip: the IP address as text.
is_allowed
Section titled “is_allowed”POST /api/admin/system/is_allowed
Says whether the caller has access to a module, or one of its permissions.
Permission: Every staff account may call it (for a module name of lowercase letters, digits and _).
| Parameter | Type | Description |
|---|---|---|
mod |
string, required | The module, such as invoice. |
f |
string | A permission key of that module, such as view. Without it, access to the module is checked. |
Returns: true or false. Super Administrators always get true.
Errors:
- “mod” key is missing
Example
Request parameters:
{ "mod": "invoice", "f": "view"}result:
trueclear_cache
Section titled “clear_cache”POST /api/admin/system/clear_cache
Clears the cache: the cache folder and the configured cache store (Redis or Memcached).
Permission: Invalidate Cache (system.invalidate_cache)
No parameters.
Returns: true
update_available
Section titled “update_available”POST /api/admin/system/update_available
Says whether the last daily check of the ClientFence release feed found a newer version. It does not contact the feed.
Permission: View System Information (system.view)
No parameters.
Returns: true or false.
update_info
Section titled “update_info”POST /api/admin/system/update_info
Returns what the release feed says about the newest version, and whether this server is ready to install it.
Permission: View System Information (system.view)
No parameters.
Returns: An object: version (the newer version, else the installed one), download_url, release_date, release_notes, update_type, last_check, next_check, branch (release), minimum_php_version, digest (SHA-256 of the archive), check_enabled, channel (the update channel chosen), release_channel, check_error, current_php_version, php_version_supported and readiness (can_update and issues, each with path, type, reason, message). The release fields are null when there is no newer version.
Example
Request parameters:
{}result:
{ "version": "1.0.58", "download_url": "https://…/clientfence-1.0.58.zip", "release_date": "2026-11-20", "release_notes": "…", "update_type": 1, "last_check": "2026-11-17 06:00:00", "next_check": "2026-11-18 06:00:00", "branch": "release", "minimum_php_version": "8.3", "digest": "…", "check_enabled": true, "channel": "stable", "release_channel": "stable", "check_error": null, "current_php_version": "8.3.14", "php_version_supported": true, "readiness": { "can_update": true, "issues": [] }}recheck_update
Section titled “recheck_update”POST /api/admin/system/recheck_update
Checks the ClientFence release feed again now, instead of waiting for the daily check.
Permission: Recheck for Updates (system.recheck_update)
No parameters.
Returns: true. Read the result with update_info.
update_core
Section titled “update_core”POST /api/admin/system/update_core
Downloads and installs the newer ClientFence version’s files. Then finalize the update with finalize_update.
Permission: Update ClientFence (system.system_update)
No parameters.
Returns: true when the files are installed and finalization is pending.
Errors:
- You have the latest version of ClientFence. You do not need to update.
- Another update appears to already be in progress. Please wait for it to finish before trying again.
- An update finalization is already pending. Complete finalization before starting another update.
- ClientFence does not have sufficient filesystem permissions to perform the update. Resolve the reported issues before trying again. (code 820)
- The ClientFence release feed did not provide a SHA-256 digest. Update canceled for security reasons.
Make a backup first. Staff without the permission are refused before ClientFence asks the update feed. Fires onBeforeAdminUpdateCore. While finalization is pending, the admin API answers only the update calls, and cron is paused.
update_finalization_status
Section titled “update_finalization_status”POST /api/admin/system/update_finalization_status
Returns whether an installed update still has to be finalized.
Permission: While finalization is pending: Super Administrators only. Otherwise Update ClientFence (system.system_update).
No parameters.
Returns: An object: required, status (not_required when nothing waits), current_version, clientfence_version, state (the saved finalization state) and pending_patches.
finalize_update
Section titled “finalize_update”POST /api/admin/system/finalize_update
Finalizes an installed update: applies the database and configuration patches and clears the cache.
Permission: While finalization is pending: Super Administrators only. Otherwise Update ClientFence (system.system_update).
No parameters.
Returns: true
Errors:
- You need to be a Super Administrator to finalize this update. (code 403)
- Unable to clear cache and/or remove install folder while finalizing the update. Further details are available in the error log.
Fires onAfterAdminUpdateCore. Then call complete_update_finalization.
complete_update_finalization
Section titled “complete_update_finalization”POST /api/admin/system/complete_update_finalization
Ends the update: after finalize_update, marks the finalization as done so the admin API and cron work normally again.
Permission: While finalization is pending: Super Administrators only. Otherwise Update ClientFence (system.system_update).
No parameters.
Returns: true
Errors:
- Update finalization must be run before it can be completed.
- There are still
pending update patches (database level , code level ). Re-run finalization before completing the update.
manual_update
Section titled “manual_update”POST /api/admin/system/manual_update
Applies the pending database and configuration patches and clears the cache, for an update whose files were copied to the server by hand.
Permission: Update ClientFence (system.system_update)
No parameters.
Returns: true
Errors:
- Unable to clear the cache after applying manual update patches. Further details are available in the error log.
Fires onBeforeAdminManualUpdate and onAfterAdminManualUpdate.
is_behind_on_patches
Section titled “is_behind_on_patches”POST /api/admin/system/is_behind_on_patches
Says whether database patches are waiting to be applied.
Permission: View System Information (system.view)
No parameters.
Returns: true or false.
instance_id
Section titled “instance_id”POST /api/admin/system/instance_id
Returns this installation’s unique ID.
Permission: View System Information (system.view)
No parameters.
Returns: The instance ID as text.
get_interface_ips
Section titled “get_interface_ips”POST /api/admin/system/get_interface_ips
Lists the server’s local IP addresses that can reach the internet, to choose the one ClientFence sends its outgoing requests from.
Permission: Manage the Network Interface (system.manage_network_interface)
No parameters.
Returns: A list of IP addresses (each one is tested with a request, so the call can take a few seconds).
set_interface_ip
Section titled “set_interface_ip”POST /api/admin/system/set_interface_ip
Sets the IP address or interface ClientFence sends its outgoing requests from.
Permission: Manage the Network Interface (system.manage_network_interface)
| Parameter | Type | Description |
|---|---|---|
interface |
string | One of the local IP addresses, or 0 for the default. |
custom_interface |
string | An IP address or an interface or host name such as eth0; empty to clear. |
Returns: true
Errors:
- Invalid interface IP address
- Invalid custom interface. Must be a valid IP address or hostname.
See Advanced network settings.
Guest calls
Section titled “Guest calls”company (guest)
Section titled “company (guest)”POST /api/guest/system/company
Returns the company details: name, contact details, logos, address, bank details, legal texts and email brand colors.
| Parameter | Type | Description |
|---|---|---|
locale |
string | A turned-on language code such as ar_SA: the name and address lines in that language, where you entered them in Languages on the Company Details tab. Without it, the visitor’s language; empty fields keep the default. |
Returns: An object: www, name, email, tel, signature, logo_url, logo_url_dark, logo_url_email, favicon_url, address_1, address_2, address_3, account_number, bank_name, bic, display_bank_info, bank_info_pagebottom, number, note, privacy_policy, tos, vat_number, invoice_title, tax_label, brand_color, brand_text and brand_link.
When Hide Some Company Information in the Guest API is on, visitors who are not signed in do not get vat_number, email, tel, account_number, number, the address lines, bank_name and bic.
Example
Request parameters:
{}result:
{ "www": "https://billing.example.com/", "name": "Example Hosting", "email": "billing@example.com", "tel": "+1 555 0100", "signature": "Example Hosting team", "logo_url": "https://billing.example.com/uploads/logo.png", "logo_url_dark": "https://billing.example.com/uploads/logo.png", "logo_url_email": "https://billing.example.com/uploads/logo.png", "favicon_url": null, "address_1": "1 Main St", "address_2": "Springfield, IL 62701", "address_3": "United States", "account_number": null, "bank_name": null, "bic": null, "display_bank_info": "0", "bank_info_pagebottom": "0", "number": null, "note": null, "privacy_policy": "…", "tos": "…", "vat_number": null, "invoice_title": "", "tax_label": "", "brand_color": "#2563eb", "brand_text": "#ffffff", "brand_link": "#2563eb"}default_country (guest)
Section titled “default_country (guest)”POST /api/guest/system/default_country
Returns the default country of forms.
No parameters.
Returns: A two-letter country code such as US, or null when none is set.
countries (guest)
Section titled “countries (guest)”POST /api/guest/system/countries
Returns the countries forms offer: the list set in the system settings, or every country.
No parameters.
Returns: An object: country code => name, such as {"DE": "Germany", "US": "United States"}.
param (guest)
Section titled “param (guest)”POST /api/guest/system/param
Returns the value of one public system setting.
| Parameter | Type | Description |
|---|---|---|
key |
string, required | The setting’s name. Only settings marked public can be read. |
Returns: The value as text.
Errors:
- “key” parameter was not passed
- Parameter
does not exist (also for a setting that is not public)
periods (guest)
Section titled “periods (guest)”POST /api/guest/system/periods
Returns the billing periods.
No parameters.
Returns: An object: period code => title: 1W Every Week, 1M Every Month, 3M Every 3 Months, 6M Every 6 Months, 1Y Every Year, 2Y Every 2 Years, 3Y Every 3 Years, 4Y Every 4 Years, 5Y Every 5 Years (titles in the current language).
phone_codes (guest)
Section titled “phone_codes (guest)”POST /api/guest/system/phone_codes
Returns the international phone calling codes.
No parameters.
Returns: A sorted list of numbers, such as [1, 7, 20, 27, …].
period_title (guest)
Section titled “period_title (guest)”POST /api/guest/system/period_title
Returns the title of a billing period code.
| Parameter | Type | Description |
|---|---|---|
code |
string | A period code, such as 1M or 2Y. |
Returns: The title, such as Every Month; - when code is empty.
paginator (guest)
Section titled “paginator (guest)”POST /api/guest/system/paginator
Works out the page numbers to show under a paged list.
| Parameter | Type | Description |
|---|---|---|
total |
integer | Number of items. Default 0. |
per_page |
integer | Items per page. Default 20. |
page |
integer | The current page, read from the key named by page_param. Default 1. |
page_param |
string | The name of the current page key. Default page. |
Returns: An object: currentpage, numpages, midrange (7), range (the page numbers to show), start and end.
current_url (guest)
Section titled “current_url (guest)”POST /api/guest/system/current_url
Returns the path and query of the current request.
No parameters.
Returns: The request URI, such as /api/guest/system/current_url.
template_exists (guest)
Section titled “template_exists (guest)”POST /api/guest/system/template_exists
Says whether a client theme template file exists.
| Parameter | Type | Description |
|---|---|---|
file |
string, required | A template file name, such as mod_page_sitemap.html.twig. Letters, digits, _, - and / only, ending in .html.twig. |
Returns: true or false (also false for a missing or invalid file).
locale (guest)
Section titled “locale (guest)”POST /api/guest/system/locale
Returns the language of the current visitor: the one they chose, else the browser’s (with auto-detection on), else the default.
No parameters.
Returns: A language code, such as en_US.
timezones (guest)
Section titled “timezones (guest)”POST /api/guest/system/timezones
Returns the time zones, grouped by region.
No parameters.
Returns: An object: region => list of time zones, starting with UTC, such as {"UTC": ["UTC"], "Africa": ["Africa/Abidjan", …], …}.
get_pending_messages (guest)
Section titled “get_pending_messages (guest)”POST /api/guest/system/get_pending_messages
Returns the messages waiting in the session to be shown on the next page, and removes them.
No parameters.
Returns: A list of messages (empty when there are none).

