WebPros International, LLC
API docs by Redocly

WHM API

WebPros International, LLC: [email protected] URL: https://cpanel.net/support/ License: cPanel License Terms of Service

WHM API.

https://cpanel.net/developers/

Restore Account

Account Restoration / Restore Account

Restore user account from backup

This function restores a user's cPanel account from a backup file.

Authorizations:
BasicAuth
query Parameters
destid
string
Default: "local"
Example: destid=LmTZCUpqqLSPH8AO7pVtIeNK

The destination's identification string.

  • local — The local directory.
  • The destination ID string's value.
give_ip
integer
Default: 0
Possible Values: 0 1
Example: give_ip=1

Whether to assign the account a dedicated IP address.

  • 1 — Assign a dedicated IP address.
  • 0 — Use the shared IP address.
mail_config
integer
Default: 0
Possible Values: 0 1
Example: mail_config=1

Whether to restore the account's email configuration.

  • 1 — Restore.
  • 0 — Do not restore.
mysql
integer
Default: 0
Possible Values: 0 1
Example: mysql=1

Whether to restore the account's MySQL® databases.

  • 1 — Restore.
  • 0 — Do not restore.
restore_point
required
string
Example: restore_point=2019-10-21T00:00:00.000Z

The date of the backup to use, in YYYY-MM-DD format.

subdomains
integer
Default: 0
Possible Values: 0 1
Example: subdomains=1

Whether to restore the account's subdomains.

  • 1 — Restore.
  • 0 — Do not restore.
user
required
string
Example: user=username

The cPanel account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_add_task \
  user='username' \
  restore_point='2019-10-21T00:00:00.000Z'

Response samples

Content type
application/json
{
  • "data": {
    • "queue_id": "3b99QG5fp99tdL5"
    },
  • "metadata": {
    • "command": "restore_queue_add_task",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore account backup

This function restores an account backup. You can use this function to restore daily, weekly, or monthly backups.

Important:

  • When you call this function, you must include at least one of the all, mail, subs, or mysql parameters.

  • On servers with a custom Whostmgr::Transfers module, the function may not return XML output. To properly return XML output, the Whostmgr::Transfers module must allow the system to use the Cpanel::Demultiplexer module to capture output.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.

  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.

Authorizations:
BasicAuth
query Parameters
all
integer
Possible Values: 0 1
Example: all=1

Whether to create the account before restoration.

  • 1 — Create and then restore the account. If you select this value and the account already exists, the function will fail.
  • 0 — Restore only.
ip
integer
Possible Values: 0 1
Example: ip=1

Whether to assign a dedicated IP address to the restored account.

  • 1 — Assign a dedicated IP address.
  • 0 — Use the shared IP address.
mail
integer
Possible Values: 0 1
Example: mail=1

Whether to restore account-level filters (vfilters) and forwarders (valiases).

  • 1 — Restore.
  • 0 — Do not restore.
mysql
integer
Possible Values: 0 1
Example: mysql=1

Whether to restore the account's MySQL® databases.

  • 1 — Restore.
  • 0 — Do not restore.
subs
integer
Possible Values: 0 1
Example: subs=1

Whether to restore the account's subdomains.

  • 1 — Restore.
  • 0 — Do not restore.
type
required
string
Possible Values: "monthly" "weekly" "daily"
Example: type=monthly

The type of backup to restore. The function restores the most recent backup of the type that you specify:

  • monthly
  • weekly
  • daily
user
required
string
Example: user=username

The account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restoreaccount \
  user='username' \
  type='monthly'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restoreaccount",
    • "output": {
      • "raw": "Extracting tarball...................\nDone<br />\nExtracting Domain....Done<br />\nDone<br />\n<br /><br />Restoring cpanel user config fileDone<br />\n<br />Restoring reseller privs (if any)<br />Restoring Locale Setting<br />Restoring SSL keys and CertificatesDone<br />\n<br />Restoring frontpage (if installed)Done<br />\n<br />Restoring access logs....\nDone<br />\n<br /><br />Restoring domain keys....\nDone<br />\n<br /><br />Restoring DB MAP File....\nDone<br />\n<br /><br /><span class=\"b2\">Restoring PostgreSQL databases....</span>\nRestoring PostgreSQL privs<!--\n-->\nDone<br />\n<br />Restoring Mailman listsDone<br />\n<br />Restoring Mailman ArchivesDone<br />\n<br />Restoring shell<blockquote><pre>Current shell /bin/bash is up to date.\n</pre></blockquote>Done<br />\n<br />Restoring password<blockquote><pre></pre></blockquote>Done<br />\n<br />Restoring proftpd fileDone<br />\n<br />Resyncing FTP Passwords<blockquote><pre>Updating ftp passwords for userFtp password files updated.Ftp vhost passwords synced</pre></blockquote>Done<br />\n<br />Linking old home directories<br />Parsing Domain Databases...ParkedDomains......AddonDomains...<br />Restoring Domains<br />\n<br />Restoring Bandwidth DataDone\n<br />Restoring Counter Data<pre></pre><br />Restoring Homedir....<blockquote><pre></pre></blockquote>Done<br />\n<br />Doing fileprotect conversion<br />Restoring nobody owned filesDone<br />\n<br />Restoring Mail filesDone<br />\n<br />Restoring userdata....\nDone<br />\n<br /><br />Restoring custom virtualhost templates....\nConverting email to cPanel 5+ (if needed)<blockquote><pre></pre></blockquote>Done<br />\n<br />Cleaning up filters (if needed)<blockquote><pre>vfilter converter v3.0Updating vfilter files to latest format.Running for user only (force=0) (has_spam_acl=1)Processing user......Done</pre></blockquote>Done<br />\n<br />Fixing mail permissions<blockquote><pre></pre></blockquote>Done<br />\n<br />Restoring crontabDone<br />\nConverting to maildir if needed<blockquote><pre></pre></blockquote>Done<br />\nRestoring Dns Zones<blockquote><pre>Restoring zone: user.com.db\n</pre></blockquote><br />Adding missing subdomain DNS entries (if needed)<pre></pre><br />Update Proxy subomains<blockquote><pre>Adding proxy subdomains for domain example.com.Records Installed</pre></blockquote>Done<br />\n<br />Updating SPF Records<blockquote><pre></pre></blockquote>Done<br />\n<br />Restoring quota<blockquote><pre></pre></blockquote>Done<br />\n<br /><br />Update mail routing<blockquote><pre>LOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.: This configuration has been manually selected.\n</pre></blockquote>Done<br />\n<br />Rebuilding Apache Conf<br />Restore CompleteAccount Restore Complete\nUnlocking password for user user.passwd: Success.<br />"
      },
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate username during restoration

This function checks for username conflicts during account restoration. If the function detects a username conflict, it outputs an error message in the reason return.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=username

The cPanel account that you wish to transfer to the server.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_new_username_for_restore \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "verify_new_username_for_restore",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore Queue Management

Account Restoration / Restore Queue Management

Start restoration

This function activates the restore queue. This triggers a process that restores all queued accounts.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_activate

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_activate",
    • "reason": "Restore queue processing initiated",
    • "result": 1,
    • "version": 1
    }
}

Remove all completed restoration tasks

This function removes successfully completed tasks from the restoration queue.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_clear_all_completed_tasks

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_clear_all_completed_tasks",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove all failed restoration tasks

This function removes any failed tasks from the restoration queue.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_clear_all_failed_tasks

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_clear_all_failed_tasks",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove all pending restoration tasks

This function removes any pending tasks from the restoration queue.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_clear_all_pending_tasks

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_clear_all_pending_tasks",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove all restoration tasks

This function removes all tasks from the restoration queue.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_clear_all_tasks

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_clear_all_tasks",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove pending restoration task

This function removes a single pending task from the restoration queue.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=username

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_clear_pending_task \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_clear_pending_task",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove completed restoration task

This function removes a single completed task from the restoration queue.

Authorizations:
BasicAuth
query Parameters
start_time
required
integer <unix_timestamp>
Example: start_time=1396065600

When the restoration queue started the restoration.

user
required
string <username>
Example: user=username

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_clear_completed_task \
  user='username' \
  start_time='1396065600'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_queue_clear_completed_task",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore Queue Reporting

Account Restoration / Restore Queue Reporting

Validate restoration queue is active

This function checks whether the system's restoration queue is actively processing tasks.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_is_active

Response samples

Content type
application/json
{
  • "data": {
    • "is_active": 1
    },
  • "metadata": {
    • "command": "restore_queue_is_active",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return active restoration tasks list

This function lists the tasks that the restoration queue is actively processing.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_list_active

Response samples

Content type
application/json
{
  • "data": {
    • "restore_job": [
      • {
        • "options": {
          • "destid": "local",
          • "give_ip": 1,
          • "mail_config": 1,
          • "mysql": 1,
          • "subdomains": 1
          },
        • "restore_point": "2019-10-21T00:00:00.000Z",
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "restore_queue_list_active",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return completed restoration tasks list

This function lists the restoration queue's completed tasks.

Important:

This function's output varies dramatically. The /usr/local/cpanel/bin/backup_restore_manager script run with the list_finished option determines this output..

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_list_completed

Response samples

Content type
application/json
Example

A task that the restore_queue_add_task function added.

{
  • "data": {
    • "restore_job": [
      • {
        • "restore_job": {
          • "options": {
            • "destid": "local",
            • "give_ip": 0,
            • "mail_config": 0,
            • "mysql": 0,
            • "subdomains": 0
            },
          • "restore_point": "2020-03-29",
          • "user": "mrfrog"
          },
        • "status_info": {
          • "altered_items": null,
          • "dangerous_items": null,
          • "finished": "1586188203",
          • "log": "warning",
          • "restore_logfile": "item-RESTORE_AccountLocal_mrfrog",
          • "result": 2,
          • "skipped_items": null,
          • "started": "1586188078",
          • "status": 2,
          • "statusmsg": "warning",
          • "transfer_session_id": "userbackup20200406154758JqBa",
          • "warnings": null
          }
        }
      ]
    },
  • "metadata": {
    • "command": "restore_queue_list_completed",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return restoration tasks list

This function lists the tasks in the restoration queue.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_state

Response samples

Content type
application/json
{
  • "data": {
    • "active": [
      • {
        • "options": {
          • "give_ip": 1,
          • "mail_config": 1,
          • "mysql": 1,
          • "subdomains": 1
          },
        • "restore_point": "2019-10-21T00:00:00.000Z",
        • "user": "username"
        }
      ],
    • "completed": [
      • {
        • "options": {
          • "give_ip": 1,
          • "mail_config": 0,
          • "mysql": 1,
          • "subdomains": 0
          },
        • "restore_point": "2019-10-22T00:00:00.000Z",
        • "user": "username"
        }
      ],
    • "is_active": 1,
    • "pending": [
      • {
        • "options": {
          • "give_ip": 0,
          • "mail_config": 1,
          • "mysql": 0,
          • "subdomains": 1
          },
        • "restore_point": "2019-10-23T00:00:00.000Z",
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "restore_queue_state",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return pending restoration tasks list

This function lists the tasks that the restoration queue has not yet processed.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_queue_list_pending

Response samples

Content type
application/json
{
  • "data": {
    • "restore_job": [
      • {
        • "options": {
          • "destid": "LmTZCUpqqLSPH8AO7pVtIeNK",
          • "give_ip": 1,
          • "mail_config": 1,
          • "mysql": 1,
          • "subdomains": 1
          },
        • "restore_point": "2015-10-21T00:00:00.000Z",
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "restore_queue_list_pending",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return backup modules list

This function lists backup modules and their descriptions.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_modules_summary

Response samples

Content type
application/json
{
  • "data": {
    • "modules": [
      • {
        • "module": "APITokens",
        • "restricted_available": 1,
        • "summary": [
          • "The APITokens module restores the API tokens for an account."
          ]
        },
      • {
        • "module": "Account",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "Force mode is not available in restricted mode."
          ],
        • "summary": [
          • "This creates the cPanel account and system user."
          ]
        },
      • {
        • "module": "AuthnLinks",
        • "restricted_available": 1,
        • "summary": [
          • "This restores the account’s external authentication links."
          ]
        },
      • {
        • "module": "AutoSSL",
        • "restricted_available": 1,
        • "summary": [
          • "This restores AutoSSL settings."
          ]
        },
      • {
        • "module": "BackupConfig",
        • "restricted_available": 1,
        • "summary": [
          • "This installs the backup configuration based on the target system’s defaults."
          ]
        },
      • {
        • "module": "BandwidthData",
        • "restricted_available": 1,
        • "summary": [
          • "This restores the bandwidth data."
          ]
        },
      • {
        • "module": "CpUser",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "The system discards configuration data that is unknown or that the system cannot validate."
          ],
        • "summary": [
          • "This restores the cPanel account’s configuration data."
          ]
        },
      • {
        • "module": "Cron",
        • "restricted_available": 1,
        • "summary": [
          • "This restores crontab entries."
          ]
        },
      • {
        • "module": "CustomLocale",
        • "restricted_available": 0,
        • "summary": [
          • "This restores custom locales."
          ]
        },
      • {
        • "module": "DKIM",
        • "restricted_available": 1,
        • "summary": [
          • "This restores DKIM (DomainKeys Identified Mail) keys and updates records for the current server."
          ]
        },
      • {
        • "module": "DNSAuthority",
        • "restricted_available": 1,
        • "summary": [
          • "This module reports whether this system is authoritative for each of the new accounts’ DNS (Domain Name System) zones."
          ]
        },
      • {
        • "module": "DNSSEC",
        • "restricted_available": 1,
        • "summary": [
          • "This module restores the DNSSEC keys for an account."
          ]
        },
      • {
        • "module": "DigestShadow",
        • "restricted_available": 1,
        • "summary": [
          • "This restores password data for digest authentication."
          ]
        },
      • {
        • "module": "Domains",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "The system will restore subdomains, parked domains, and addon domains if they pass the server’s domain creation rules. If the server rejects the restoration of an addon domain, it will still create a subdomain associated with that addon domain."
          ],
        • "summary": [
          • "This restores subdomains, parked domains, and addon domains."
          ]
        },
      • {
        • "module": "FeatureList",
        • "restricted_available": 1,
        • "summary": [
          • "This restores the account’s feature list setting."
          ]
        },
      • {
        • "module": "FileProtect",
        • "restricted_available": 1,
        • "summary": [
          • "This configures the account for cPanel FileProtect."
          ]
        },
      • {
        • "module": "Ftp",
        • "restricted_available": 1,
        • "summary": [
          • "This restores FTP (File Transfer Protocol) accounts."
          ]
        },
      • {
        • "module": "Homedir",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "If the home directory does not already exist, the system will not create it."
          ],
        • "summary": [
          • "This restores the home directory’s contents."
          ]
        },
      • {
        • "module": "Htaccess",
        • "restricted_available": 1,
        • "summary": [
          • "This repairs EasyApache4 and removes legacy Frontpage entries from .htaccess."
          ]
        },
      • {
        • "module": "IPAddress",
        • "restricted_available": 1,
        • "summary": [
          • "This sets up a dedicated IP address."
          ]
        },
      • {
        • "module": "Integration",
        • "restricted_available": 0,
        • "summary": [
          • "Implementor Error: The summary for this module is missing."
          ]
        },
      • {
        • "module": "LinkedNodes",
        • "restricted_available": 1,
        • "summary": [
          • "This module handles the linked node setup."
          ]
        },
      • {
        • "module": "LinkedNodesSubarchives",
        • "restricted_available": 1,
        • "summary": [
          • "This module restores linked-node configurations when the archive contains linked node data."
          ]
        },
      • {
        • "module": "LocalConfig",
        • "restricted_available": 1,
        • "summary": [
          • "This module updates the local user’s configuration."
          ]
        },
      • {
        • "module": "Logs",
        • "restricted_available": 1,
        • "summary": [
          • "This restores service access logs."
          ]
        },
      • {
        • "module": "Mail",
        • "restricted_available": 1,
        • "summary": [
          • "This resets email quotas to safe values and restores email aliases, filters and mail items."
          ]
        },
      • {
        • "module": "MailFix",
        • "restricted_available": 1,
        • "summary": [
          • "This repairs mail permissions and upgrades the system to the latest storage methods."
          ]
        },
      • {
        • "module": "MailLimits",
        • "restricted_available": 1,
        • "summary": [
          • "This restores any holds or suspensions on outgoing messages for a user’s email accounts."
          ]
        },
      • {
        • "module": "MailRouting",
        • "restricted_available": 1,
        • "summary": [
          • "This updates MX (Mail eXchange) records."
          ]
        },
      • {
        • "module": "MailSync",
        • "restricted_available": 1,
        • "summary": [
          • "This copies any new mail to the local server that the remote account received during the transfer."
          ]
        },
      • {
        • "module": "Mailman",
        • "restricted_available": 1,
        • "summary": [
          • "This restores mailing lists."
          ]
        },
      • {
        • "module": "ManualMX",
        • "restricted_available": 1,
        • "summary": [
          • "This configures the source server’s manual MX entries to send mail to the destination server."
          ]
        },
      • {
        • "module": "Mysql",
        • "restricted_available": 1,
        • "summary": [
          • "This restores MariaDB/MySQL databases, users, and grants."
          ]
        },
      • {
        • "module": "MysqlRemoteNotes",
        • "restricted_available": 1,
        • "summary": [
          • "The MysqlRemoteNotes module restores the Remote MySQL comments for an account."
          ]
        },
      • {
        • "module": "NobodyFiles",
        • "restricted_available": 1,
        • "summary": [
          • "This restores ownership of files previously owned by the “nobody” user in the home directory."
          ]
        },
      • {
        • "module": "OldHomedirs",
        • "notes": [
          • "Symbolic links for former home directories ensure that applications with hard-coded paths continue to work when transferred between servers."
          ],
        • "restricted_available": 0,
        • "summary": [
          • "This creates symbolic links to former home directory paths."
          ]
        },
      • {
        • "module": "Package",
        • "notes": [
          • "If the target server does not have the package that the user has been assigned, the system will use the account’s properties to recreate the package."
          ],
        • "restricted_available": 0,
        • "summary": [
          • "This recreates account packages."
          ]
        },
      • {
        • "module": "Password",
        • "restricted_available": 1,
        • "summary": [
          • "This restores the encrypted system password."
          ]
        },
      • {
        • "module": "PostRestoreActions",
        • "notes": [
          • "This module updates system databases and name server IP address lists, restarts services, unblocks dynamic content, and runs custom post-restoration scripts."
          ],
        • "restricted_available": 1,
        • "summary": [
          • "This runs post-restoration actions and cleanups."
          ]
        },
      • {
        • "module": "Postgres",
        • "restricted_available": 0,
        • "restricted_summary": [
          • "PostgreSQL version “8.4” or later is required to restore databases in restricted mode."
          ],
        • "summary": [
          • "This restores PostgreSQL databases, users, and grants."
          ]
        },
      • {
        • "module": "PreRestoreActions",
        • "notes": [
          • "This module temporarily lifts the account’s quota and runs custom pre-restoration scripts."
          ],
        • "restricted_available": 1,
        • "summary": [
          • "This performs pre-restoration actions and cleanups."
          ]
        },
      • {
        • "module": "ProxySubdomains",
        • "notes": [
          • "This module ensures that service subdomains such as “cpanel”, “cpcalendars”, and “cpcontacts” are configured properly."
          ],
        • "restricted_available": 1,
        • "summary": [
          • "This restores service subdomains."
          ]
        },
      • {
        • "module": "PublicContact",
        • "restricted_available": 1,
        • "summary": [
          • "This restores the account’s public contact data."
          ]
        },
      • {
        • "module": "PublicHtmlSymlinks",
        • "notes": [
          • "Symbolic links for former web root directories ensure that applications with hard-coded paths will continue to work when transferred between servers."
          ],
        • "restricted_available": 1,
        • "restricted_summary": [
          • "The system does not recreate symbolic links outside of the account’s home directory in restricted mode."
          ],
        • "summary": [
          • "This creates symbolic links to former web root directory paths."
          ]
        },
      • {
        • "module": "PublishZones",
        • "restricted_available": 1,
        • "summary": [
          • "This module ensures all zones have been synced out and reloaded across the DNS (Domain Name System) cluster."
          ]
        },
      • {
        • "module": "Quota",
        • "restricted_available": 1,
        • "summary": [
          • "This restores the account’s data storage quota."
          ]
        },
      • {
        • "module": "Reseller",
        • "notes": [
          • "This restores all of the privileges the account previously had. This includes the “all” privilege, which is equivalent to root access."
          ],
        • "restricted_available": 0,
        • "summary": [
          • "This restores reseller privileges."
          ]
        },
      • {
        • "module": "ResyncHomedir",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "If the home directory does not already exist, the system will not create it."
          ],
        • "summary": [
          • "This module will resynchronize the home directory from the source server. The module preserves any changes that occurred during the transfer."
          ]
        },
      • {
        • "module": "Roundcube",
        • "restricted_available": 1,
        • "summary": [
          • "This restores Roundcube configuration and preferences."
          ]
        },
      • {
        • "module": "SPF",
        • "restricted_available": 1,
        • "summary": [
          • "This restores SPF (Sender Policy Framework) records and updates them for the target server."
          ]
        },
      • {
        • "module": "SSL",
        • "restricted_available": 1,
        • "summary": [
          • "This restores SSL (Secure Sockets Layer) keys, certificates, and virtual host entries."
          ]
        },
      • {
        • "module": "ServiceProxy",
        • "restricted_available": 1,
        • "summary": [
          • "This module sets up applicable service proxying to the destination servers."
          ]
        },
      • {
        • "module": "Shell",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "In restricted mode, the system will set any account that requests a shell other than “noshell” or “jailshell” to use “jailshell”."
          ],
        • "summary": [
          • "This restores the account’s shell."
          ]
        },
      • {
        • "module": "SpamAssassin",
        • "restricted_available": 0,
        • "summary": [
          • "This module will disable SpamAssassin for the restored user if they had it enabled at the source."
          ]
        },
      • {
        • "module": "Subaccount",
        • "restricted_available": 0,
        • "summary": [
          • "Implementor Error: The summary for this module is missing."
          ]
        },
      • {
        • "module": "Suspend",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "The system will not restore the suspension reason or old shell for the account and instead will use a default."
          ],
        • "summary": [
          • "This module will suspend the restored user if they were suspended at the source."
          ]
        },
      • {
        • "module": "Unsuspend",
        • "restricted_available": 1,
        • "summary": [
          • "This unsuspends .htaccess files."
          ]
        },
      • {
        • "module": "VhostIncludes",
        • "restricted_available": 0,
        • "summary": [
          • "This restores custom virtual host includes."
          ]
        },
      • {
        • "module": "Vhosts",
        • "restricted_available": 1,
        • "summary": [
          • "This module installs the web server configuration and restarts the web server."
          ]
        },
      • {
        • "module": "WebCalls",
        • "restricted_available": 1,
        • "summary": [
          • "This module restores the account’s web call data."
          ]
        },
      • {
        • "module": "WebDiskHomedir",
        • "restricted_available": 1,
        • "summary": [
          • "This rewrites web disk home directories to the correct location on the new server."
          ]
        },
      • {
        • "module": "ZoneFile",
        • "restricted_available": 1,
        • "summary": [
          • "This restores custom DNS (Domain Name System) Zone entries."
          ]
        },
      • {
        • "module": "userdata",
        • "restricted_available": 1,
        • "restricted_summary": [
          • "Restricted Restore does not restore the entire userdata file; instead, the system will create a new one and copy in certain information. Customizations to the userdata file in the archive will not be in the newly-created userdata file."
          ],
        • "summary": [
          • "This restores website configuration (userdata)."
          ]
        }
      ]
    },
  • "metadata": {
    • "command": "restore_modules_summary",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Account Creation

Accounts / Account Creation

Validate new cPanel account username

This function checks for username conflicts during account creation.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=username

The account that you wish to create.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_new_username \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "verify_new_username",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel accounts total number

This function returns the number of cPanel accounts on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_current_users_count

Response samples

Content type
application/json
{
  • "data": {
    • "users": 100
    },
  • "metadata": {
    • "command": "get_current_users_count",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return maximum accounts for license

This function returns the maximum number of cPanel accounts that the server's license allows.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_maximum_users

Response samples

Content type
application/json
{
  • "data": {
    • "users": 100
    },
  • "metadata": {
    • "command": "get_maximum_users",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create cPanel account

This function creates a cPanel account and sets up its domain information.

Note:

  • On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.
  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth
query Parameters
string or Array of strings
Examples:
  • account_enhancements=My Custom Enhancement&account_enhancements=Sample Enhancement - Assign multiple enhancements
  • account_enhancements=My Custom Enhancement - Assign one enhancement

Assign Account Enhancements to the cPanel account. To view your server's Account Enhancements, run WHM API 1's list_account_enhancements function.

any or string or integer <megabytes>
Example: bwlimit=unlimited

The account's maximum bandwidth.

  • 0, unlimited, or null — The account possesses unlimited bandwidth.
cgi
integer
Default: 1
Possible Values: 1 0
Example: cgi=1

Whether the account has Common Gateway Interface (CGI) access enabled.

  • 1 — Enabled.
  • 0 — Disabled.

Note:

When a server profile disables the Web Server role, this parameter defaults to 0. On these servers, you cannot enable CGI access.

contactemail
string <email>
Default: ""

The account's contact email address.

cpmod
string
Example: cpmod=jupiter

The account's cPanel theme.

Note:

This parameter defaults to the server's default cPanel theme.

customip
string <ipv4>
Example: customip=192.0.2.0

The account's IP address.

Note:

If you do not specify this parameter, the system will determine the account's IP address.

dkim
integer
Possible Values: 0 1
Example: dkim=1

Whether DomainKeys Identified Mail (DKIM) is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

Note:

This parameter defaults to the Enable DKIM on domains for newly created accounts setting's value in WHM's Tweak Settings interface (WHM >> Home >> System Configuration >> Tweak Settings).

dmarc
integer
Possible Values: 0 1
Example: dmarc=1

Whether Domain-based Message Authentication, Reporting, and Conformance (DMARC) is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

Note:

This parameter defaults to the Enable DMARC on domains for newly created accounts setting's value in the Domains section of WHM's Tweak Settings interface (WHM >> Home >> System Configuration >> Tweak Settings).

domain
string
Example: domain=example.com

The account's main domain.

Note:

  • If you do not provide a domain, the system will automatically create a temporary domain for the account.
  • For more information about temporary domains, read our Temporary Domains documentation.
featurelist
string
Default: "default"
Example: featurelist=feature_list

The account's assigned feature list.

forcedns
integer
Default: 0
Possible Values: 0 1
Example: forcedns=0

Whether to overwrite an existing DNS zone with the new account's information. The system performs this action if a matching DNS zone currently exists.

  • 1 — Overwrite.
  • 0 — Do not overwrite.
frontpage
integer or null
Deprecated
Default: null

Whether the account has Microsoft® FrontPage Extensions enabled.

Note:

cPanel & WHM ignores all FrontPage settings and parameters.

gid
integer >= 1
Example: gid=123456789

The account's group ID.

Note:

  • To use this parameter, the function's caller must authenticate as the root user.
  • If you do not specify this parameter, the system generates a group ID.
  • This must be a unique value that is not currently associated with disk usage and does not exist on the server.
hasshell
integer
Default: 0
Possible Values: 0 1
Example: hasshell=0

Whether the account has shell (SSH) access enabled.

  • 1 — Enabled.
  • 0 — Disabled.
hasuseregns
integer
Default: 0
Possible Values: 0 1
Example: hasuseregns=1

A legacy parameter.

  • 1 — Enabled.
  • 0 — Disabled.

Important:

Only include this parameter if you set a useregns value of 1.

homedir
string
Example: homedir=/home/user

The absolute path to the account's home directory.

Note:

  • To use this parameter, the function's caller must authenticate as the root user.
  • If you do not specify a value, the system uses the /home/user directory, where user is the account's username.
ip
string
Default: "n"
Possible Values: "y" "n"
Example: ip=n

Whether the account has a dedicated IP address.

  • y — The account possesses a dedicated IP address.
  • n — The account does not possess a dedicated IP address.
language
string
Example: language=en

The account's default locale.

Note:

  • This value is case-sensitive.
  • For region-specific locales, use the ISO 639-1 code, an underscore (_), and the ISO 3166-1 code.
mail_node_alias
string
Example: mail_node_alias=mailnode

A linked cPanel mail server on which to also create the account. This is the server's alias (friendly name) defined when creating the link to a cPanel mail server.

Note:

This function requires a linked cPanel mail server.

mailbox_format
string
Possible Values: "mdbox" "maildir"
Example: mailbox_format=mdbox

A mailbox format to use, if you do not wish to use the system's default mailbox format.

Note:

  • Use this parameter when you transfer between servers with different mailbox formats.
  • This parameter defaults to the The mailbox storage format for new accounts setting in the Mail section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).
string or integer
Default: "unlimited"
Example: max_defer_fail_percentage=unlimited

The percentage of failed or deferred email messages that the account can send per hour. If the account exceeds this value its outgoing mail is rate-limited.

  • 0 or unlimited — The account can send an unlimited number of failed or deferred messages.
string or integer
Example: max_email_per_hour=unlimited

The maximum number of emails that the account can send in one hour.

  • 0 or unlimited — The account can send an unlimited number of emails.
string or integer <megabytes>
Default: 1024
Example: max_emailacct_quota=1024

The maximum size that the account can define when it creates an email account.

  • 0 or unlimited — The account possesses an unlimited quota.

Important:

  • This value applies to each email account, not each cPanel account.
  • If you define this parameter it overwrites the hosting plan's defined value for the account.
  • We recommend that you allow the account's plan to determine this value.
max_team_users
integer [ 0 .. 7 ]
Example: max_team_users=7

The maximum number of Team users for this account. This parameter should be a number between 0 and the server's default value, inclusively. This parameter can not be a number greater than the server's default value.

any or string or integer
Default: 0
Example: maxaddon=unlimited

The account's maximum number of addon domains.

  • unlimited, or null — The account possesses unlimited addon domains.
any or string or integer
Example: maxftp=unlimited

The account's maximum number of FTP accounts.

  • 0, unlimited, or null — The account possesses unlimited FTP accounts.
any or string or integer
Example: maxlst=unlimited

The account's maximum number of mailing lists.

  • 0, unlimited, or null — The account possesses unlimited mailing lists.
any or string or integer
Default: 0
Example: maxpark=unlimited

The account's maximum number of parked domains (aliases).

  • unlimited or null — The account possesses unlimited parked domains.
any or string or integer
Example: maxpop=unlimited

The account's maximum number of email accounts.

  • 0, unlimited, or null — The account possesses unlimited email accounts.
any or string or integer
Example: maxsql=unlimited

The account's maximum number of each available type of SQL database. For example, this parameter has a 5 value and the system administrator allows MySQL® and PostgreSQL® databases. Users can create up to five MySQL databases and up to five PostgreSQL databases.

  • 0, unlimited, or null — The account possesses unlimited databases.
any or string or integer
Example: maxsub=unlimited

The account's maximum number of subdomains. unlimited or null — The account possesses unlimited subdomains.

mxcheck
string
Default: "local"
Possible Values: "local" "secondary" "remote" "auto"
Example: mxcheck=auto

The account's main mail exchanger's type.

  • local - Local Mail Exchanger.
  • secondary - Backup Mail Exchanger.
  • remote - Remote Mail Exchanger.
  • auto - Automatically Detect Configuration.

Note:

The function does not configure the primary MX entry to point to the appropriate exchanger. You must perform this function separately.

owner
string
Example: owner=root

The name of the account owner.

  • root
  • A valid reseller account username on the server.
ownerself
integer
Default: 0
Possible Values: 0 1
Example: ownerself=1

Set the account to own itself. Ignored if owner is set.

  • 1 — Set account to own itself.
  • 0 — Do nothing.
pass
string
Example: pass=123456luggage

The account's password.

Note:

  • You can use either the pass or the password parameter, but not both.
  • If you don't specify this value, the system generates a secure password.
password
string
Example: password=123456luggage

The account's password.

Note:

  • You can use either the pass or the password parameter, but not both.
  • If you don't specify this value, the system generates a secure password.
pkgname
string
Example: pkgname=my_new_package

A new plan name. Use this parameter to save unique account settings as a new plan.

Note:

  • If you do not use this parameter but specify 1 for the savepkg value, the system will generate a plan name.
  • If you do not use this parameter and specify 0 or do not use the savepkg parameter, the function does not save a new plan.
  • If you do not use this parameter, the function will not save the new account settings.
plan
string
Default: "default"
Example: plan=default

The account's hosting plan (package).

Important:

If you provide this value, do not use the optional quota-related parameters below. Instead, we recommend that you allow the account's plan to determine these values.

quota
integer <megabytes> [ 0 .. 999999 ]
Default: 0
Example: quota=500

The account's disk space quota.

  • 0 — The account's disk space is unlimited.
reseller
integer
Default: 0
Possible Values: 0 1
Example: reseller=0

Whether to grant reseller privileges to the account.

  • 1 — Grant reseller privileges.
  • 0 — Do not grant reseller privileges.
reseller_without_domain
integer
Default: 0
Possible Values: 0 1
Example: reseller_without_domain=0

Create the user as a reseller without an associated domain.

  • 1 - Create the account as a reseller without an associated domain.
  • 0 - Do not create the account as a reseller without an associated domain.

Warning:

If you create a reseller without a domain, certain parts of WHM will not function for that user. These limitations exist both when logged in as that user and when you attempt to perform actions which affect that user.

savepkg
integer
Default: 0
Possible Values: 0 1
Example: savepkg=1

Whether to save the account's settings as a new plan.

  • 1 — Save.
  • 0 — Do not save.
showpass
string
Default: "y"
Possible Values: "y" "n"
Example: showpass=n

Whether to display the account password in the output.

  • y — Display the account password in the output.
  • n — Do NOT display the account password in the output.
spamassassin
integer
Default: 1
Possible Values: 0 1
Example: spamassassin=1

Whether the account has Apache SpamAssassin™ enabled.

  • 1 — Enabled.
  • 0 — Disabled.
spambox
string
Default: "y"
Possible Values: "y" "n"
Example: spambox=y

Whether to enable spam box filtering for the account.

  • y - Enable spam box filtering.
  • n - Disable spam box filtering. Note:

You must enable Apache SpamAssassin™ to use the Spam Box feature.

spf
integer
Possible Values: 0 1
Example: spf=1

Whether Sender Policy Framework (SPF) is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the Enable SPF on domains for newly created accounts setting's value in WHM's Tweak Settings interface (WHM >> Home >> System Configuration >> Tweak Settings).

uid
integer >= 0
Example: uid=123456789

The account's user ID.

Note:

  • To use this parameter, the function's caller must authenticate as the root user.
  • If you do not specify this parameter, the system generates a user ID.
  • This must be a unique value that is not currently associated with disk usage and does not exist on the server.
useregns
integer
Default: 0
Possible Values: 0 1
Example: useregns=0

Whether to use registered nameservers for the domain.

  • 1 - Use registered nameservers.
  • 0 - Use the server's default nameservers.

Important:

If you set this parameter to 1, you must also include the hasuseregns parameter with a value of 1.

username
required
string <= 16 characters
Example: username=username

The new account's username. cPanel usernames must adhere to the following criteria:

  • The first eight characters of a username must be unique.
  • A username cannot begin with a number or the test string.

Note:

  • Use the Cpanel::Validate::Username Perl module to validate usernames before you call this function. For more information, read the /usr/local/cpanel/Cpanel/Validate/Username.pod file.
  • The system will automatically convert this value to all lowercase letters.
  • MySQL's unique character limitations do not exist on servers that use MariaDB.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  createacct \
  username='username' \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "192.0.2.0",
    • "nameserver": "ns1.example.com",
    • "nameserver2": "ns2.example.com",
    • "nameserver3": "ns3.example.com",
    • "nameserver4": "ns4.example.com",
    • "nameservera": "192.0.2.1",
    • "nameservera2": "192.0.2.2",
    • "nameservera3": "192.0.2.3",
    • "nameservera4": "192.0.2.4",
    • "nameserverentry": "dnsentry1",
    • "nameserverentry2": "dnsentry2",
    • "nameserverentry3": "dnsentry3",
    • "nameserverentry4": "dnsentry4",
    • "package": "my_new_package"
    },
  • "metadata": {
    • "command": "createacct",
    • "output": {
      • "raw": "Checking input data...Forced Dns is enabled.\\nValidating Username......Done\\nValidating IP......Done\\nValidating Contact Email......Done\\n...Done\\nValidating system setup......Done\\nChecking for database conflicts......Done\\nWWWAcct 12.6.0 (c) 2024 WebPros International, LLC...\\n\\n+===================================+\\n| New Account Info |\\n+===================================+\\n| Domain: example.com\\n| Ip: 192.0.2.0 (n)\\n| HasCgi: y\\n| UserName: username\\n| PassWord: 123456luggage\\n| CpanelMod: jupiter\\n| HomeRoot: /home\\n| Quota: 1 GB\\n| NameServer1: ns1.example.com\\n| NameServer2: ns2.example.com\\n| NameServer3:\\n| NameServer4:\\n| Contact Email: [email protected]\\n| Package: my_new_package\\n| Feature List: feature_list\\n| Language: en\\n+===================================+\\n...Done\\nCustom Account Data Provided: no\\nRunning pre creation script (/usr/local/cpanel/scripts/prewwwacct)......Done\\nAdding User...Removing Shell Access (n)\\nSuccess...Done\\nAdding Entries to userdata......Done\\nSetting up Mail & Local Domains...localdomains...valiases ...vdomainaliases ...vfilters ......Done\\nConfiguring DNS...Zone example.com has been successfully added\\n...Done\\nVerifying MX Records and Setting up Databases...Reconfiguring Mail Routing:\\nLOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.:\\n This configuration has been automatically detected based on your mx entries.\\n\\n...Done\\nSetting up Service Subdomains......Done\\nUpdating Authentication Databases......Done\\nSetting passwords......Done\\nUpdating the userdata cache......Done\\n\\nCreating bandwidth datastore......Done\\nUpdating the dedicated IP address usage cache......Done\\nGenerating and installing DKIM keys......Done\\nEnabling Apache SpamAssassin......Done\\nEnabling Apache SpamAssassin Spam Box......Done\\nSending Account Information......Done\\nRunning post creation scripts (/usr/local/cpanel/scripts/legacypostwwwacct, /usr/local/cpanel/scripts/postwwwacct, /usr/local/cpanel/scripts/postwwwacctuser)......Done\\nwwwacct creation finished\\nAccount Creation Complete!!!...Account Creation Ok...Done\\n"
      },
    • "reason": "Account Creation Ok",
    • "result": 1,
    • "version": 1
    }
}

Account Enhancements

The Account Enhancements module for WHM.

Return Account Enhancements

This function retrieves all existing account enhancements on the system.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_account_enhancements

Response samples

Content type
application/json
{
  • "data": {
    • "enhancements": {
      • "id": "sample-enhancement-id",
      • "name": "Sample Enhancement"
      }
    },
  • "metadata": {
    • "command": "list_account_enhancements",
    • "output": {
      • "warnings": [
        • "(XID svx4zp) The enhancement file “/var/cpanel/account_enhancements/enhancement 5000.json” contains an invalid enhancement “id”: “bad-id”."
        ]
      },
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create Account Enhancement

This function creates a new account enhancement.

Authorizations:
BasicAuth
query Parameters
id
required
string
Example: id=sample-enhancement-id

The identifier of the item you are targeting.

Note:

  • You must use an account enhancements ID that a 3rd-party plugin defines.
  • To return a list of valid account enhancement IDs, run the WHM API 1 list_account_enhancements function.
name
required
string <= 80 characters
Example: name=featurename 5000

The name of the account enhancement.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_account_enhancement \
  name='featurename 5000' \
  id='sample-enhancement-id'

Response samples

Content type
application/json
{
  • "data": {
    • "name": "featurename 5000"
    },
  • "metadata": {
    • "command": "create_account_enhancement",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove an Account Enhancement

This function removes an account enhancement.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=enhancement 5000

The name of the account enhancement.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_account_enhancement \
  name='enhancement 5000'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "delete_account_enhancement",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Account Enhancement

This function modifies an account enhancement.

Important:

  • When you call this function, you must include at least one of the id or name parameters. Lack of a second parameter will result in no change.
Authorizations:
BasicAuth
query Parameters
id
string
Example: id=sample-enhancement-id

The account enhancement's new identifier.

Note:

  • You must use an account enhancements ID that a 3rd-party plugin defines.
  • To return a list of valid account enhancement IDs, run the WHM API 1 list_account_enhancements function.
name
required
string
Example: name=enhancement 5000

The name of the account enhancement.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modify_account_enhancement \
  name='enhancement 5000' \
  id='sample-enhancement-id'

Response samples

Content type
application/json
{
  • "data": {
    • "id": "sample-enhancement-id",
    • "name": "Sample Enhancement"
    },
  • "metadata": {
    • "command": "modify_account_enhancement",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Unassign Account Enhancement

This function removes an Account Enhancement from a cPanel account.

Authorizations:
BasicAuth
query Parameters
account
required
string <username>
Example: account=username

The username of the account.

name
required
string
Example: name=enhancement 5000

The name of the account enhancement.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  unassign_account_enhancement \
  account='username' \
  name='enhancement 5000'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "unassign_account_enhancement",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Assign Account Enhancement

This function assigns an Account Enhancement to a cPanel account.

Authorizations:
BasicAuth
query Parameters
account
required
string <username>
Example: account=username

The username of the account.

name
required
string
Example: name=enhancement 5000

The name of the account enhancement.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  assign_account_enhancement \
  account='username' \
  name='enhancement 5000'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "assign_account_enhancement",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Account Management

Accounts / Account Management

Remove UID or GID from tracked list

This function removes a user identification number (UID) or group identification number (GID) from the tracked ID list.

Authorizations:
BasicAuth
query Parameters
check_exists
integer
Default: 1
Possible Values: 0 1
Example: check_exists=1

Whether to prevent removal of user or group IDs currently in use.

  • 1 — Prevent removal.
  • 0 — Do not prevent removal.
check_quota
integer
Default: 1
Possible Values: 0 1
Example: check_quota=1

Whether to prevent removal of the user ID if the quota system tracks associated files.

  • 1 — Prevent removal.
  • 0 — Do not prevent removal.

Note:

  • This parameter only applies to user IDs and not group IDs.
  • You cannot check filesystems if the quota system does not track them.
protect_system
integer
Default: 1
Possible Values: 0 1
Example: protect_system=1

Whether to prevent removal of system user or group IDs.

  • 1 — Prevent removal.
  • 0 — Do not prevent removal.
uid or gid
required
integer
Example: uid or gid=1012

The user or group ID to remove from the track list.

Note:

You must include the uid parameter, the gid parameter, or both.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  untrack_acct_id \
  uid or gid='1012'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "untrack_acct_id",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return data from NVData file

This function retrieves the data from an NVData file on disk. cPanel NVData is a per-account configuration storage mechanism that you can use to maintain persistent cPanel & WHM settings across multiple sessions. This includes custom settings for your own themes.

Note:

You can only call this function as a JSON request. For more information about additional output options, run the whmapi1 --help command.

Authorizations:
BasicAuth
Request Body schema: application/json
required
names
Array of strings or null <= 2048 characters

A list of NVData keys stored on the server.

Note:

If you did not set a value for the requested keys, the system returns a null value.

store
string <= 128 characters

The name under which the values are stored.

Responses

Response Schema: application/json
object
object

Request samples

Content type
application/json
{
  • "names": [
    • "milk",
    • "coffee"
    ],
  • "store": "beverages"
}

Response samples

Content type
application/json
{
  • "data": {
    • "personalization": {
      • "coffee": {
        • "reason": "OK",
        • "success": 1,
        • "value": "hot"
        },
      • "milk": {
        • "reason": "OK",
        • "success": 1,
        • "value": "cold"
        }
      }
    },
  • "metadata": {
    • "command": "personalization_get",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Save data to NVData file

This function is used to save personalization data for a WHM user to a datastore on disk.

We call this system cPanel NVData.

cPanel NVData is a per-login configuration storage mechanism that you can use to maintain persistent user interface settings across multiple sessions.

This includes custom settings for your own themes and plugins.

This function is used to save personalzation data for WHM users only. If you want to save personalization data for cPanel users, use the UAPI function personalization_set.

Authorizations:
BasicAuth
Request Body schema: application/json
api.version
required
integer
Value: 1

The WHM API version number

personalization
required
object

An object you want to store.

store
string <= 128 characters

The name under which the values will be stored.

Responses

Response Schema: application/json
object
object

Request samples

Content type
application/json
{
  • "api.version": 1,
  • "personalization": {
    • "coffee": "hot",
    • "milk": "cold"
    },
  • "store": "beverages"
}

Response samples

Content type
application/json
{
  • "data": {
    • "personalization": {
      • "coffee": {
        • "reason": "OK",
        • "success": 1,
        • "value": "hot"
        },
      • "milk": {
        • "reason": "OK",
        • "success": 1,
        • "value": "cold"
        }
      }
    },
  • "metadata": {
    • "command": "personalization_set",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete cPanel account

This function deletes a cPanel or WHM account.

Authorizations:
BasicAuth
query Parameters
keepdns
integer
Default: 0
Possible Values: 0 1
Example: keepdns=0

Whether to retain the account's DNS entries.

  • 1 — Retain DNS entries.
  • 0 — Delete DNS entries.
user
string
Deprecated
Example: user=username

The account's username.

username
required
string
Example: username=username

The account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  removeacct \
  username='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "removeacct",
    • "output": {
      • "raw": "\"raw\":\"Running pre removal script (/usr/local/cpanel/scripts/prekillacct)......Done\\nCollecting Domain Name and IP...User: example\\nDomain: example.com\\n...Done\\nLocking account and setting shell to nologin...Locking password for user example.\\npasswd: Success\\n...Done\\nKilling all processes owned by user......Done\\nRemoving Sessions.........Done\\nRemoving Suspended Info.........Done\\nCleaning Virtfs.........Done\\nRemoving Web Logs......Done\\nRemoving Bandwidth Files......Done\\nRemoving Email Sending Limits Cache......Done\\nRemoving DKIM keys......Done\\nRemoving Crontab......Done\\nRemoving HTTP Virtual Hosts...Removed the following non-SSL virtual hosts: example.com\\nRemoved the following SSL virtual hosts:\\n...Done\\nRemoving ftp Virtual Hosts......Done\\nRemoving user's web content directory symlinks......Done\\nRemoving MySQL databases and users......Done\\nRemoving PostgreSQL databases and users......Done\\nRemoving User & Group.......Success...Done\\nRemoving DNS Entries...example.com => deleted from hostname. \\n...Done\\nRemoving Email Setup...Removing /etc/valiases/example.com\\n...Done\\nRemoving mailman lists......Done\\nUpdating Databases......Done\\nRemoving bandwidth limits......Done\\nRemoving Counter Data......Done\\nAdding IP back to the IP address pool...System has 2 free ips.\\n...Done\\nRemoving user's cPanel Databases & Updating......Done\\nReloading Services......Done\\nRemoving mail and service configs...\\n...Done\\nSending Contacts......Done\\nUpdating internal databases...Updating ftp passwords for example\\nPurging ftp user example\\nFtp password files updated.\\nFtp vhost passwords synced\\n...Done\\nRunning post removal scripts (/usr/local/cpanel/scripts/legacypostkillacct, /usr/local/cpanel/scripts/postkillacct)......Done\\nAccount Removal Complete!!!...example account removed...Done\\n\""
      },
    • "reason": "example account removed",
    • "result": 1,
    • "version": 1
    }
}

Return home directories list

This function returns all the directories where the system stores users' home directories. It returns them in descending order, based on the current amount of available free disk space for each directory. For example, the first directory the function lists has the most available free disk space.

Note:

Use WHM's Basic WebHost Manager Setup (WHM >> Home >> Server Configuration >> Basic WebHost Manager Setup) to configure where the system will create a new user's home directory.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_homedir_roots

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "path": "/home"
        }
      ]
    },
  • "metadata": {
    • "command": "get_homedir_roots",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate cPanel account Digest Authentication

This function checks whether Digest Authentication is enabled for a cPanel user. Windows® Vista, Windows® 7, and Windows® 8 require Digest Authentication support in order to access Web Disk over an unencrypted connection.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=username

The cPanel account username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  has_digest_auth \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "digestauth": 1
    },
  • "metadata": {
    • "command": "has_digest_auth",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable or disable Digest Authentication

This function enables or disables Digest Authentication for an account. Windows Vista®, Windows® 7, and Windows® 8 requires that you enable Digest Authentication support in order to access your Web Disk over a clear text, unencrypted connection.

Note:

If the server has an SSL certificate that a recognized certificate authority signed and you can make an SSL connection over port 2078, you do not need to enable Digest Authentication.

Authorizations:
BasicAuth
query Parameters
enabledigest or digestauth
required
integer
Possible Values: 0 1
Example: enabledigest or digestauth=1

Whether to enable Digest Authentication for the account.

  • 1 — Enable.
  • 0 — Disable.
password
required
string
Example: password=123456luggage

The account's password.

user
required
string
Example: user=username

The account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_digest_auth \
  user='username' \
  password='123456luggage' \
  enabledigest or digestauth='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_digest_auth",
    • "reason": "Digest Authentication enabled.",
    • "result": 1,
    • "version": 1
    }
}

Validate MySQL Configuration file

This function checks whether a cPanel user's home directory contains a valid .my.cnf file.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=user

The cPanel account username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  has_mycnf_for_cpuser \
  user='user'

Response samples

Content type
application/json
{
  • "data": {
    • "has_mycnf_for_cpuser": 1
    },
  • "metadata": {
    • "command": "has_mycnf_for_cpuser",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel accounts

This function lists the accounts on the server.

Authorizations:
BasicAuth
query Parameters
search
string
Example: search=username

A Perl Compatible Regular Expression (PCRE) that filters the results.

Note:

  • The system matches the PCRE against the searchtype parameter's specified type.
  • If you do not specify a value for both the searchtype and search parameters, the function returns all of the server's accounts.
searchmethod
string
Possible Values: "exact" "regex"
Example: searchmethod=exact

The function's search method.

  • exact - The matched value and the search value must be identical.
  • regex - The matched value must contain the search value.
searchtype
string
Possible Values: "domain" "owner" "user" "ip" "package"
Example: searchtype=domain

The account information to query. If you do not specify a value for both the searchtype and search parameters, the function returns all of the server's accounts.

  • domain - Match domains against the search regular expression.
  • owner - Match the WHM user who owns the account against the search regular expression.
  • user - Match usernames against the search regular expression.
  • ip - Match IP addresses against the search regular expression.
  • package - Match hosting plans (packages) against the search regular expression.
want
string
Example: want=domain,diskused

The returns to include in the output for each account.

If you do not specify a value, the function's output includes all of its returns.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listaccts

Response samples

Content type
application/json
{
  • "data": {
    • "acct": [
      • {
        • "backup": 0,
        • "child_nodes": [
          • {
            • "alias": "nodealias",
            • "workload": "Mail"
            }
          ],
        • "disklimit": "unlimited",
        • "diskused": "14M",
        • "domain": "example.com",
        • "email": "[email protected]",
        • "has_backup": 1,
        • "inodeslimit": "unlimited",
        • "inodesused": 1,
        • "ip": "192.168.0.128",
        • "ipv6": [
          • "0101:ca75:0101:ca75:0101:ca75:0101:ca77"
          ],
        • "is_locked": 0,
        • "is_temporary_domain": 0,
        • "legacy_backup": 0,
        • "mailbox_format": "mdbox",
        • "max_defer_fail_percentage": "unlimited",
        • "max_email_per_hour": "unlimited",
        • "max_emailacct_quota": "unlimited",
        • "maxaddons": "unlimited",
        • "maxftp": "unlimited",
        • "maxlst": "unlimited",
        • "maxparked": "unlimited",
        • "maxpop": "unlimited",
        • "maxsql": "unlimited",
        • "maxsub": "unlimited",
        • "min_defer_fail_to_trigger_protection": "unlimited",
        • "outgoing_mail_hold": 1,
        • "outgoing_mail_suspended": 0,
        • "owner": "root",
        • "partition": "home",
        • "plan": "packagename",
        • "shell": "/bin/bash",
        • "startdate": "13 May 22 16:03",
        • "suspended": 0,
        • "suspendreason": "not suspended",
        • "suspendtime": 1594040856,
        • "temporary": 0,
        • "theme": "jupiter",
        • "uid": 1001,
        • "unix_startdate": 1369256589,
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "listaccts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel account

This function modifies a cPanel account.

Warning:

We strongly recommend that you do not modify a single cPanel account's settings if that cPanel account uses a hosting plan (package). If the package values change, the system will overwrite any of your custom values with the package's new values.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth
query Parameters
account_enhancements
string
Examples:
  • account_enhancements=My Custom Enhancement&account_enhancements=Sample Enhancement - Assign multiple enhancements
  • account_enhancements=My Custom Enhancement - Assign one enhancement

A list of names for Account Enhancements to assign to the cPanel account. To view your server's Account Enhancements, run WHM API 1's list_account_enhancements function.

Warning:

You must provide a complete list of Account Enhancements for the cPanel account. The parameter will add or remove Account Enhancements based on the names that you provide.

BACKUP
integer
Possible Values: 0 1
Example: BACKUP=1

Whether backups are enabled for the cPanel account.

  • 1 — Enable backups.
  • 0 — Disable backups.

This parameter defaults to the defined system value.

Note:

You must have root-level privileges to set this parameter.

string or integer
Example: BWLIMIT=unlimited

The cPanel account's maximum bandwidth use, in bytes.

  • 0 or unlimited — The cPanel account can use unlimited bandwidth.

This parameter defaults to the defined system value.

contactemail
string <email>

The cPanel account's contact email address.

This parameter defaults to the defined system value.

DBOWNER
string
Example: DBOWNER=example

The owner of the cPanel account's MySQL databases.

This parameter defaults to the defined system value.

DISK_BLOCK_LIMIT
integer
Example: DISK_BLOCK_LIMIT=100000000

The number of disk blocks for the cPanel account, in kilobytes (KB).

This parameter defaults to the defined system value.

DNS
string <domain>
Example: DNS=example.com

The cPanel account's main domain.

This parameter is an alias of domain. If you set both the DNS and domain parameters, the DNS parameter will override the domain parameter.

This parameter defaults to the defined system value.

domain
string <domain>
Example: domain=example.com

The cPanel account's main domain.

This parameter is an alias of DNS. If you set both the DNS and domain parameters, the DNS parameter will override the domain parameter.

This parameter defaults to the defined system value.

HASCGI
integer
Possible Values: 0 1
Example: HASCGI=1

Whether CGI access is enabled for the cPanel account.

  • 1 — Enable CGI access.
  • 0 — Disable CGI access.

This parameter defaults to the defined system value.

Note:

When a server profile disables the Web Server role, you cannot enable CGI access.

HASDKIM
integer
Possible Values: 0 1
Example: HASDKIM=1

Whether DKIM is enabled for the cPanel account.

  • 1 — Enable DKIM.
  • 0 — Disable DKIM.

This parameter defaults to the defined system value.

HASDMARC
integer
Possible Values: 0 1
Example: HASDMARC=1

Whether DMARC is enabled for the cPanel account.

  • 1 — Enable DMARC.
  • 0 — Disable DMARC.

This parameter defaults to the defined system value.

HASSHELL
integer
Possible Values: 0 1
Example: HASSHELL=1

Whether shell (SSH) access is enabled for the cPanel account.

  • 1 — Enable shell access.
  • 0 — Disable shell access.

This parameter defaults to the defined system value.

Note:

We strongly recommend that you use the shell parameter to specify a shell for SSH access.

HASSPF
integer
Possible Values: 0 1
Example: HASSPF=1

Whether SPF is enabled for the cPanel account.

  • 1 — Enable SPF.
  • 0 — Disable SPF.

This parameter defaults to the defined system value.

LANG
string
Example: LANG=english-utf8

The cPanel account's display language.

This parameter defaults to the defined system value.

LOCALE
string <ISO-3166-1 (alpha-2)>
Example: LOCALE=en

The cPanel account's default locale, in two-letter ISO-3166 code format.

This parameter defaults to the defined system value.

string or string
Example: mail_node_alias=mailnode

The server that will manage the cPanel account's mail.

  • .local — Make the local server manage the cPanel account’s mail. If the account currently uses a child node for its mail, this will transfer the account’s mail to the local server.

  • The alias (friendly name) of a child node that should manage the cPanel account’s mail.

    When you distribute an account’s mail, the function adds a LINK entry to the /var/cpanel/accounting.log file.

This parameter defaults to the account’s current mail node, or .local if the account’s mail is on the local server.

MAILBOX_FORMAT
string
Possible Values: "maildir" "mbox"
Example: MAILBOX_FORMAT=maildir

The storage format that the cPanel account's mailboxes use.

  • maildir
  • mbox

This parameter defaults to the defined system value.

string or integer (IntPosOrUnlimited)
Example: MAX_DEFER_FAIL_PERCENTAGE=unlimited

The percentage of failed or deferred email messages that the cPanel account can send per hour before outgoing mail is rate-limited.

  • 0 or unlimited — The cPanel account can send an unlimited number of failed or deferred messages.

This parameter defaults to the defined system value.

string or integer (IntPosOrUnlimited)
Example: MAX_EMAIL_PER_HOUR=unlimited

The maximum number of emails that the cPanel account can send in one hour.

  • 0 or unlimited — The cPanel account can send an unlimited number of emails.

This parameter defaults to the defined system value.

string or integer
Example: MAX_EMAILACCT_QUOTA=unlimited

The maximum quota, in megabytes (MB), that the cPanel account can define when it creates an email account.

  • unlimited — The cPanel account can set unlimited quotas.

This parameter defaults to the defined system value, or to unlimited if you do not define either the plan or MAX_EMAILACCT_QUOTA parameters.

Important:

  • This value applies to each email account, not each cPanel account.
  • If you specify a MAX_EMAILACCT_QUOTA value, the function will overwrite the plan's defined value for that cPanel account.
  • We recommend that you allow the cPanel account's plan to determine this value.
max_team_users
integer [ 0 .. 7 ]
Example: max_team_users=7

The maximum number of Team users for this account. This parameter should be a number between 0 and the server's default value, inclusively. This parameter can not be a number greater than the server's default value.

string or integer (Int999999OrUnlimited)
Example: MAXADDON=unlimited

The cPanel account's maximum number of addon domains.

  • 0 or unlimited — The cPanel account can use unlimited addon domains.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXFTP=unlimited

The cPanel account's maximum number of FTP accounts.

  • unlimited — The cPanel account can create unlimited FTP accounts.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXLST=unlimited

The cPanel account's maximum number of mailing lists.

  • 0 or unlimited — The cPanel account can create unlimited mailing lists.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXPARK=unlimited

The cPanel account's maximum number of parked domains (aliases).

  • unlimited — The cPanel account can use unlimited parked domains.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXPASSENGERAPPS=unlimited

The cPanel account's maximum number of Ruby applications.

  • unlimited — The cPanel account can use unlimited Ruby applications.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXPOP=unlimited

The maximum number of email accounts for the cPanel account.

  • unlimited — The cPanel account can create unlimited email accounts.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXSQL=unlimited

The maximum number of each available type of SQL database for the cPanel account. For example, if you set this value to 5 and the system administrator allows MySQL® and PostgreSQL® databases, users can create up to five MySQL databases and up to five PostgreSQL databases.

  • unlimited — The cPanel account can create unlimited databases.

This parameter defaults to the defined system value.

string or integer (Int999999OrUnlimited)
Example: MAXSUB=unlimited

The maximum number of subdomains for the cPanel account.

  • unlimited — The cPanel account can create unlimited subdomains.

This parameter defaults to the defined system value.

modify_firewall
integer
Default: 1
Possible Values: 0 1
Example: modify_firewall=0

Whether to modify the firewall rules as part of the cPanel account modification.

  • 1 — Modify the firewall rules.
  • 0 — Do not modify the firewall rules.

Note:

If you do not set this parameter, the system will modify the firewall based on the Do not make changes to the firewall during cPanel account modification. setting in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

MXCHECK-*
integer

The priority of the cPanel account's primary mail exchanger.

This parameter defaults to the defined system value.

Note:

The parameter name consists of MXCHECK, a hyphen, and the primary domain name of the cPanel account. For example, MXCHECK-example.com=10.

newuser
string <username>
Example: newuser=example1

The cPanel account's new username.

This parameter defaults to the defined system value.

Note:

  • Usernames cannot begin with a number or the string test.
  • Usernames can contain 16 characters or fewer if database prefixes are enabled.
  • The first eight characters of usernames must be unique. MySQL requires this due to potential conflicts with cPanel account transfers. However, this limit requirement does not exist on servers that use MariaDB.
  • If you rename the cPanel account and database prefixing is enabled, you can also use the rename_database_objects parameter.
notify_account_authn_link
integer
Possible Values: 0 1
Example: notify_account_authn_link=0

Whether to send a notification when someone links the cPanel account to an external authentication account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_account_authn_link_notification_disabled
integer
Possible Values: 0 1
Example: notify_account_authn_link_notification_disabled=0

Whether to send a notification when someone disables notifications for external authentication account links.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_expiry
integer
Possible Values: 0 1
Example: notify_autossl_expiry=0

Whether to send a notification when an AutoSSL certificate expires.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_expiry_coverage
integer
Possible Values: 0 1
Example: notify_autossl_expiry_coverage=0

Whether to send a notification AutoSSL cannot renew a certificate because domains that fail Domain Control Validation (DCV) exist on the current certificate.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_renewal
integer
Possible Values: 0 1
Example: notify_autossl_renewal=0

Whether to send a notification when AutoSSL renews a certificate.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_renewal_coverage
integer
Possible Values: 0 1
Example: notify_autossl_renewal_coverage=0

Whether to send a notification when AutoSSL renews a certificate but the new certificate lacks at least one domain that the previous certificate secured.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_contact_address_change
integer
Possible Values: 0 1
Example: notify_contact_address_change=0

Whether to send a notification when someone changes the contact address for the cPanel account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_contact_address_change_notification_disabled
integer
Possible Values: 0 1
Example: notify_contact_address_change_notification_disabled=0

Whether to send a notification when disables the notification for contact address changes.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_disk_limit
integer
Possible Values: 0 1
Example: notify_disk_limit=0

Whether to send a notification when the cPanel account reaches its disk usage limit.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_password_change
integer
Possible Values: 0 1
Example: notify_password_change=0

Whether to send a notification when someone changes the cPanel account's password.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_password_change_notification_disabled
integer
Possible Values: 0 1
Example: notify_password_change_notification_disabled=0

Whether to send a notification when someone disables notifications for password changes.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_ssl_expiry
integer
Possible Values: 0 1
Example: notify_ssl_expiry=0

Whether to send a notification when an SSL certificate on the cPanel account expires.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

OUTGOING_EMAIL_SUSPENDED
integer
Possible Values: 0 1
Example: OUTGOING_EMAIL_SUSPENDED=0

Whether to suspend outgoing email on the cPanel account.

  • 1 — Suspend outgoing email.
  • 0 — Do not suspend outgoing email.

This parameter defaults to the defined system value.

owner
string <username>
Example: owner=reseller_name

A new owner's username or the root user, to change the cPanel account's owner.

This parameter defaults to the defined system value.

Note:

The authenticated user must have root privileges in order to assign the cPanel account to a reseller other than that cPanel account.

PUSHBULLET_ACCESS_TOKEN
string

An access token for the cPanel account's Pushbullet™ notifications.

This parameter defaults to the defined system value.

string or integer (IntPosOrUnlimited)
Example: QUOTA=unlimited

The cPanel account's disk space quota.

  • An integer in multiples of 1,048,576 bytes.
  • 0 or unlimited — The cPanel account's disk space is unlimited.

This parameter defaults to the defined system value.

remove_missing_extensions
string
Default: ""
Example: remove_missing_extensions=packageext1 packageext2

A space-separated list of removed, missing, or uninstalled package extensions.

Warning:

This parameter removes all of the extensions that you list from the _PACKAGE_EXTENSIONS variable in the user file. It will not remove the extensions' variables. For more information, read our Guide to Package Extensions.

rename_database_objects
integer
Default: 1
Possible Values: 0 1
Example: rename_database_objects=0

Whether to rename the cPanel account's database objects to use a new username's database prefix.

  • 1 — Rename the cPanel account's database objects.
  • 0 — Do not rename the cPanel account's database objects.

Warning:

  • The cPanel account owner must update any applications to use the new database object names.
  • Use this parameter carefully, as it may cause confusion for system administrators.

MySQL does not allow you to rename a database. When cPanel & WHM "renames" a database, the system performs the following steps:

  1. The system creates a new database.
  2. The system moves data from the old database to the new database.
  3. The system recreates grants and stored code in the new database.
  4. The system deletes the old database and its grants.

Warning:

  • If any of the first three steps fail, the system returns an error and attempts to restore the database's original state. If the restoration process fails, the API function's error response describes these additional failures.
  • In rare cases, the system creates the second database successfully, but fails to delete the old database or grants. The system treats the rename action as a success; however, the API function returns warnings that describe the failure to delete the old database or grants.

Note:

This parameter only applies to servers that use database prefixing.

reseller
integer
Default: 0
Possible Values: 0 1
Example: reseller=1

Whether to grant reseller privileges to the cPanel account.

  • 1 — Grant reseller privileges.
  • 0 — Do not grant reseller privileges.

Note:

You must have root-level privileges to use this parameter.

RS
string
Example: RS=jupiter

The cPanel account's cPanel theme.

This parameter defaults to the defined system value.

shell
string <path>
Example: shell=/bin/bash

The absolute filepath to the shell's location.

This parameter defaults to the defined system value.

spamassassin
integer
Possible Values: 0 1
Example: spamassassin=0

Whether Apache SpamAssassin™ is enabled for the cPanel account.

This parameter defaults to the defined system value.

STARTDATE
integer <unix_timestamp>
Example: STARTDATE=1549471343

A timestamp to use as the cPanel account's creation date.

This parameter defaults to the defined system value.

Note:

This parameter does not provide user access controls. For example, you cannot modify a cPanel account's date to prevent a user from logging in to the server.

STYLE
string
Example: STYLE=Glass

The cPanel account's cPanel interface theme style.

This parameter defaults to the defined system value.

update_existing_email_account_quotas
integer
Default: 0
Possible Values: 0 1
Example: update_existing_email_account_quotas=1

Whether to update the quota for existing email accounts to match the value of MAX_EMAILACCT_QUOTA setting.

  • 1 — Update quota for existing email accounts.
  • 0 — Do not update quota for existing email accounts.

Important:

To use this parameter, you must also use the MAX_EMAILACCT_QUOTA parameter.

user
required
string <username>
Example: user=example

The cPanel account's current username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modifyacct \
  user='example'

Response samples

Content type
application/json
{
  • "data": {
    • "cpuser": {
      • "BACKUP": "1",
      • "BWLIMIT": "0",
      • "CONTACTEMAIL": "[email protected]",
      • "CONTACTEMAIL2": "",
      • "DBOWNER": "example",
      • "DEADDOMAINS": [ ],
      • "DEMO": "0",
      • "DISK_BLOCK_LIMIT": "0",
      • "DOMAIN": "example.com",
      • "DOMAINS": [
        • "subdomain.example.com"
        ],
      • "FEATURELIST": "default",
      • "HASCGI": "1",
      • "HASDKIM": "1",
      • "HASDMARC": "1",
      • "HASSPF": "1",
      • "HOMEDIRLINKS": [ ],
      • "IP": "172.16.1.13",
      • "LEGACY_BACKUP": "0",
      • "LOCALE": "en",
      • "MAILBOX_FORMAT": "maildir",
      • "MAXADDON": "0",
      • "MAXFTP": "unlimited",
      • "MAXLST": "unlimited",
      • "MAXPARK": "0",
      • "MAXPOP": "unlimited",
      • "MAXSQL": "unlimited",
      • "MAXSUB": "unlimited",
      • "MAX_DEFER_FAIL_PERCENTAGE": "unlimited",
      • "MAX_EMAILACCT_QUOTA": "unlimited",
      • "MAX_EMAIL_PER_HOUR": "unlimited",
      • "MTIME": "1560518791",
      • "MXCHECK-example.com": "0",
      • "OWNER": "example",
      • "PLAN": "default",
      • "PUSHBULLET_ACCESS_TOKEN": "",
      • "RS": "jupiter",
      • "STARTDATE": "1554919365",
      • "USER": "example",
      • "UTF8MAILBOX": "1",
      • "_PACKAGE_EXTENSIONS": "",
      • "__CACHE_DATA_VERSION": "0.81",
      • "modify_firewall": "1",
      • "notify_account_authn_link": "0",
      • "notify_account_authn_link_notification_disabled": "0",
      • "notify_autossl_expiry": "0",
      • "notify_autossl_expiry_coverage": "0",
      • "notify_autossl_renewal_coverage": "0",
      • "notify_autossl_renewal_coverage_reduced": "0",
      • "notify_autossl_renewal_uncovered_domains": "0",
      • "notify_bandwidth_limit": "0",
      • "notify_contact_address_change": "0",
      • "notify_contact_address_change_notification_disabled": "0",
      • "notify_disk_limit": "0",
      • "notify_password_change": "0",
      • "notify_password_change_notification_disabled": "0",
      • "notify_ssl_expiry": "0"
      },
    • "domain": "example.com",
    • "setshell": "/bin/bash",
    • "user": "example1"
    },
  • "metadata": {
    • "command": "modifyacct",
    • "output": {
      • "messages": [
        • "Reseller data updated",
        • "0 rows updated in eximstats sends database.\n0 rows updated in eximstats smtp database.\n0 rows updated in eximstats failures database.\n0 rows updated in eximstats defers database.\n",
        • "Username changed from example to example1",
        • "Restarting apache"
        ],
      • "warnings": [
        • "Changing the cPanel account username from “example” to “example1” requires Digest Authentication to be disabled.",
        • "Use the Web Disk Accounts page in cPanel to re-enable Digest Authentication."
        ]
      },
    • "reason": "Account Modified",
    • "result": 1,
    • "version": 1
    }
}

Update user hosting plan

This function changes a cPanel account's hosting plan (package).

Authorizations:
BasicAuth
query Parameters
pkg
required
string
Example: pkg=package1

The hosting plan's name.

user
required
string <username>
Example: user=username

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  changepackage \
  user='username' \
  pkg='package1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "changepackage",
    • "output": {
      • "raw": "<pre>\nChanging the account bandwidth limit from “0” to “unlimited”.\nChanging Feature List to default\nChanging the maximum email accounts from “unlimited” to “unlimited”.\nChanging the maximum SQL databases from “unlimited” to “unlimited”.\nChanging the maximum FTP accounts from “unlimited” to “unlimited”.\nChanging the maximum mailing lists from “unlimited” to “unlimited”.\nChanging the maximum subdomains from “unlimited” to “unlimited”.\nChanging the maximum email quota from “unlimited” to “unlimited” …\nChanging \"Maximum Hourly Email by Domain Relayed\" from unlimited to unlimited\nChanging \"Maximum percentage of failed or deferred messages a domain may send per hour\" from unlimited to unlimited\nChanging the maximum parked domains from “unlimited” to “0”.\nChanging the maximum addon domains from “unlimited” to “0”.\nRemoving Shell Access\nShell changed\nChanging cPanel theme from jupiter to jupiter\nChanging plan from default to boo\nBandwidth limit (unlimited) is lower than (unlimited) (all limits removed)<br /><blockquote><div style='float:left;'>Enabling...</div><div style='float:left;'>...exampleaddon.com...</div><div style='float:left;'>...exampleaddon.example.com...</div><div style='float:left;'>...example.com...</div><div style='float:left;'>Done</div></blockquote><br /><div class='clearit' style='clear:both; width:80%;'> </div>Setting quota to “unlimited”.\n<span class=\"b2\">Warning, this will not change shared IP accounts to dedicated IP accounts, or the reverse.</span>\n<span class=\"b2\">Warning: Changing a user’s package does not affect their Digest Authentication settings.</span>\n</pre>"
      },
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Get upgrade opportunities

This function lists accounts that could benefit from upgrading to a different package. The listed accounts may be nearing (or exceeding) resource usage thresholds.

Authorizations:
BasicAuth
query Parameters
disk_threshold_blocks
integer >= 0
Default: 2097152
Example: disk_threshold_blocks=8388608

A fixed number of blocks to use as an alternative disk usage threshold.

nearness_fraction
number ( 0 .. 1 )
Default: 0.8
Example: nearness_fraction=0.6

The fraction of 1 at which to consider usage "near".

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_upgrade_opportunities

Response samples

Content type
application/json
{
  • "data": {
    • "upgrade_opportunities": {
      • "property1": {
        • "bw_limit": {
          • "last_month": {
            • "fraction": 0.54,
            • "near": 1,
            • "reached": 1
            },
          • "messages": [
            • "This account has used 54% of its bandwidth quota for this month."
            ],
          • "this_month": {
            • "fraction": 0.54,
            • "near": 1,
            • "reached": 1
            }
          },
        • "disk_usage": {
          • "messages": [
            • "This account has used 94% of its disk quota."
            ],
          • "relative_to_fixed_amount": {
            • "fraction": 0,
            • "near": 0,
            • "reached": 0,
            • "threshold_blocks": 10485760
            },
          • "relative_to_quota": {
            • "fraction": 0,
            • "near": 0,
            • "reached": 0,
            • "threshold_blocks": 10485760
            }
          },
        • "messages": [
          • "This account has used 54% of its bandwidth quota for this month.",
          • "This account has used 94% of its disk quota."
          ]
        },
      • "property2": {
        • "bw_limit": {
          • "last_month": {
            • "fraction": 0.54,
            • "near": 1,
            • "reached": 1
            },
          • "messages": [
            • "This account has used 54% of its bandwidth quota for this month."
            ],
          • "this_month": {
            • "fraction": 0.54,
            • "near": 1,
            • "reached": 1
            }
          },
        • "disk_usage": {
          • "messages": [
            • "This account has used 94% of its disk quota."
            ],
          • "relative_to_fixed_amount": {
            • "fraction": 0,
            • "near": 0,
            • "reached": 0,
            • "threshold_blocks": 10485760
            },
          • "relative_to_quota": {
            • "fraction": 0,
            • "near": 0,
            • "reached": 0,
            • "threshold_blocks": 10485760
            }
          },
        • "messages": [
          • "This account has used 54% of its bandwidth quota for this month.",
          • "This account has used 94% of its disk quota."
          ]
        }
      }
    },
  • "metadata": {
    • "command": "get_upgrade_opportunities",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account system privileges

This function retrieves the current user's Access Control List (ACL) privileges.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  myprivs

Response samples

Content type
application/json
{
  • "data": {
    • "privileges": [
      • {
        • "acct-summary": 0,
        • "add-pkg": 0,
        • "add-pkg-ip": 0,
        • "add-pkg-shell": 0,
        • "all": 0,
        • "allow-addoncreate": 0,
        • "allow-emaillimits-pkgs": 0,
        • "allow-parkedcreate": 0,
        • "allow-shell": 0,
        • "allow-unlimited-bw-pkgs": 0,
        • "allow-unlimited-disk-pkgs": 0,
        • "allow-unlimited-pkgs": 0,
        • "basic-system-info": 0,
        • "basic-whm-functions": 0,
        • "clustering": 0,
        • "cors-proxy-get": 0,
        • "cpanel-api": 0,
        • "cpanel-integration": 0,
        • "create-acct": 0,
        • "create-dns": 0,
        • "create-user-session": 0,
        • "demo-setup": 0,
        • "digest-auth": 0,
        • "edit-account": 0,
        • "edit-dns": 0,
        • "edit-mx": 0,
        • "edit-pkg": 0,
        • "file-restore": 0,
        • "generate-email-config": 0,
        • "kill-acct": 0,
        • "kill-dns": 0,
        • "limit-bandwidth": 0,
        • "list-accts": 0,
        • "list-pkgs": 0,
        • "locale-edit": 0,
        • "mailcheck": 0,
        • "manage-api-tokens": 0,
        • "manage-dns-records": 0,
        • "manage-oidc": 0,
        • "manage-styles": 0,
        • "mysql-info": 0,
        • "news": 0,
        • "ns-config": 0,
        • "park-dns": 0,
        • "passwd": 0,
        • "quota": 0,
        • "rearrange-accts": 0,
        • "resftp": 0,
        • "restart": 0,
        • "show-bandwidth": 0,
        • "ssl": 0,
        • "ssl-buy": 0,
        • "ssl-gencrt": 0,
        • "ssl-info": 0,
        • "stats": 0,
        • "status": 0,
        • "suspend-acct": 0,
        • "thirdparty": 0,
        • "track-email": 0,
        • "upgrade-account": 0,
        • "viewglobalpackages": 0
        }
      ]
    },
  • "metadata": {
    • "command": "myprivs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update multiple cPanel accounts

This function modifies multiple cPanel accounts.

Warning:

  • We strongly recommend that you do not modify a cPanel account's settings if that account uses a hosting plan (package). If the package values change, the system will overwrite any of your custom values with the package's new values.
  • This function uses case-sensitive parameters. You must enter parameters in the correct case format. If you do not, the function will ignore that parameter.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth
query Parameters
BACKUP
any
Possible Values: 1 0
Example: BACKUP=1

Whether backups are enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

Note:

This parameter requires root privileges.

any or string or integer (IntPosNullOrUnlimited)
Example: BWLIMIT=unlimited

The account's maximum bandwidth use, in bytes.

  • 0, null or unlimited — The account can use unlimited bandwidth.

This parameter defaults to the defined system value.

CONTACTEMAIL
string <email>

The account's contact email address.

This parameter defaults to the defined system value.

DBOWNER
string <username>
Example: DBOWNER=example

The owner of the account's MySQL® databases.

This parameter defaults to the defined system value.

DISK_BLOCK_LIMIT
integer >= 1
Example: DISK_BLOCK_LIMIT=100000000

The number of disk blocks for the account, in kilobytes (KB).

This parameter defaults to the defined system value.

HASCGI
integer
Possible Values: 1 0
Example: HASCGI=1

Whether CGI access is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

Note:

When a server profile disables the Web Server role, you cannot enable CGI access.

HASDKIM
integer
Possible Values: 1 0

Whether DomainKeys Identified Mail (DKIM) is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

HASDMARC
integer
Possible Values: 1 0

Whether Domain-based Message Authentication, Reporting, and Conformance (DMARC) is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

HASSHELL
integer
Possible Values: 1 0
Example: HASSHELL=1

Whether shell (SSH) access is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

Note:

We strongly recommend that you use the shell parameter to specify a shell for SSH access.

HASSPF
integer
Possible Values: 1 0
Example: HASSPF=1

Whether Sender Policy Framework (SPF) is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

LANG
string
Example: LANG=english-utf8

The account's display language.

This parameter defaults to the defined system value.

LOCALE
string <ISO-3166-1 (alpha-2)>
Example: LOCALE=en

The account's default locale.

This parameter defaults to the defined system value.

MAILBOX_FORMAT
any
Possible Values: "maildir" "mbox"

The storage format that the account's mailboxes use.

  • maildir
  • mbox

This parameter defaults to the defined system value.

string or integer (IntPosOrUnlimited)
Example: MAX_DEFER_FAIL_PERCENTAGE=unlimited

The percentage of failed or deferred email messages that the account can send per hour before outgoing mail is rate-limited.

  • 0 or unlimited — The account can send an unlimited number of failed or deferred messages.

This parameter defaults to the defined system value.

string or integer (IntPosOrUnlimited)
Example: MAX_EMAIL_PER_HOUR=unlimited

The maximum number of emails that the account can send in one hour.

  • 0 or unlimited — The account can send an unlimited number of emails.

This parameter defaults to the defined system value.

string or integer
Example: MAX_EMAILACCT_QUOTA=unlimited

The maximum size, in megabytes (MB), that the account can define when it creates an email account.

  • unlimited — The account possesses an unlimited quota.

Important:

  • This value applies to each email account, not each cPanel account.
  • If you specify a MAX_EMAILACCT_QUOTA value, the function will overwrite the plan's defined value for that cPanel account.
  • This parameter does not affect any existing email accounts
  • We recommend that you allow the account's plan to determine this value.
  • MAX_EMAIL_PER_HOUR will define to unlimited if you do not define either the plan or MAX_EMAILACCT_QUOTA parameters.

This parameter defaults to the defined system value. It will default to unlimited if you do not define either the plan or MAX_EMAILACCT_QUOTA parameters.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXADDON=unlimited

The account's maximum number of addon domains.

  • 0, null, or unlimited — The account possesses unlimited addon domains.

This parameter defaults to the defined system value.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXFTP=unlimited

The account's maximum number of FTP accounts.

  • null or unlimited — The account possesses unlimited FTP accounts.

This parameter defaults to the defined system value.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXLST=unlimited

The account's maximum number of mailing lists.

  • 0, null, or unlimited — The account possesses unlimited mailing lists.

This parameter defaults to the defined system value.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXPARK=unlimited

The account's maximum number of parked domains (aliases).

  • null or unlimited — The account possesses unlimited mailing lists.

This parameter defaults to the defined system value.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXPASSENGERAPPS=unlimited

The account's maximum number of Ruby applications.

  • null or unlimited — The account possesses unlimited Ruby applications.

This parameter defaults to the defined system value.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXPOP=unlimited

The maximum number of email accounts for the account.

  • null or unlimited — The account possesses unlimited email accounts.

This parameter defaults to the defined system value.

any or string or integer (Int0Max999999NullOrUnlimited)
Example: MAXSQL=unlimited

The maximum number of each available type of SQL database for the account.

For example, if you set this value to 5 and the system administrator allows MySQL® and PostgreSQL® databases, users can create up to five MySQL databases and up to five PostgreSQL databases.

  • null or unlimited — The account possesses unlimited databases.

This parameter defaults to the defined system value.

any or string or integer (Int0-999999NullOrUnlimited)
Example: MAXSUB=unlimited

The maximum number of subdomains for the account.

  • null or unlimited — The account possesses unlimited subdomains.

This parameter defaults to the defined system value.

modify_firewall
integer
Default: 1
Possible Values: 0 1
Example: modify_firewall=0

Whether to modify the firewall rules as part of the account modification.

  • 1 – Modify the firewall rules.
  • 0 – Do not modify the firewall rules.

NOTE:

If you do not set this parameter, the system will modify the firewall based on the Do not make changes to the firewall during account modification. setting in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

MXCHECK-*
integer >= 0
Example: MXCHECK-*=1

The priority of the account's primary mail exchanger.

Note:

The parameter name consists of MXCHECK, a hyphen, and the primary domain of the account.

Example key and value:

  • MXCHECK-example.com=10

This parameter defaults to the define system value.

notify_account_authn_link
integer
Possible Values: 1 0
Example: notify_account_authn_link=0

Whether to send a notification when someone links the account to an external authentication account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_account_authn_link_notification_disabled
integer
Possible Values: 1 0
Example: notify_account_authn_link_notification_disabled=0

Whether to send a notification when someone disables notifications for external authentication account links.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_expiry
integer
Possible Values: 1 0
Example: notify_autossl_expiry=0

Whether to send a notification when an AutoSSL certificate expires.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_expiry_coverage
integer
Possible Values: 1 0
Example: notify_autossl_expiry_coverage=0

Whether to send a notification AutoSSL cannot renew a certificate because domains that fail Domain Control Validation (DCV) exist on the current certificate.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_renewal
integer
Possible Values: 1 0
Example: notify_autossl_renewal=0

Whether to send a notification when AutoSSL renews a certificate.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_autossl_renewal_coverage
integer
Possible Values: 1 0
Example: notify_autossl_renewal_coverage=0

Whether to send a notification when AutoSSL renews a certificate but the new certificate lacks at least one domain that the previous certificate secured.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_contact_address_change
integer
Possible Values: 1 0
Example: notify_contact_address_change=0

Whether to send a notification when someone changes the contact address for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_contact_address_change_notification_disabled
integer
Possible Values: 1 0
Example: notify_contact_address_change_notification_disabled=0

Whether to send a notification when disables the notification for contact address changes.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_disk_limit
integer
Possible Values: 1 0
Example: notify_disk_limit=0

Whether to send a notification when the account reaches its disk usage limit.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_password_change
integer
Possible Values: 1 0
Example: notify_password_change=0

Whether to send a notification when someone changes the account's password.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_password_change_notification_disabled
integer
Possible Values: 1 0
Example: notify_password_change_notification_disabled=0

Whether to send a notification when someone disables notifications for password changes.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

notify_ssl_expiry
integer
Possible Values: 1 0
Example: notify_ssl_expiry=0

Whether to send a notification when an SSL certificate on the account expires.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

OUTGOING_EMAIL_SUSPENDED
integer
Possible Values: 1 0
Example: OUTGOING_EMAIL_SUSPENDED=0

Whether to suspend outgoing email on the account.

  • 1 — Suspend outgoing email.
  • 0 — Do not suspend outgoing email.

This parameter defaults to the defined system value.

OWNER
string <username>
Example: OWNER=reseller

A new owner's username or the root user, to change the account's owner.

This parameter defaults to the defined system value.

Note:

The authenticated user must have root privileges in order to assign the account to a reseller other than that account.

PUSHBULLET_ACCESS_TOKEN
string
Example: PUSHBULLET_ACCESS_TOKEN=1234567890

An access token for the account's Pushbullet™ notifications.

This parameter defaults to the defined system value.

any or string or integer (IntPosNullOrUnlimited)
Example: QUOTA=unlimited

The account's disk space quota, in multiples of 1,048,576 bytes.

  • 0, null, or unlimited — The account's disk space is unlimited.

This parameter defaults to the defined system value.

remove_missing_extensions
string
Example: remove_missing_extensions=packageext1 packageext2

A space-separated list of removed, missing, or uninstalled extensions.

This parameter defaults to the defined system value.

Warning:

This parameter removes all of the extensions that you list from the _PACKAGE_EXTENSIONS variable in the user file. It will not remove the extensions' variables. For more information, read our Guide to Package Extensions.

rename_database_objects
integer
Possible Values: 1 0
Example: rename_database_objects=0

Whether to rename the cPanel account's database objects to use a new username's database prefix. This parameter only applies to servers that use database prefixing.

  • 1 — Rename the cPanel account's database objects.
  • 0 — Do not rename the cPanel account's database objects.

Warning:

  • The account owner must update any applications to use the new database object names.
  • Use this parameter carefully. It can cause confusion for system administrators.

MySQL does not allow you to rename a database. When cPanel & WHM "renames" a database, the system performs the following steps:

  1. The system creates a new database.
  2. The system moves data from the old database to the new database.
  3. The system recreates grants and stored code in the new database.
  4. The system deletes the old database and its grants.

Warning:

  • If any of the first three steps fail, the system returns an error and attempts to restore the database's original state. If the restoration process fails, the API function's error response describes these additional failures.
  • In rare cases, the system creates the second database successfully, but fails to delete the old database or grants. The system treats the rename action as a success; however, the API function returns warnings that describe the failure to delete the old database or grants.
reseller
integer
Default: 0
Possible Values: 1 0
Example: reseller=1

Whether to grant reseller privileges to the account.

  • 1 — Grant reseller privileges.
  • 0 — Do not grant reseller privileges.
RS
string
Example: RS=jupiter

The account's cPanel interface theme.

This parameter defaults to the defined system value.

shell
string <path>
Example: shell=/bin/bash

The absolute file path to the shell's location.

This parameter defaults to the defined system value.

spamassassin
integer
Possible Values: 1 0
Example: spamassassin=1

Whether Apache SpamAssassin™ is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

This parameter defaults to the defined system value.

STARTDATE
integer <unix_timestamp>
Example: STARTDATE=1549471343

A timestamp for which to use as the account's creation date.

This parameter defaults to the defined system value.

STYLE
string
Example: STYLE=Glass

The account's cPanel interface style.

This parameter defaults to the defined system value.

user
required
string <username>
Examples:
  • user=user-0=username user-1=username1 user-2=username2 user-3=username3 - Modify multiple users.
  • user=user=username user=username1 user=username2 user=username3 - Modify multiple users.
  • user=username - Modify a single user.

The account's current username.

Note:

To modify multiple users, duplicate or increment the parameter name. For example, the user-1, user-2, and user-3 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  massmodifyacct \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "reason": "Unable to fetch the cPanel user file for username",
        • "result": 0,
        • "user": "username"
        },
      • {
        • "extended": {
          • "cpuser": {
            • "BACKUP": "1",
            • "BWLIMIT": "unlimited",
            • "CONTACTEMAIL": "[email protected]",
            • "CONTACTEMAIL2": "",
            • "DBOWNER": "username1",
            • "DEADDOMAINS": [
              • "example.example1.com"
              ],
            • "DEMO": "0",
            • "DISK_BLOCK_LIMIT": 0,
            • "DOMAIN": "example1.com",
            • "DOMAINS": [ ],
            • "FEATURELIST": "default",
            • "HASCGI": "1",
            • "HASDKIM": "1",
            • "HASDMARC": "1",
            • "HASSPF": "1",
            • "HOMEDIRLINKS": [ ],
            • "IP": "172.16.1.3",
            • "LANG": "english-utf8",
            • "LEGACY_BACKUP": "0",
            • "LOCALE": "en",
            • "MAILBOX_FORMAT": "maildir",
            • "MAXADDON": "0",
            • "MAXFTP": "234",
            • "MAXLST": "unlimited",
            • "MAXPARK": "0",
            • "MAXPOP": "123",
            • "MAXSQL": "345",
            • "MAXSUB": "unlimited",
            • "MAX_DEFER_FAIL_PERCENTAGE": "unlimited",
            • "MAX_EMAILACCT_QUOTA": "unlimited",
            • "MAX_EMAIL_PER_HOUR": "unlimited",
            • "MTIME": "1584509675",
            • "MXCHECK-example1.com": "remote",
            • "OWNER": "username1",
            • "PLAN": "extended",
            • "RS": "jupiter",
            • "STARTDATE": "765435600",
            • "USER": "username1",
            • "UTF8MAILBOX": "1",
            • "WORKER_NODE-Mail": "example1:6L3ZJZ8LPAAOMC8CA31325O8EKGJ5YV5",
            • "_PACKAGE_EXTENSIONS": "custom",
            • "__CACHE_DATA_VERSION": "0.81"
            },
          • "domain": "example1.com",
          • "setshell": "unmodified",
          • "user": "username1"
          },
        • "messages": [ ],
        • "reason": "Account Modified",
        • "result": 1,
        • "user": "username1",
        • "warnings": [ ]
        },
      • {
        • "extended": {
          • "cpuser": {
            • "BACKUP": "1",
            • "BWLIMIT": "unlimited",
            • "CONTACTEMAIL": "",
            • "CONTACTEMAIL2": "",
            • "DBOWNER": "username2",
            • "DEADDOMAINS": [ ],
            • "DEMO": "0",
            • "DISK_BLOCK_LIMIT": 0,
            • "DOMAIN": "example2.com",
            • "DOMAINS": [ ],
            • "FEATURELIST": "default",
            • "HASCGI": "0",
            • "HASDKIM": "1",
            • "HASDMARC": "1",
            • "HASSPF": "1",
            • "HOMEDIRLINKS": [ ],
            • "IP": "10.0.0.1",
            • "LANG": null,
            • "LEGACY_BACKUP": "0",
            • "LOCALE": "cs",
            • "MAILBOX_FORMAT": "maildir",
            • "MAXADDON": "0",
            • "MAXFTP": "234",
            • "MAXLST": "unlimited",
            • "MAXPARK": "0",
            • "MAXPOP": "123",
            • "MAXSQL": "345",
            • "MAXSUB": "unlimited",
            • "MAX_DEFER_FAIL_PERCENTAGE": "unlimited",
            • "MAX_EMAILACCT_QUOTA": "unlimited",
            • "MAX_EMAIL_PER_HOUR": "unlimited",
            • "MTIME": "1583966719",
            • "MXCHECK-example2.com": "0",
            • "OWNER": "root",
            • "PLAN": "extended",
            • "RS": "jupiter",
            • "STARTDATE": "728719200",
            • "USER": "username2",
            • "UTF8MAILBOX": "1",
            • "WORKER_NODE-Mail": "example2:BXE4LIAXF4X9N0B0TG69AAQ64DGR1XPU",
            • "_PACKAGE_EXTENSIONS": "",
            • "__CACHE_DATA_VERSION": "0.81"
            },
          • "domain": "example2.com",
          • "setshell": "unmodified",
          • "user": "username2"
          },
        • "messages": [ ],
        • "proxied_from": [
          • "example.com"
          ],
        • "reason": "Account Modified",
        • "result": 1,
        • "user": "username2",
        • "warnings": [ ]
        },
      • {
        • "extended": {
          • "cpuser": {
            • "BACKUP": "1",
            • "BWLIMIT": "unlimited",
            • "CONTACTEMAIL": "",
            • "CONTACTEMAIL2": "",
            • "DBOWNER": "username2",
            • "DEADDOMAINS": [ ],
            • "DEMO": 0,
            • "DISK_BLOCK_LIMIT": 0,
            • "DOMAIN": "example2.com",
            • "DOMAINS": [ ],
            • "FEATURELIST": "default",
            • "HASCGI": "1",
            • "HASDKIM": "1",
            • "HASDMARC": "1",
            • "HASSPF": "1",
            • "HOMEDIRLINKS": [ ],
            • "IP": "172.16.1.3",
            • "LANG": "english-utf8",
            • "LEGACY_BACKUP": "0",
            • "LOCALE": "en",
            • "MAILBOX_FORMAT": "maildir",
            • "MAXADDON": "unlimited",
            • "MAXFTP": "234",
            • "MAXLST": "unlimited",
            • "MAXPARK": "unlimited",
            • "MAXPOP": "123",
            • "MAXSQL": "345",
            • "MAXSUB": "unlimited",
            • "MAX_DEFER_FAIL_PERCENTAGE": "unlimited",
            • "MAX_EMAILACCT_QUOTA": "unlimited",
            • "MAX_EMAIL_PER_HOUR": "unlimited",
            • "MTIME": "1584509675",
            • "MXCHECK-example2.com": "remote",
            • "OWNER": "username2",
            • "PLAN": "default",
            • "RS": "jupiter",
            • "STARTDATE": "765435600",
            • "USER": "username2",
            • "UTF8MAILBOX": "1",
            • "WORKER_NODE-Mail": "example2:H99IZWY3OH9Q1DQNR58L55WUBXAENPDP",
            • "_PACKAGE_EXTENSIONS": "",
            • "__CACHE_DATA_VERSION": "0.81"
            },
          • "domain": "example2.com",
          • "setshell": "unmodified",
          • "user": "username2"
          },
        • "messages": [ ],
        • "reason": "Account Modified",
        • "result": 1,
        • "user": "username2",
        • "warnings": [ ]
        },
      • {
        • "extended": {
          • "cpuser": {
            • "BACKUP": "1",
            • "BWLIMIT": "unlimited",
            • "CONTACTEMAIL": "",
            • "CONTACTEMAIL2": "",
            • "DBOWNER": "username2",
            • "DEADDOMAINS": [ ],
            • "DEMO": 0,
            • "DISK_BLOCK_LIMIT": 0,
            • "DOMAIN": "example2.com",
            • "DOMAINS": [ ],
            • "FEATURELIST": "default",
            • "HASCGI": "0",
            • "HASDKIM": "1",
            • "HASDMARC": "1",
            • "HASSPF": "1",
            • "HOMEDIRLINKS": [ ],
            • "IP": "10.0.0.2",
            • "LANG": "english-utf8",
            • "LEGACY_BACKUP": "0",
            • "LOCALE": "en",
            • "MAILBOX_FORMAT": "maildir",
            • "MAXADDON": "unlimited",
            • "MAXFTP": "234",
            • "MAXLST": "unlimited",
            • "MAXPARK": "unlimited",
            • "MAXPOP": "123",
            • "MAXSQL": "345",
            • "MAXSUB": "unlimited",
            • "MAX_DEFER_FAIL_PERCENTAGE": "unlimited",
            • "MAX_EMAILACCT_QUOTA": "unlimited",
            • "MAX_EMAIL_PER_HOUR": "unlimited",
            • "MTIME": "1583966717",
            • "MXCHECK-example2.com": "0",
            • "OWNER": "linked",
            • "PLAN": "default",
            • "RS": "jupiter",
            • "STARTDATE": "765435600",
            • "USER": "username2",
            • "UTF8MAILBOX": "1",
            • "_PACKAGE_EXTENSIONS": "",
            • "__CACHE_DATA_VERSION": "0.81"
            },
          • "domain": "example2.com",
          • "setshell": "noshell",
          • "user": "username2"
          },
        • "messages": [
          • "Shell changed"
          ],
        • "proxied_from": [
          • "example.com"
          ],
        • "reason": "Account Modified",
        • "result": 1,
        • "user": "username2",
        • "warnings": [ ]
        }
      ]
    },
  • "metadata": {
    • "command": "massmodifyacct",
    • "messages": [
      • "From example1.com: Restarting apache"
      ],
    • "reason": "Failed to modify one or more users.",
    • "result": 0,
    • "version": 1,
    • "warnings": [ ]
    }
}

Return root and cPanel accounts

This function lists the cPanel user accounts and the root user on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_users

Response samples

Content type
application/json
{
  • "data": {
    • "users": [
      • "example",
      • "root"
      ]
    },
  • "metadata": {
    • "command": "list_users",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account summary

This function retrieves a summary of a user's account.

Note:

You must use either the user or domain parameters.

Authorizations:
BasicAuth
query Parameters
domain
string
Example: domain=example.com

The account's main domain.

user
string
Example: user=username

The account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  accountsummary \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "acct": [
      • {
        • "backup": 0,
        • "child_nodes": [
          • {
            • "alias": "nodealias",
            • "workload": "Mail"
            }
          ],
        • "disklimit": "unlimited",
        • "diskused": "14M",
        • "domain": "example.com",
        • "email": "[email protected]",
        • "inodeslimit": "unlimited",
        • "inodesused": 1,
        • "ip": "192.168.0.128",
        • "ipv6": [
          • "0101:ca75:0101:ca75:0101:ca75:0101:ca77"
          ],
        • "is_locked": 0,
        • "legacy_backup": 0,
        • "mailbox_format": "maildir",
        • "max_defer_fail_percentage": "unlimited",
        • "max_email_per_hour": "unlimited",
        • "max_emailacct_quota": "unlimited",
        • "maxaddons": "unlimited",
        • "maxftp": "unlimited",
        • "maxlst": "unlimited",
        • "maxparked": "unlimited",
        • "maxpop": "unlimited",
        • "maxsql": "unlimited",
        • "maxsub": "unlimited",
        • "min_defer_fail_to_trigger_protection": "5",
        • "outgoing_mail_hold": 0,
        • "outgoing_mail_suspended": 0,
        • "owner": "root",
        • "partition": "home",
        • "plan": "packagename",
        • "shell": "/bin/bash",
        • "startdate": "13 May 22 16:03",
        • "suspended": 0,
        • "suspendreason": "not suspended",
        • "suspendtime": null,
        • "temporary": 0,
        • "is_temporary_domain": 0,
        • "theme": "jupiter",
        • "uid": 0,
        • "unix_startdate": 1369256589,
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "accountsummary",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Bandwidth and Disk Quotas

Accounts / Bandwidth and Disk Quotas

Update cPanel account bandwidth quota

This function modifies a cPanel account's bandwidth quota.

Authorizations:
BasicAuth
query Parameters
string or integer
Default: "unlimited"
Example: bwlimit=0

The account's new bandwidth quota, in megabytes (MB).

  • 0 and unlimited - Grant the user unlimited bandwidth
user
required
string
Example: user=username

The username of a cPanel account on the server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  limitbw \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "bwlimits": [
      • {
        • "bwlimit": 0,
        • "bwlimitenable": 0,
        • "domains": [
          • "example.com",
          • "addondomain.com",
          • "subdomain.example.com"
          ],
        • "human_bwlimit": "500 MB",
        • "human_bwused": "none",
        • "unlimited": 1
        }
      ]
    },
  • "metadata": {
    • "command": "limitbw",
    • "reason": "Bandwidth Limit for username has been set to unlimited megabytes",
    • "result": 1,
    • "version": 1
    }
}

Return all cPanel accounts disk usage

This function lists the disk usage status of the system's user accounts. This also lists information about file system object (inode) usage.

Authorizations:
BasicAuth
query Parameters
cache_mode
string
Default: "on"
Possible Values: "on" "off"
Example: cache_mode=on

Each cPanel & WHM server maintains a cache of users’ disk quota usage. This parameter controls the way this function will use that cache.

  • on - Use the quota cache. This is fast, but it may be inaccurate.
  • off - Ignore the quota cache. This is slower, but it will be more accurate.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_disk_usage

Response samples

Content type
application/json
{
  • "data": {
    • "accounts": [
      • {
        • "blocks_limit": null,
        • "blocks_used": 2632,
        • "inodes_limit": 9999,
        • "inodes_used": 340,
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "get_disk_usage",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate cPanel account quotas

This function checks if quotas are enabled on at least one of a user's /home directory mounts.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  quota_enabled

Response samples

Content type
application/json
{
  • "data": {
    • "quota_enabled": 0
    },
  • "metadata": {
    • "command": "quota_enabled",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account bandwidth information

This function retrieves account bandwidth information.

Authorizations:
BasicAuth
query Parameters
month
integer [ 1 .. 12 ]
Example: month=12

The month to query, in numeric format.

This value defaults to the current month.

search
string
Example: search=ownername

A Perl Compatible Regular Expression (PCRE) that filters the results. The system matches the PCRE against the searchtype parameter's specified type.

If you do not specify a value for both the searchtype and search parameters, the function does not use the search criteria.

searchtype
string
Possible Values: "domain" "owner" "user" "ip" "package"
Example: searchtype=owner

The account information to query.

  • domain — Match domains against the search regular expression.
  • owner — Match the WHM user who owns the account against the search regular expression.
  • user — Match usernames against the search regular expression.
  • ip — Match IP addresses against the search regular expression.
  • package — Match hosting plans (packages) against the search regular expression.

If you do not specify a value for both the searchtype and search parameters, the function does not use the searchtype value.

showres
string
Example: showres=reseller_user

The reseller to query.

If you do not specify a value, the function queries all users.

year
integer
Example: year=2019

The year to query.

This value defaults to the current year.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  showbw

Response samples

Content type
application/json
{
  • "data": {
    • "acct": [
      • {
        • "bwusage": [
          • {
            • "deleted": 0,
            • "domain": "example.com",
            • "usage": 0
            }
          ],
        • "deleted": 0,
        • "limit": 0,
        • "maindomain": "example.com",
        • "owner": "root",
        • "reseller": 0,
        • "totalbytes": 352,
        • "user": "user"
        }
      ],
    • "month": 12,
    • "reseller": "root",
    • "totalused": 352,
    • "year": 2019
    },
  • "metadata": {
    • "command": "showbw",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel account disk quota

This function modifies a user's disk quota.

Authorizations:
BasicAuth
query Parameters
required
integer or string
Example: quota=500

The account's new quota.

  • A positive integer that represents the maximum amount of disk space, in megabytes (MB).
  • 0 or unlimited grants the account unlimited disk space.
user
required
string
Example: user=user

The cPanel account username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  editquota \
  user='user' \
  quota='500'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "editquota",
    • "reason": "Set quota for user.",
    • "result": 1,
    • "version": 1
    }
}

Domain Information

Accounts / Domain Domain Information

Return additional domain conversion details

This function returns the details of a conversion from an addon domain to an account. Use WHM API 1's convert_addon_domain_to_account to start a conversion.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
job_id
required
integer >= 1
Example: job_id=2

The conversion's job identification number.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_addon_fetch_conversion_details \
  job_id='2'

Response samples

Content type
application/json
{
  • "data": {
    • "domain": "cptestaddon175.tld",
    • "job_end_time": 1462216653,
    • "job_id": 2,
    • "job_start_time": 1462465001,
    • "job_status": "DONE",
    • "source_acct": "cptest",
    • "steps": [
      • {
        • "end_time": 1462465001,
        • "start_time": 1462465001,
        • "status": "DONE",
        • "step_name": "Saving email forwarder data",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465001,
        • "start_time": 1462465001,
        • "status": "DONE",
        • "step_name": "Saving custom DNS records",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465001,
        • "start_time": 1462465001,
        • "status": "DONE",
        • "step_name": "Saving installed SSL Certificate",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465001,
        • "start_time": 1462465001,
        • "status": "DONE",
        • "step_name": "Saving EasyApache 4 configuration",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465009,
        • "start_time": 1462465001,
        • "status": "DONE",
        • "step_name": "Removing Addon Domain",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465014,
        • "start_time": 1462465009,
        • "status": "DONE",
        • "step_name": "Creating new cPanel account",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465015,
        • "start_time": 1462465014,
        • "status": "DONE",
        • "step_name": "Restoring custom DNS records",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465016,
        • "start_time": 1462465015,
        • "status": "DONE",
        • "step_name": "Copying Custom VirtualHost Includes",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465016,
        • "start_time": 1462465016,
        • "status": "DONE",
        • "step_name": "Copying document root content",
        • "warnings": "/usr/bin/gtar: ./shadow: Cannot open: Permission denied\\n/usr/bin/gtar: Exiting with failure status due to previous errors"
        },
      • {
        • "end_time": 1462465016,
        • "start_time": 1462465016,
        • "status": "DONE",
        • "step_name": "Setting the proper permissions on document root",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465017,
        • "start_time": 1462465016,
        • "status": "DONE",
        • "step_name": "Copying email accounts",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465017,
        • "start_time": 1462465017,
        • "status": "DONE",
        • "step_name": "Restoring email forwarders",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465017,
        • "start_time": 1462465017,
        • "status": "DONE",
        • "step_name": "Copying Autoresponders",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465017,
        • "start_time": 1462465017,
        • "status": "DONE",
        • "step_name": "Copying webmail data",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465017,
        • "start_time": 1462465017,
        • "status": "DONE",
        • "step_name": "Restoring installed SSL Certificate",
        • "warnings": ""
        },
      • {
        • "end_time": 1462465017,
        • "start_time": 1462465017,
        • "status": "DONE",
        • "step_name": "Restoring EasyApache 4 configuration",
        • "warnings": ""
        }
      ],
    • "target_acct": "user2"
    },
  • "metadata": {
    • "command": "convert_addon_fetch_conversion_details",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return additional domain data

This function retrieves domain data for an addon domain.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The addon domain for which to retrieve details.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_addon_fetch_domain_details \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "docroot": "/home/exampleparent/public_html/example.com",
    • "has_dedicated_ip": 0,
    • "has_ssl_cert_installed": 0,
    • "ip": "192.0.2.0",
    • "is_sni_supported": 0,
    • "number_of_autoresponders": 0,
    • "number_of_domain_forwarders": 1,
    • "number_of_email_accounts": 2,
    • "number_of_email_forwarders": 1,
    • "owner": "username"
    },
  • "metadata": {
    • "command": "convert_addon_fetch_domain_details",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start additional domain conversion

This function initiates the conversion process for an addon domain into a cPanel account.

Note:

For information about the data that the system migrates when you convert an addon domain, read our Addon Domain Conversion List documentation.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
copymysqldb-*
string
Examples:
  • copymysqldb-*=copymysqldb-olddatabase1=newdatabase1 copymysqldb-olddatabase2=newdatabase2 - Copy multiple databases.
  • copymysqldb-*=newdatabase - Copy a single database.

Copy a MySQL® database from the source account to the new account with a new database name.

This parameter's format consists of copymysqldb, a hyphen, and the name of the existing database. For example, copymysqldb-olddatabase.

If you do not specify this parameter, the system does not copy any MySQL databases to the new account.

domain
required
string <domain>
Example: domain=example.com

The addon domain to convert into an account's main domain.

movemysqldb
string
Examples:
  • movemysqldb=movemysqldb-1=exampledb1 movemysqldb-2=exampledb2 movemysqluser-3=exampledb3 - Move multiple databases.
  • movemysqldb=exampledb - Move a single database.

Move the specified MySQL database from the source account to the new account.

If you do not specify this parameter, the system does not move any MySQL databases to the new account.

Note:

To move multiple databases, increment the parameter name. For example, movemysqldb-1, movemysqldb-2, and movemysqldb-3.

movemysqluser
string
Examples:
  • movemysqluser=movemysqluser-1=dbuser1 movemysqluser-2=dbuser2 movemysqluser-3=dbuser3 - Move multiple database users.
  • movemysqluser=dbuser1 - Move a single database user.

Move the specified MySQL database user from the source account into the new MySQL database account.

If you do not specify this parameter, the system does not move any MySQL database users to the new account.

Note:

To move multiple database users, increment the parameter name. For example, movemysqluser-1, movemysqluser-2, and movemysqluser-3.

pkgname
string
Default: "default"
Example: pkgname=mycustompkg

The hosting package that you want to assign to the new account.

username
required
string <username>
Example: username=username

The username for a specified account.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_addon_initiate_conversion \
  username='username' \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "convert_addon_initiate_conversion",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's additional domains

This function returns a list of addon domains that belong to the current user.

Important: When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_addon_list_addon_domains

Response samples

Content type
application/json
{
  • "data": {
    • "example.com": {
      • "docroot": "/home/exampleparent/public_html/example.com",
      • "domain_type": "addon",
      • "ip": "192.0.2.0",
      • "owner": "root",
      • "subdomain": "example.exampleparent.com"
      }
    },
  • "metadata": {
    • "command": "convert_addon_list_addon_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return additional domains conversion queue

This function returns a list of addon domains undergoing conversion into cPanel accounts.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_addon_list_conversions

Response samples

Content type
application/json
{
  • "data": {
    • "conversions": [
      • {
        • "domain": "example.com",
        • "end_time": 1462216653,
        • "job_id": 1,
        • "source_acct": "example",
        • "start_time": 1462216639,
        • "status": "DONE",
        • "target_acct": "example2"
        }
      ]
    },
  • "metadata": {
    • "command": "convert_addon_list_conversions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return conversion status for additional domain

This function returns the status of the convert addon domain to account process for specified conversion jobs. For data about the conversion status of all jobs, use the WHM API 1 convert_addon_fetch_conversion_details function.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
job_id
required
integer >= 1
Examples:
  • job_id=job_id-1=10&job_id-2=33&job_id-3=15 - Get the status for multiple conversion jobs.
  • job_id=10 - Get status for a single conversion job.

The conversion's job identification number.

Note:

To list entries for multiple conversion jobs, increment the parameter name. For example: job_id-0, job_id-1, and job_id-2.

Responses

Response Schema: application/json
object

An object that contains details about the conversion job's status.

object

Request samples 

whmapi1 --output=jsonpretty \
  convert_addon_get_conversion_status \
  job_id='10'

Response samples

Content type
application/json
{
  • "data": {
    • "1": {
      • "job_end_time": 1462383658,
      • "job_id": "1",
      • "job_status": "DONE",
      • "source_acct": "user1"
      }
    },
  • "metadata": {
    • "command": "convert_addon_get_conversion_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain user information

This function retrieves domain data.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The account's main domain.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  domainuserdata \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "userdata": {
      • "customlog": [
        • {
          • "format": "combined",
          • "target": "/usr/local/apache/domlogs/example.com"
          }
        ],
      • "documentroot": "/home/username/public_html",
      • "group": "reseller_username",
      • "hascgi": 1,
      • "homedir": "/home/username",
      • "ip": "10.0.0.1",
      • "owner": "root",
      • "phpopenbasedirprotect": 1,
      • "port": 80,
      • "scriptalias": [
        • {
          • "path": "/home/user/public_html/cgi-bin/",
          • "url": "/cgi-bin/"
          }
        ],
      • "serveradmin": "[email protected]",
      • "serveralias": "parkeddomain.com www.parkeddomain.com seconddomain.com",
      • "servername": "example.com",
      • "usecanonicalname": "Off",
      • "user": "user",
      • "userdirprotect": "Off"
      }
    },
  • "metadata": {
    • "command": "domainuserdata",
    • "reason": "Obtained userdata.",
    • "result": 1,
    • "version": 1
    }
}

Return all domains information

This function returns information about each domain on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_domain_info

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "docroot": "/home/user1/public_html/example.com",
        • "domain": "example.com",
        • "domain_type": "addon",
        • "ipv4": "192.0.2.255",
        • "ipv4_ssl": "192.0.2.255",
        • "ipv6": "2001:DB8:g1m:0N3y::1",
        • "ipv6_is_dedicated": 1,
        • "modsecurity_enabled": 1,
        • "parent_domain": "example.com",
        • "php_version": "ea-php54",
        • "port": 80,
        • "port_ssl": 443,
        • "user": "username",
        • "user_owner": "user1"
        }
      ]
    },
  • "metadata": {
    • "command": "get_domain_info",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain owner

This function lists the owner of a domain.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

A domain on the system that is owned by the user calling this function.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  getdomainowner \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "user": "username"
    },
  • "metadata": {
    • "command": "getdomainowner",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Passwords

Accounts / Passwords

Return minimum password strength

This function retrieves the minimum password strength for cPanel & WHM accounts.

Authorizations:
BasicAuth
query Parameters
name
string
Possible Values: "default" "cpaddons" "createacct" "list" "mysql" "passwd" "postgres" "sshkey" "virtual"
Example: name=default

The service for which to display the minimum password value. If you do not use this parameter, this function returns the minimum password setting for all values.

  • default - All services
  • cpaddons - cPAddons
  • createacct - New cPanel accounts
  • list - Mailing lists
  • mysql - MySQL® database users
  • passwd - WHM user or system accounts
  • postgres - PostgreSQL database users
  • sshkey - SSH keys
  • virtual - Mail, FTP, Web Disk, and WebDAV accounts

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  getminimumpasswordstrengths

Response samples

Content type
application/json
{
  • "data": {
    • "cpaddons": 50,
    • "createacct": 50,
    • "default": 50,
    • "list": 50,
    • "mysql": 50,
    • "passwd": 50,
    • "postgres": 50,
    • "sshkey": 50,
    • "virtual": 50
    },
  • "metadata": {
    • "command": "getminimumpasswordstrengths",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update minimum password strength

This function sets the minimum password strength for cPanel & WHM accounts.

Note

If you do not specify a value for a parameter, the system will retain the existing setting.

Authorizations:
BasicAuth
query Parameters
cpaddons
integer [ 1 .. 100 ]
Example: cpaddons=50

The minimum password strength for cPAddons.

createacct
integer [ 1 .. 100 ]
Example: createacct=50

The minimum password strength for new cPanel accounts.

default
integer [ 1 .. 100 ]
Example: default=50

The minimum password strength for all services.

list
integer [ 1 .. 100 ]
Example: list=50

The minimum password strength for mailing lists.

mysql
integer [ 1 .. 100 ]
Example: mysql=50

The minimum password strength for MySQL® database users.

passwd
integer [ 1 .. 100 ]
Example: passwd=50

The minimum password strength for WHM user or system accounts.

postgres
integer [ 1 .. 100 ]
Example: postgres=50

The minimum password strength for PostgreSQL® database users.

sshkey
integer [ 1 .. 100 ]
Example: sshkey=50

The minimum password strength for SSH keys.

virtual
integer [ 1 .. 100 ]
Example: virtual=50

The minimum password strength for mail, FTP, Web Disk, and WebDAV accounts.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setminimumpasswordstrengths

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setminimumpasswordstrengths",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return password strength

This function measures the strength of a password.

Authorizations:
BasicAuth
query Parameters
password
required
string
Example: password=12345luggage

The password.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_password_strength \
  password='12345luggage'

Response samples

Content type
application/json
{
  • "data": {
    • "strength": 21
    },
  • "metadata": {
    • "command": "get_password_strength",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable forced password update

This function forces a user to change the account password after the next login attempt.

Authorizations:
BasicAuth
query Parameters
stop_on_failure
integer
Default: 0
Possible Values: 0 1
Example: stop_on_failure=1

Whether to halt the function if it experiences an error.

  • 1 - Halt on error.
  • 0 - Continue on error.
users_json
required
string <json>
Example: users_json={"user1":1,"user2":1,"user3":1}

The list of users. The system will force each user that you specify to change their account's password the next time that they log in.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  forcepasswordchange \
  users_json='{"user1":1,"user2":1,"user3":1}'

Response samples

Content type
application/json
{
  • "data": {
    • "updated": [
      • "user"
      ]
    },
  • "metadata": {
    • "command": "forcepasswordchange",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel account password

This function modifies a cPanel or reseller account's password.

Note

  • When modifying the root password, this will only update the password for the root system user, but not for the root MySQL user.
  • To update the MySQL root user's password, use set_local_mysql_root_password.
Authorizations:
BasicAuth
query Parameters
db_pass_update
integer
Default: 1
Possible Values: 0 1
Example: db_pass_update=0

Whether to also change the account's MySQL® password.

  • 1 — Also update the account's MySQL password to match the password value.
  • 0 — Do not update.
enabledigest or digestauth
integer
Possible Values: 0 1
Example: enabledigest or digestauth=1

Whether to enable Digest Authentication for the account. If you do not specify a value, the account retains its current Digest Authentication setting.

  • 1 — Enable.
  • 0 — Disable.
password
required
string
Example: password=12345luggage

The account's new password.

user
required
string
Example: user=username

The account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  passwd \
  user='username' \
  password='12345luggage'

Response samples

Content type
application/json
{
  • "data": {
    • "app": [
      • "ftp"
      ]
    },
  • "metadata": {
    • "command": "passwd",
    • "reason": "Password changed for user “username”.",
    • "result": 1,
    • "version": 1
    }
}

Styles

The Styles and Themes module for WHM API 1.

Suspensions

Accounts / Suspensions

Suspend cPanel account

This function suspends an account.

Authorizations:
BasicAuth
query Parameters
disallowun
integer
Default: 0
Possible Values: 0 1
Example: disallowun=1

Whether to allow only the root user to unsuspend the account.

  • 1 - Only the root user can unsuspend the account.
  • 0 - The root user or the account's owner can unsuspend the account.
leave-ftp-accts-enabled
integer
Default: 0
Possible Values: 0 1
Example: leave-ftp-accts-enabled=0

Whether to skip suspension of the account's FTP accounts.

  • 1 - Do not suspend the FTP accounts.
  • 0 - Suspend the FTP accounts.
reason
string
Default: "Unknown"
Example: reason=Nonpayment

The reason for suspension.

Important:

We strongly recommend that you provide a reason for suspension whenever you suspend an account.

user
required
string
Example: user=username

The account to suspend.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  suspendacct \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "suspendacct",
    • "output": {
      • "raw": "Changing Shell to /bin/false...Changing shell for username. Warning: \"/bin/false\" is not listed in /etc/shells. Shell changed. Done Locking Password...Locking password for user username. passwd: Success Done Suspending mysql users Using Universal Quota Support (quota=0) Suspending websites... Using Universal Quota Support (quota=0) Suspending FTP accounts... Updating FTP passwords for username FTP password files updated. FTP vhost passwords synced username's account has been suspended\n"
      },
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Unsuspend cPanel account

This function unsuspends an account.

Note:

Only the root account and root-enabled resellers can unsuspend a locked account.

Authorizations:
BasicAuth
query Parameters
retain-service-proxies
integer
Default: 0
Possible Values: 0 1
Example: retain-service-proxies=0

Whether to retain any service proxies on an account.

  • 1 — Retain service proxies.
  • 0 — Do not retain service proxies.
user
required
string
Example: user=username

The account to unsuspend.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  unsuspendacct \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "unsuspendacct",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return suspended cPanel accounts

This function lists locked accounts on the server. Only WHM users with root-level privileges can unsuspend locked accounts.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listlockedaccounts

Response samples

Content type
application/json
{
  • "data": {
    • "account": [
      • "account1",
      • "account2"
      ]
    },
  • "metadata": {
    • "command": "listlockedaccounts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return suspended cPanel accounts and information

This function lists suspended accounts on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listsuspended

Response samples

Content type
application/json
{
  • "data": {
    • "account": [
      • {
        • "is_locked": 0,
        • "owner": "root",
        • "reason": "Suspended for nonpayment.",
        • "time": "Thu Nov 18 10:34:34 2014",
        • "unixtime": 1416306874,
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "listsuspended",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

API Execution

API Development Tools / API Execution

Enable CORS HTTP requests

This function allows your system to perform Cross-Origin Resource Sharing (CORS) HTTP requests.

Authorizations:
BasicAuth
query Parameters
url
required
string <url>
Example: url=http://www.example.com

The website that you wish to access.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cors_proxy_get \
  url='http://www.example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "_cp_redirects": [
      • {
        • "headers": {
          • "age": "425879",
          • "cache-control": "max-age=604800",
          • "content-length": "1256",
          • "content-type": "text/html; charset=UTF-8",
          • "date": "Thu, 05 Mar 2020 23:42:25 GMT",
          • "etag": "\"3147526947+ident\"",
          • "expires": "Thu, 12 Mar 2020 23:42:25 GMT",
          • "last-modified": "Thu, 17 Oct 2019 07:18:26 GMT",
          • "server": "ECS (dab/4BA8)",
          • "vary": "Accept-Encoding",
          • "x-cache": "HIT"
          },
        • "protocol": "HTTP/1.1",
        • "reason": "OK",
        • "status": "200",
        • "success": 1,
        • "url": "http://www.example.com"
        }
      ],
    • "content": "<!doctype html>\\n<html>\\n<head>\\n <title>Example Domain</title>\\n\\n <meta charset=\\\"utf-8\\\" />\\n <meta http-equiv=\\\"Content-type\\\" content=\\\"text/html; charset=utf-8\\\" />\\n <meta name=\\\"viewport\\\" content=\\\"width=device-width, initial-scale=1\\\" />\\n <style type=\\\"text/css\\\">\\n body {\\n background-color: #f0f0f2;\\n margin: 0;\\n padding: 0;\\n font-family: -apple-system, system-ui, BlinkMacSystemFont, \\\"Segoe UI\\\", \\\"Open Sans\\\", \\\"Helvetica Neue\\\", Helvetica, Arial, sans-serif;\\n\\n }\\n div {\\n width: 600px;\\n margin: 5em auto;\\n padding: 2em;\\n background-color: #fdfdff;\\n border-radius: 0.5em;\\n box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\\n }\\n a:link, a:visited {\\n color: #38488f;\\n text-decoration: none;\\n }\\n @media (max-width: 700px) {\\n div {\\n margin: 0 auto;\\n width: auto;\\n }\\n }\\n </style>\\n</head>\\n\\n<body>\\n<div>\\n <h1>Example Domain</h1>\\n <p>This domain is for use in illustrative examples in documents. You may use this\\n domain in literature without prior coordination or asking for permission.</p>\\n <p><a href=\\\"https://www.iana.org/domains/example\\\">More information...</a></p>\\n</div>\\n</body>\\n</html>\\n"
    },
  • "metadata": {
    • "command": "cors_proxy_get",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Run UAPI function through WHM API

This function calls a UAPI function through the WHM API. This function's output will match the UAPI function that it calls.

Authorizations:
BasicAuth
query Parameters
cpanel.function
required
string
Example: cpanel.function=get_stats

The UAPI function to call.

Note:

You must include the UAPI function's required parameters. You can also include its optional parameters.

For example, to call the UAPI get_stats function with its required display parameter and the bandwidthusage and diskusage values:

display=bandwidthusage|diskusage

cpanel.module
required
string
Example: cpanel.module=StatsBar

The UAPI function's cPanel module.

cpanel.user
required
string
Example: cpanel.user=username

The cPanel username to call with the UAPI function.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  uapi_cpanel \
  cpanel.function='get_stats' \
  cpanel.module='StatsBar' \
  cpanel.user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "uapi": {
      • "data": [
        • {
          • "_count": "0",
          • "_max": "unlimited",
          • "_maxed": 0,
          • "count": "0",
          • "feature": "addondomains",
          • "id": "addondomains",
          • "is_maxed": 0,
          • "item": "Addon Domains",
          • "max": "unlimited",
          • "maxed_phrase": "You are using your maximum allotment ([numf,_1]) of addon domains.",
          • "module": "Park",
          • "name": "addondomains",
          • "near_limit_phrase": "You are using [numf,_1] of [numf,_2] available addon [numerate,_2,domain,domains].",
          • "percent": 0,
          • "percent10": 0,
          • "percent20": 0,
          • "percent5": 0,
          • "phrase": "Addon Domains",
          • "role": "WebServer",
          • "zeroisunlimited": 0
          }
        ],
      • "errors": null,
      • "messages": null,
      • "metadata": {
        • "transformed": 1
        },
      • "status": 1,
      • "warnings": null
      }
    },
  • "metadata": {
    • "command": "uapi_cpanel",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Run multiple WHM API 1 functions

This function combines calls for multiple WHM API 1 functions.

Authorizations:
BasicAuth
query Parameters
abort_on_error
integer
Default: 0
Possible Values: 0 1
Example: abort_on_error=0

Whether to stop processing remaining commands in the batch when a command returns an error.

  • 1 — Do not process remaining commands in the batch when an error occurs.
  • 0 — When an error occurs, process the remaining commands in the batch.
command
required
string
Example: command=version

The WHM API 1 function to call.

Important:

Specify a command parameter for each function.

Note:

Include the function's input parameters as a URI-encoded list after the function name. For example, to call the killdns function with a domain parameter value of example.com directly you would use:

killdns?domain=example.com

To call this function using the batch function, URI-encode the command and pass it as part of the batch function:

/json-api/batch?api.version=1&command=killdns%3Fdomain%3Dexample.com

You can call the same function multiple times within a single batch API call. For example:

/json-api/batch?api.version=1&command=version&command=version&command=version

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  batch \
  command='version'

Response samples

Content type
application/json
{
  • "data": {
    • "result": [
      • {
        • "data": {
          • "hostname": "example-hosting.com"
          },
        • "metadata": {
          • "command": "gethostname",
          • "reason": "OK",
          • "result": 1,
          • "version": 1
          }
        },
      • {
        • "data": {
          • "version": "11.88.0.1"
          },
        • "metadata": {
          • "command": "version",
          • "reason": "OK",
          • "result": 1,
          • "version": 1
          }
        }
      ]
    },
  • "metadata": {
    • "command": "batch",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Run cPanel API or UAPI function

You can call cPanel API and UAPI functions through the WHM API.

This method is useful, for example, when you develop plugins for WHM users, particularly resellers, but need to access cPanel functions. You can make these calls from within either the WHM or cPanel interfaces.

Important:

We recommend that you use the WHM API 1 uapi_cpanel function. The uapi_cpanel function is a more flexible way to call cPanel API functions from WHM. For example, you can use the uapi_cpanel function with the WHM API 1 batch function.

Before calling a cPanel API function via this method, read its documentation. The cPanel API function may require other parameters not listed in this document.

Authorizations:
BasicAuth
query Parameters
cpanel_jsonapi_apiversion
integer
Default: 2
Possible Values: 1 2 3
Example: cpanel_jsonapi_apiversion=3

The cPanel API version to use.

  • 1 — Use cPanel API 1.
  • 2 — Use cPanel API 2.
  • 3 — Use UAPI.
cpanel_jsonapi_func
required
string
Example: cpanel_jsonapi_func=listpopswithdisk

The UAPI function name.

Important:

Function names are case-sensitive.

cpanel_jsonapi_module
required
string
Example: cpanel_jsonapi_module=Email

The UAPI module name.

Important:

Module names are case-sensitive.

cpanel_jsonapi_user
required
string <username>
Example: cpanel_jsonapi_user=user

The cPanel username for the account through which to call the function.

Make certain that you specify the username in lowercase characters only. cPanel & WHM automatically converts usernames to lowercase when you create a cPanel account. For this reason, if you supply a username that includes some or all capital letters, the call will fail.

Variable Names and Values
string

The function's input parameters and their values. You can add any additional parameters supported by the underlying cPanel API function.

Example: domain=example.com

Note:

  • Separate multiple parameter=value pairs with the ampersand character (&).
  • You must URI-encode these values.

Responses

Response Schema: application/json
data
any

Information returned by the cPanel API function passed in cpanel_jsonapi_module and cpanel_jsonapi_func.

object

Request samples 

whmapi1 --output=jsonpretty \
  cpanel \
  cpanel_jsonapi_user='user' \
  cpanel_jsonapi_module='Email' \
  cpanel_jsonapi_func='listpopswithdisk'

Response samples

Content type
application/json
{
  • "data": null,
  • "metadata": {
    • "command": "cpanel",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Run remote WHM API 1 function

This function executes WHM API 1 functions on a remote server.

Authorizations:
BasicAuth
query Parameters
function
required
string
Example: function=passwd

The name of the function to call on the remote server.

host
required
string
Example: host=host.example.com

The remote server's hostname or IP address.

parameter_name
required
string
Example: parameter_name=user

The name of the parameter for the function.

Note:

You must enter the same number of parameter_name and parameter_value parameters.

parameter_value
required
string
Example: parameter_value=username2

The value of the parameter for the function.

Note:

You must enter the same number of parameter_name and parameter_value parameters.

password
required
string
Example: password=luggage12345

The password to log in to the remote server.

tls_verification
string
Example: tls_verification=on

Whether to use TLS verification. This parameter defaults to On.

Important:

We strongly recommend that you use TLS verification. Only connect to a server if you can verify its identity.

username
required
string
Example: username=username

The username to log in to the remote server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  execute_remote_whmapi1_with_password \
  host='host.example.com' \
  username='username' \
  password='luggage12345' \
  function='passwd' \
  parameter_name='user' \
  parameter_value='username2'

Response samples

Content type
application/json
{
  • "data": {
    • "app": [
      • "string"
      ],
    • "key-name*": "system"
    },
  • "metadata": {
    • "command": "execute_remote_whmapi1_with_password",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

API Statistics

API Development Tools / API Statistics

Return deprecated cPanel API 1 functions by date

This function returns the cPanel API 1 functions that the system called on specific dates. This is useful, for example, to check whether your system calls any cPanel API 1 functions.

Important:

The function only returns cPanel API 1 functions. We deprecated cPanel API 1 and plan to remove those functions at a later date. For more information, read our Guide to Replacing cPanel API 1 Functions with UAPI Equivalents documentation.

Authorizations:
BasicAuth
query Parameters
type
string
Default: "cpapi1"
Example: type=cpapi1

The cPanel API 1 function to query.

Note:

cpapi1 is the only possible value.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_api_calls

Response samples

Content type
application/json
{
  • "data": {
    • "result": [
      • {
        • "count": 200000,
        • "entry": "Email::printdomainoptions",
        • "timestamp": 1548828000
        }
      ]
    },
  • "metadata": {
    • "command": "get_api_calls",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return deprecated cPanel API 1 functions

This function returns the daily interface use of cPanel API 1 functions. Use this function to find out which API calls your custom interfaces or third-party plugins use.

Important:

The function only returns cPanel API 1 functions. We deprecated cPanel API 1 and plan to remove those functions at a later date. For more information, read our Guide to Replacing cPanel API 1 Functions with UAPI Equivalents documentation.

Authorizations:
BasicAuth
query Parameters
type
string
Default: "cpapi1"
Value: "cpapi1"
Example: type=cpapi1

The cPanel API type to query.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_api_pages

Response samples

Content type
application/json
{
  • "data": {
    • "count": 200000,
    • "entry": "/usr/local/cpanel/base/frontend/jupiter/plugin1/index.html.tt",
    • "timestamp": 1548828000
    },
  • "metadata": {
    • "command": "get_api_pages",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

API Token Management

API Development Tools / API Token Management

Create WHM API token

This function creates an API token. You can use API tokens instead of a password or access hash key to execute WHM API 1 functions over HTTPS. For more information about API tokens, read our Manage API Tokens in WHM documentation.

Important:

You must call this function over an SSL connection.

Authorizations:
BasicAuth
query Parameters
acl
string
Examples:
  • acl=acl-0=create-acct acl-1=list-accts acl-2=kill-acct - Assign multiple privileges.
  • acl=all - Assign a single privilege.

The privileges to assign to the token. If you do not use this parameter, the system assigns all of your privileges to the token.

Note:

  • You can only assign privileges that you possess to the API token.
  • To assign multiple privileges to the token, increment the parameter name. For example: acl-0, acl-1, acl-2.
expires_at
integer
Default: 0
Example: expires_at=1609372800

The API token's expiration time. If you do not use this parameter, the API token will not expire.

Important:

When an API token expires, the system does not delete it. You must manually delete expired API tokens.

token_name
required
string
Example: token_name=example

The API token's name.

Note:

  • An API token name's maximum length is 50 characters, and the name may only contain alphanumeric characters, dashes (-), and underscores (_).
  • You must assign a name that does not already exist to the API token.
string or string or string
Examples:
  • whitelist_ip=whitelist_ip-0=192.0.2.1 whitelist_ip-1=192.0.2.5 whitelist_ip-2=192.0.2.8/29 whitelist-ip-3=fc00:abcd::f whitelist-ip-4=2620:0:28a4::/48 - Assign multiple IP or CIDR ranges.
  • whitelist_ip=192.0.2.8/29 - Assign a single IP or CIDR range.

One or more optional remote IP or CIDR IP ranges this token may be used from. If you do not use this parameter, the system does not limit which IPs can use this token.

Note:

  • To assign multiple whitelisted IPs to the token, increment the parameter name. For example: whitelist_ip-0, whitelist_ip-1, whitelist_ip-2.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  api_token_create \
  token_name='example'

Response samples

Content type
application/json
{
  • "data": {
    • "acls": [
      • "kill-acct"
      ],
    • "create_time": 1483625276,
    • "expires_at": 1609372800,
    • "name": "example",
    • "token": "UWU28DCA23NKY76CN17MDPKM3O7EFQY8",
    • "whitelist_ips": [
      • "1.1.1.1",
      • "1.1.1.2",
      • "1.1.1.8/29",
      • "fc00:abcd:0000:0000:0000:0000:0000:000f",
      • "2620:0000:28a4:0000:0000:0000:0000:0000/48"
      ]
    },
  • "metadata": {
    • "command": "api_token_create",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return WHM API tokens

This function lists a WHM account's API tokens.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  api_token_list

Response samples

Content type
application/json
{
  • "data": {
    • "tokens": {
      • "my-controller-token": {
        • "acls": {
          • "create-acct": 0,
          • "edit-account": 0,
          • "limit-bandwidth": 1,
          • "list-accts": 1,
          • "suspend-acct": 1,
          • "upgrade-account": 0
          },
        • "create_time": 1483625276,
        • "expires_at": 1609372800,
        • "name": "my-controller-token",
        • "whitelist_ips": [
          • "192.0.2.1",
          • "192.0.2.2",
          • "192.0.2.8/29",
          • "fc00:abcd:0000:0000:0000:0000:0000:000f",
          • "2620:0000:28a4:0000:0000:0000:0000:0000/48"
          ]
        },
      • "my-read-only-token": {
        • "acls": {
          • "create-acct": 0,
          • "edit-account": 0,
          • "limit-bandwidth": 0,
          • "list-accts": 1,
          • "suspend-acct": 0,
          • "upgrade-account": 0
          },
        • "create_time": 1490882281,
        • "expires_at": null,
        • "name": "my-read-only-token",
        • "whitelist_ips": null
        }
      }
    },
  • "metadata": {
    • "command": "api_token_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable WHM API token

This function revokes an API token from the WHM account.

Authorizations:
BasicAuth
query Parameters
token_name
required
string
Examples:
  • token_name=token_name-1=subway&token_name-2=job&token_name-3=jmkMRXBnhp20iz - Revoke multiple API tokens.
  • token_name=subway - Revoke a single API token.

The API token's name.

Note:

To revoke multiple API tokens, increment this parameter's name. For example: token_name-1, token_name-2, and token_name-3.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  api_token_revoke \
  token_name='subway'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "api_token_revoke",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update WHM API token's settings

This function updates an API token's settings.

Authorizations:
BasicAuth
query Parameters
acl
string
Examples:
  • acl=acl-0=create-acct acl-1=list-accts acl-2=kill-acct - Assign multiple privilges.
  • acl=all - Assign a single privilege.

The new privileges to assign to the token. If you do not use this parameter, the system will assign all of your privileges to the token.

For a list of Access Control List (ACL) privileges, read our Edit Reseller Nameservers and Privileges documentation.

Note:

  • You can only assign privileges that you possess to the API token.

  • The function replaces all current privileges with the privileges that you pass in this parameter.

  • To assign multiple privileges to the token, increment the parameter name. For example, acl-1, acl-2, acl-3.

expires_at
integer <unix_timestamp>
Default: 0
Example: expires_at=1609372800

The API token's expiration time. If you do not use this parameter, the API token will not expire.

Important:

When an API token expires, the system does not delete it. You must manually delete expired API tokens.

new_name
string <= 50 characters
Example: new_name=example

The API token's new name. If you do not use this parameter, the API token's name remains the same.

Note:

  • An API token name's maximum length is 50 characters, and the name may only contain alphanumeric characters, dashes (-), and underscores (_).

  • You must assign a name that does not already exist to the API token.

token_name
required
string
Example: token_name=token

The API token's name.

string or string or string or string
Examples:
  • whitelist_ip=whitelist_ip=any - Clear a token's whitelisted IPs list.
  • whitelist_ip=whitelist_ip-0=192.0.2.1 whitelist_ip-1=192.0.2.5 whitelist_ip-2=192.0.2.8/29 whitelist-ip-3=fc00:abcd::f whitelist-ip-4=2620:0:28a4::/48 - Assign multiple IPs or CIDR ranges.
  • whitelist_ip=whitelist_ip=192.0.2.8/29 - Assign a single IP or CIDR range.

The new remote IP or CIDR IP ranges to assign to this token. If you do not use this parameter, the system does not limit which IPs can use this token.

Note:

  • The function replaces all current whitelisted IPs with the IPs you pass in this parameter.

  • To assign multiple whitelisted IPs to the token, increment the parameter name. For example: whitelist_ip-0, whitelist_ip-1, whitelist_ip-2.

  • If a token has whitelisted IPs set, they can be cleared by passing whitelist_ip=any as a parameter. This will allow any IP to make API calls using that token.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  api_token_update \
  token_name='token'

Response samples

Content type
application/json
{
  • "data": {
    • "acls": [
      • "create-acct",
      • "kill-acct",
      • "list-accts"
      ],
    • "create_time": 1483625276,
    • "expires_at": 1609372800,
    • "name": "example",
    • "whitelist_ips": [
      • "192.0.2.1",
      • "192.0.2.2",
      • "192.0.2.8/29",
      • "fc00:abcd:0000:0000:0000:0000:0000:000f",
      • "2620:0000:28a4:0000:0000:0000:0000:0000/48"
      ]
    },
  • "metadata": {
    • "command": "api_token_update",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Look up API token details

This function looks up an API token’s details based on the token itself.

Authorizations:
BasicAuth
query Parameters
token
required
string
Example: token=GVJWD78FF12NMBFKYKPS9BJ483C0XSQH

The API token.

Responses

Response Schema: application/json
Any of
object

The API token’s details. Only present if the system recognizes the given token.

object (Metadata)

Request samples 

whmapi1 --output=jsonpretty \
  api_token_get_details \
  token=GVJWD78FF12NMBFKYKPS9BJ483C0XSQH

Response samples

Content type
application/json
Example
{
  • "data": {
    • "acls": [
      • "create-acct",
      • "kill-acct",
      • "list-accts"
      ],
    • "create_time": 1483625276,
    • "expires_at": 1609372800,
    • "name": "example",
    • "whitelist_ips": [
      • "192.0.2.1",
      • "192.0.2.2",
      • "192.0.2.8/29",
      • "fc00:abcd:0000:0000:0000:0000:0000:000f",
      • "2620:0000:28a4:0000:0000:0000:0000:0000/48"
      ]
    },
  • "metadata": {
    • "command": "api_token_get_details",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Applications

API Development Tools / Applications

Return WHM API 1 functions list

This function lists available WHM API 1 functions.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  applist

Response samples

Content type
application/json
{
  • "data": {
    • "app": [
      • "accountsummary",
      • "listaccts"
      ]
    },
  • "metadata": {
    • "command": "applist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return registered applications

This function lists registered AppConfig applications.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_appconfig_application_list

Response samples

Content type
application/json
{
  • "data": {
    • "cpanel": [
      • {
        • "acls": [
          • "any"
          ],
        • "displayname": "Roundcube",
        • "entryurl": "roundcube/",
        • "features": [
          • "roundcube"
          ],
        • "group": "mailman",
        • "icon": "roundcube.ico",
        • "name": "roundcube",
        • "origin": "clamavconnector.conf",
        • "phpConfig": "php.ini",
        • "target": "_self",
        • "upgradecall": "/usr/local/roundcube/bin/upgrade",
        • "url": "/3rdparty/roundcube",
        • "user": "roundcube"
        }
      ],
    • "webmail": [
      • {
        • "acls": [
          • "any"
          ],
        • "displayname": "Roundcube",
        • "entryurl": "roundcube/",
        • "features": [
          • "roundcube"
          ],
        • "group": "mailman",
        • "icon": "roundcube.ico",
        • "name": "roundcube",
        • "origin": "clamavconnector.conf",
        • "phpConfig": "php.ini",
        • "target": "_self",
        • "upgradecall": "/usr/local/roundcube/bin/upgrade",
        • "url": "/3rdparty/roundcube",
        • "user": "roundcube"
        }
      ],
    • "whostmgr": [
      • {
        • "acls": [
          • "any"
          ],
        • "displayname": "Roundcube",
        • "entryurl": "roundcube/",
        • "features": [
          • "roundcube"
          ],
        • "group": "mailman",
        • "icon": "roundcube.ico",
        • "name": "roundcube",
        • "origin": "clamavconnector.conf",
        • "phpConfig": "php.ini",
        • "target": "_self",
        • "upgradecall": "/usr/local/roundcube/bin/upgrade",
        • "url": "/3rdparty/roundcube",
        • "user": "roundcube"
        }
      ]
    },
  • "metadata": {
    • "command": "get_appconfig_application_list",
    • "reason": "Got application list",
    • "result": 1,
    • "version": 1
    }
}

Session

API Development Tools / Session

Create a temporary user session

This function creates a new temporary user session for a specified service. This allows users with WHM access to log in to third-party applications (for example, billing systems) without storing the account password.

Note:

  • The system destroys the temporary session after 15 minutes of inactivity.
  • For more information about the Single Sign On feature, read our Guide to API Authentication documentation.
Authorizations:
BasicAuth
query Parameters
app
string
Possible Values: "Backups_Home" "Calendar_Configure" "ContactInfo_Change" "Cron_Home" "Database_MySQL" "Database_phpMyAdmin" "Domains_AddonDomains" "Domains_SubDomains" "Email_AccountLevelFiltering" "Email_Accounts" "Email_Archive" "Email_Authentication" "Email_AutoResponders" "Email_BoxTrapper" "Email_DefaultAddress" "Email_DeliveryReport" "Email_Forwarders" "Email_GreyListing" "Email_MailingLists" "Email_MX" "Email_SpamFilter" "Email_UserLevelFiltering" "FileManager_Home" "Locale_Change" "Password_Change" "Site_Software" "Site_Software_*" "Stats_AWStats" "WHMCS_billing" "add_a_dns_zone" "add_an_a_entry_for_your_hostname" "add_a_new_ip_address" "add_a_package" "additional_mysql_access_hosts" "add_remove_recognized_ip_addresses" "apache_configuration" "apache_mod_userdir_tweak" "apache_status" "api_shell" "api_tokens" "apps_managed_by_appconfig" "assign_ipv6_address" "background_process_killer" "backup_configuration" "backup_restoration" "backup_system_migration" "backup_user_selection" "basic_webhost_manager_setup" "blocker" "change_account_contact_email" "change_hostname" "change_log" "change_multiple_sites_ip_addresses" "change_mysql_user_password" "change_ownership_of_an_account" "change_ownership_of_multiple_accounts" "change_root_password" "change_sites_ip_address" "cloudlinux_lve_manager" "compiler_access" "configuration_cluster" "configure_application_locales" "configure_cpanel_analytics" "configure_cpanel_cron_jobs" "configure_postgresql" "configure_remote_service_ips" "configure_security_policies" "contact_manager" "convert_addon_domain_to_account" "copy_a_locale" "copy_an_account_from_another_server_with_an_account_password" "cpanel_development_forum" "cpanel_log_rotation_configuration" "cpanel_plugin_file_generator" "cpanel_web_disk_configuration" "cpanel_web_services_configuration" "cphulk_brute_force_protection" "create_a_new_account" "create_support_ticket" "customization" "daily_process_log" "database_map_tool" "delete_a_dns_zone" "delete_a_locale" "delete_a_package" "directoryindex_priority" "dns_cluster" "dns_server" "easyapache_4" "edit_a_locale" "edit_a_package" "edit_backup_mx_hosts" "edit_blacklisted_smtp_ips" "edit_dns_zone" "edit_mx_entry" "edit_only_verify_recipient_smtp_hosts" "edit_questions_and_answers" "edit_reseller_name_servers_and_privileges" "edit_sender_verification_bypass_ips" "edit_system_mail_preferences" "edit_trusted_smtp_ips" "edit_zone_templates" "email_all_resellers" "email_all_users" "email_deliverability" "enable_dkim_and_spf_globally" "exim_configuration_manager" "feature_manager" "file_and_directory_restoration" "forceful_server_reboot" "force_password_change" "ftp_server_configuration" "ftp_server_proftpd_pureftpd" "ftp_server_selection" "generate_an_ssl_certificate_and_signing_request" "global_configuration" "graceful_server_reboot" "grant_cpanel_support_access" "greylisting" "host_access_control" "http_server_apache" "ico-security-advisor" "imap_server" "include_editor" "initial_quota_setup" "install_an_rpm" "install_an_ssl_certificate_on_a_domain" "install_a_perl_module" "install_a_perl_module_process" "install_cpaddons_site_software" "ip_migration_wizard" "ipv6_ranges" "legacy_backup_configuration" "legacy_language_file_upload" "legacy_restore_backups" "legacy_restore_multiple_backups" "legacy_restore_multiple_backups_confirmation" "limit_bandwidth_usage" "list_accounts" "list_parked_domains" "list_subdomains" "list_suspended_accounts" "locale_editor" "locale_xml_download" "locale_xml_upload" "log_rotation" "mailbox_conversion" "mail_delivery_reports" "mailing_list_manager_mailman" "mail_queue_manager" "mailserver_configuration" "mail_server_exim" "mail_troubleshooter" "manage_account_suspension" "manage_autossl" "manage_compiler_group" "manage_cpaddons_site_software" "manage_custom_rbls" "manage_databases" "manage_database_users" "manage_demo_mode" "manage_external_authentication" "manage_external_authentication_providers" "manage_external_authentication_users" "manage_hooks" "manage_mysql_profiles" "manage_plugins" "manage_resellers_ip_delegation" "manage_resellers_shared_ip" "manage_roots_ssh_keys" "manage_services_ssl_certificates" "manage_shell_access" "manage_ssl_hosts" "manage_wheel_group_users" "market_provider_manager" "memory_usage_restrictions" "modify_an_account" "modify_cpanel_whm_news" "modify_upgrade_multiple_accounts" "modsecurity_configuration" "modsecurity_tools" "modsecurity_vendors" "module_installers" "multiphp_ini_editor" "multiphp_manager" "mysql_mariadb_upgrade" "mysql_root_password" "nameserver_record_report" "nameserver_selection" "non_standard_locale_configuration" "park_a_domain" "password_modification" "password_strength_configuration" "perform_a_dns_cleanup" "php_fpm_service_for_apache" "phpMyAdmin" "piped_log_configuration" "process_manager" "purchase_and_install_an_ssl_certificate" "quota_modification" "raw_apache_log_download" "raw_ftp_log_download" "rearrange_an_account" "rebuild_rpm_database" "rebuild_the_ip_address_pool" "remote_access_key" "repair_a_mysql_database" "repair_mailbox_permissions" "reseller_center" "reserved_ips_editor" "reset_account_bandwidth_limit" "reset_a_dns_zone" "reset_a_mailman_password" "reset_resellers" "resolver_configuration" "restore_a_full_backup_cpmove_file" "restore_modules_summary" "review_transfers_and_restores" "security_questions" "server_information" "server_profile" "server_time" "service_manager" "service_status" "setup_edit_domain_forwarding" "set_zone_time_to_live_ttl" "shell_fork_bomb_protection" "show_accounts_over_quota" "show_current_disk_usage" "show_current_running_processes" "show_edit_reserved_ips" "show_ip_address_usage" "show_mysql_processes" "show_or_delete_current_ip_addresses" "show_reseller_accounts" "skeleton_directory" "smtp_restrictions" "software_development_kit" "spamd_startup_configuration" "sql_server_mysql" "sql_server_pgsql" "ssh_password_authorization_tweak" "ssh_server_openssh" "ssl_storage_manager" "statistics_software_configuration" "support_center" "synchronize_dns_records" "system_update" "task_queue_monitor" "terminal" "terminate_accounts" "theme_manager" "traceroute_enable_disable" "transfer_tool" "tweak_settings" "two_factor_authentication" "unsuspend_bandwidth_exceeders" "update_database_map" "update_database_map_process" "update_preferences" "update_server_software" "upgrade_downgrade_an_account" "upgrade_to_latest_version" "view_available_locales" "view_bandwidth_usage" "view_mail_statistics_summary" "view_relayers" "view_reseller_usage_and_manage_account_status" "view_sent_summary" "web_template_editor"
Example: app=Backups_Home

The cPanel or WHM application to which the session will link. This parameter defaults to a blank string, which redirects the user to the cPanel Home interface.

  • A valid application name, to link the session to an application.
  • An invalid application name, to create the session but not link it to an application.
cp_security_token
string
Example: cp_security_token=cpsess1234567890

The session's security token.

locale
string
Example: locale=fr

The session's locale. This parameter defaults to the Server Locale setting in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Note:

  • If you specify a locale, the server sends a cookie to your browser with that locale setting. The cookie expires after one year.
  • Users can change the locale with the language options at the bottom of the login interface.
preferred_domain
string
Example: preferred_domain=example.com

The hostname or IP address for the function to use in the url return. This parameter's value defaults to the server's hostname.

service
required
string
Possible Values: "cpaneld" "whostmgrd" "webmaild"
Example: service=cpaneld

The session's service.

user
required
string

The session's cPanel account username or a valid email address.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_user_session \
  user='[email protected]' \
  service='cpaneld'

Response samples

Content type
application/json
{}

Authentication Providers

Authentication / Authentication Providers

External Authentication

Authentication / External Authentication

Disable identity provider

This function disables a external authentication identity provider for a specified service.

Authorizations:
BasicAuth
query Parameters
provider_id
required
string
Example: provider_id=cpanelid

A valid identity provider's identification key.

service_name
required
string
Possible Values: "cpaneld" "webmaild" "whostmgrd"
Example: service_name=cpaneld

The cPanel & WHM service's name:

  • cpaneld
  • webmaild
  • whostmgrd

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_authentication_provider \
  service_name='cpaneld' \
  provider_id='cpanelid'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "disable_authentication_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable identity provider modules that fail to load

This function disables any enabled identity provider modules that fail to load.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_failing_authentication_providers

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "disabled_services": [
          • "cpaneld",
          • "webmaild"
          ],
        • "failures_to_disable": [
          • {
            • "failure": "An informative failure message.",
            • "service_name": "whostmgrd"
            }
          ],
        • "provider_failure": "(ERR mcddbv) The system failed to load the module “Cpanel::Security::Authn::Provider::Facebook“ because of an error: Can't locate Cpanel/Security/Authn/Provider/Facebook.pm in @INC (@INC contains: /usr/local/cpanel /usr/local/cpanel/3rdparty/perl/514/lib/perl5/cpanel_lib/i386-linux-64int /usr/local/cpanel/3rdparty/perl/514/lib/perl5/cpanel_lib /usr/local/cpanel/3rdparty/perl/514/lib/perl5/5.14.4/i386-linux-64int /usr/local/cpanel/3rdparty/perl/514/lib/perl5/5.14.4 /opt/cpanel/perl5/514/site_lib/i386-linux-64int /opt/cpanel/perl5/514/site_lib /var/cpanel/perl) at (eval 143) line 1.\nBEGIN failed--compilation aborted at (eval 143) line 1.\n",
        • "provider_name": "facebook",
        • "provider_namespace": "Cpanel::Security::Authn::Provider::Facebook"
        }
      ]
    },
  • "metadata": {
    • "command": "disable_failing_authentication_providers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable identity provider

This function enables an external authentication identity provider for a specified service.

Authorizations:
BasicAuth
query Parameters
provider_id
required
string
Example: provider_id=cpanelid

A valid identity provider's identification key.

service_name
required
string
Possible Values: "cpaneld" "webmaild" "whostmgrd"
Example: service_name=cpaneld

The cPanel & WHM service's name:

  • cpaneld
  • webmaild
  • whostmgrd

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_authentication_provider \
  service_name='cpaneld' \
  provider_id='cpanelid'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "enable_authentication_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return identity provider client configuration

This function retrieves the configuration details for the client of an external authentication identity provider.

Authorizations:
BasicAuth
query Parameters
provider_id
required
string
Example: provider_id=cpanelid

The identity provider's key.

service_name
required
string
Possible Values: "cpaneld" "whostmgrd" "webmaild"
Example: service_name=cpaneld

The cPanel & WHM service's name.

  • cpaneld — The cPanel daemon.
  • whostmgrd — The WHM daemon.
  • webmaild — The Webmail daemon.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_provider_client_configurations \
  service_name='cpaneld' \
  provider_id='cpanelid'

Response samples

Content type
application/json
{}

Return identity provider configuration fields

This function retrieves the configuration fields for a external authentication identity provider.

Authorizations:
BasicAuth
query Parameters
provider_id
required
string
Example: provider_id=cpanelid

The identity provider's key.

service_name
required
string
Possible Values: "cpaneld" "whostmgrd" "webmaild"
Example: service_name=cpaneld

The cPanel & WHM service's name.

  • cpaneld
  • whostmgrd
  • webmaild

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_provider_configuration_fields \
  service_name='cpaneld' \
  provider_id='cpanelid'

Response samples

Content type
application/json
{
  • "data": {
    • "configuration_fields": [
      • {
        • "description": "The Secret of the Client",
        • "display_order": 1,
        • "field_id": "client_secret",
        • "label": "Client Secret",
        • "value": null
        },
      • {
        • "description": "The ID of the Client.",
        • "display_order": 0,
        • "field_id": "client_id",
        • "label": "Client ID",
        • "value": null
        }
      ]
    },
  • "metadata": {
    • "command": "get_provider_configuration_fields",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available identity providers

This function lists available external authentication identity providers for all services.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_available_authentication_providers

Response samples

Content type
application/json
{
  • "data": {
    • "providers": [
      • {
        • "color": "dd4b39",
        • "configured": 1,
        • "cpaneld_enabled": 1,
        • "cpaneld_link": "https://hostname.example.com:2083/openid_connect/cpanelid",
        • "display_name": "cPanel",
        • "documentation_url": "https://go.cpanel.net/cpanelidmanage",
        • "icon": "Click to view...iVBORw0KGgoAAAANSUhEUgAAACEAAAAhCAYAAABX5MJvAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAV1JREFUeNrsVtGNwjAMJegGYIRucBmhtwEjdAMyQjYoG2SEG6HcBGUDugFskHOQg1zTlFaN\\/\\/KkqMh2yYvt53S3KygomIZaE+y9P8BDJ9xXpdSDxT9jwX7dxDJsDMvCuvl33GF1sBwS5O8GX7eVgCabGyRkGJF25v0sJHrcyDH7iMhWEl9zWSD1\\/xs1klJn8J\\/gZ4WxNdgu8KyiDXGIfmJ7LO6R8CI5rJnwO+Kv0Wb9Z7xlZr+wMt8f\\/ANmyCoCMF3CUmP8rOmHip1AM\\/8tdbLcjfnL5NigYmIp+ilp5iYRJNkmajtLIBuJiUZ1S+aDKGDjI8tGk+N\\/9yuy0ODcGIjL8UEmcXKLDelRDQ5tHcuIkSLQE1WYhIRfMRIEmiV1Z7NES5Rh9nIisRGVWGOyyyflC5fSkDsTmk1KnVBMbForqQw+IVtUCP3KEpdojffHnRGKcq3LZ3pBgST+BRgANXt+WPKE7tYAAAAASUVORK5CYII=",
        • "icon_type": "image/svg+xml",
        • "id": "cpanelid",
        • "label": "Log in with a cPanelID Account",
        • "provider_name": "cpanel",
        • "textcolor": "FFFFFF",
        • "webmaild_enabled": 1,
        • "webmaild_link": "https://hostname.example.com:2096/openid_connect/cpanelid",
        • "whostmgr_enabled": 1,
        • "whostmgrd_link": "https://hostname.example.com:2087/openid_connect/cpanelid"
        }
      ]
    },
  • "metadata": {
    • "command": "get_available_authentication_providers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update identity provider client configuration

This function sets the values of configuration fields for an external authentication identity provider.

Authorizations:
BasicAuth
query Parameters
configurations
required
string <json>
Example: configurations={"client_id":"victoria","client_secret":"secret"}

The configuration values to set for the identity provider.

Note

The items in this parameter depend on the fields that the provider implements through OpenID.

provider_id
required
string
Example: provider_id=cpanelid

The identity provider's key.

service_name
required
string
Possible Values: "cpaneld" "whostmgrd" "webmaild"
Example: service_name=cpaneld

The cPanel & WHM service's name.

  • cpaneld — The cPanel daemon.
  • whostmgrd — The WHM daemon.
  • webmaild — The Webmail daemon.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_provider_client_configurations \
  service_name='cpaneld' \
  provider_id='cpanelid' \
  configurations='{"client_id":"victoria","client_secret":"secret"}'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_provider_client_configurations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return identity provider login interface appearance

This function retrieves the display configuration for the login button of an external authentication identity provider.

Authorizations:
BasicAuth
query Parameters
provider_id
required
string
Example: provider_id=google

The identity provider's key.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_provider_display_configurations \
  provider_id='google'

Response samples

Content type
application/json
{
  • "data": {
    • "configurations": [
      • {
        • "color": "dd4b39",
        • "display_name": "Google",
        • "documentation_url": "https://developers.google.com/identity/protocols/OpenIDConnect",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyMiIgaGVpZ2h0PSIxNCIgdmlld0JveD0iMCAwIDIyIDE0Ij48ZyBmaWxsPSIjZmZmIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik03IDZ2Mi40aDMuOTdjLS4xNiAxLjAzLTEuMiAzLjAyLTMuOTcgMy4wMi0yLjM5IDAtNC4zNC0xLjk4LTQuMzQtNC40MlM0LjYxIDIuNTggNyAyLjU4YzEuMzYgMCAyLjI3LjU4IDIuNzkgMS4wOGwxLjktMS44M0MxMC40Ny42OSA4Ljg5IDAgNyAwIDMuMTMgMCAwIDMuMTMgMCA3czMuMTMgNyA3IDdjNC4wNCAwIDYuNzItMi44NCA2LjcyLTYuODQgMC0uNDYtLjA1LS44MS0uMTEtMS4xNkg3ek0yMiA2aC0yVjRoLTJ2MmgtMnYyaDJ2MmgyVjhoMiIvPjwvZz48L3N2Zz4=",
        • "icon_type": "image/svg+xml",
        • "label": "Log in via Google",
        • "link": "/openid_connect/google",
        • "provider_name": "google",
        • "service": "cpaneld",
        • "textcolor": "FFFFFF"
        },
      • {
        • "color": "dd4b39",
        • "display_name": "Google",
        • "documentation_url": "https://developers.google.com/identity/protocols/OpenIDConnect",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyMiIgaGVpZ2h0PSIxNCIgdmlld0JveD0iMCAwIDIyIDE0Ij48ZyBmaWxsPSIjZmZmIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik03IDZ2Mi40aDMuOTdjLS4xNiAxLjAzLTEuMiAzLjAyLTMuOTcgMy4wMi0yLjM5IDAtNC4zNC0xLjk4LTQuMzQtNC40MlM0LjYxIDIuNTggNyAyLjU4YzEuMzYgMCAyLjI3LjU4IDIuNzkgMS4wOGwxLjktMS44M0MxMC40Ny42OSA4Ljg5IDAgNyAwIDMuMTMgMCAwIDMuMTMgMCA3czMuMTMgNyA3IDdjNC4wNCAwIDYuNzItMi44NCA2LjcyLTYuODQgMC0uNDYtLjA1LS44MS0uMTEtMS4xNkg3ek0yMiA2aC0yVjRoLTJ2MmgtMnYyaDJ2MmgyVjhoMiIvPjwvZz48L3N2Zz4=",
        • "icon_type": "image/svg+xml",
        • "label": "Log in via Google",
        • "link": "/openid_connect/google",
        • "provider_name": "google",
        • "service": "webmaild",
        • "textcolor": "FFFFFF"
        },
      • {
        • "color": "dd4b39",
        • "display_name": "Google",
        • "documentation_url": "https://developers.google.com/identity/protocols/OpenIDConnect",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyMiIgaGVpZ2h0PSIxNCIgdmlld0JveD0iMCAwIDIyIDE0Ij48ZyBmaWxsPSIjZmZmIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik03IDZ2Mi40aDMuOTdjLS4xNiAxLjAzLTEuMiAzLjAyLTMuOTcgMy4wMi0yLjM5IDAtNC4zNC0xLjk4LTQuMzQtNC40MlM0LjYxIDIuNTggNyAyLjU4YzEuMzYgMCAyLjI3LjU4IDIuNzkgMS4wOGwxLjktMS44M0MxMC40Ny42OSA4Ljg5IDAgNyAwIDMuMTMgMCAwIDMuMTMgMCA3czMuMTMgNyA3IDdjNC4wNCAwIDYuNzItMi44NCA2LjcyLTYuODQgMC0uNDYtLjA1LS44MS0uMTEtMS4xNkg3ek0yMiA2aC0yVjRoLTJ2MmgtMnYyaDJ2MmgyVjhoMiIvPjwvZz48L3N2Zz4=",
        • "icon_type": "image/svg+xml",
        • "label": "Log in via Google",
        • "link": "/openid_connect/google",
        • "provider_name": "google",
        • "service": "whostmgrd",
        • "textcolor": "FFFFFF"
        }
      ]
    },
  • "metadata": {
    • "command": "get_provider_display_configurations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update identity provider login interface appearance

This function sets the display configuration for the login button of an external authentication identity provider.

Authorizations:
BasicAuth
query Parameters
required
object

The display configuration in JSON-encoded key-value format.

provider_id
required
string
Example: provider_id=cpanelid

The identity provider's key.

service_name
required
string
Possible Values: "cpaneld" "whostmgrd" "webmaild"
Example: service_name=cpaneld

The cPanel & WHM service's name.

  • cpaneld — The cPanel daemon.
  • whostmgrd — The WHM daemon.
  • webmaild — The Webmail daemon.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty set_provider_display_configurations service_name='cpaneld' provider_id='cpanelid' configurations='{"color":"dd4b39","display_name":"cPanel","icon":"iVBORw0KGgoAAAANSUhEUgAAACEAAAAhCAYAAABX5MJvAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAV1JREFUeNrsVtGNwjAMJegGYIRucBmhtwEjdAMyQjYoG2SEG6HcBGUDugFskHOQg1zTlFaN\\/\\/KkqMh2yYvt53S3KygomIZaE+y9P8BDJ9xXpdSDxT9jwX7dxDJsDMvCuvl33GF1sBwS5O8GX7eVgCabGyRkGJF25v0sJHrcyDH7iMhWEl9zWSD1\\/xs1klJn8J\\/gZ4WxNdgu8KyiDXGIfmJ7LO6R8CI5rJnwO+Kv0Wb9Z7xlZr+wMt8f\\/ANmyCoCMF3CUmP8rOmHip1AM\\/8tdbLcjfnL5NigYmIp+ilp5iYRJNkmajtLIBuJiUZ1S+aDKGDjI8tGk+N\\/9yuy0ODcGIjL8UEmcXKLDelRDQ5tHcuIkSLQE1WYhIRfMRIEmiV1Z7NES5Rh9nIisRGVWGOyyyflC5fSkDsTmk1KnVBMbForqQw+IVtUCP3KEpdojffHnRGKcq3LZ3pBgST+BRgANXt+WPKE7tYAAAAASUVORK5CYII=","icon_type":"image/svg+xml","label":"Log in with a cPanelID Account","textcolor":"FFFFFF"}'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_provider_display_configurations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return accounts linked to identity providers

This function lists all accounts that link to available external authentication identity providers.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_users_authn_linked_accounts

Response samples

Content type
application/json
{
  • "data": {
    • "username_linked_accounts": [
      • {
        • "link_time": 1443124003,
        • "preferred_username": "[email protected]",
        • "provider_id": "cpanelid",
        • "provider_protocol": "openid_connect",
        • "subject_unique_identifier": "123456789012345678901",
        • "username": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "get_users_authn_linked_accounts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Login URL

Authentication / Login URL

Return cPanel Store or cPanel Market login URL

This function retrieves the login URL for the cPanel Store or a cPanel Market provider.

Authorizations:
BasicAuth
query Parameters
provider
required
string
Example: provider=cPStore

The cPanel Store or cPanel Market provider's name.

url_after_login
required
string <url>
Example: url_after_login=http://hostname.example.com/redirectionlocation.cgi?state

The location to which the cPanel Store or cPanel Market provider redirects the user's browser after they log in.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_login_url \
  provider='cPStore' \
  url_after_login='http://hostname.example.com/redirectionlocation.cgi?state'

SSH Keys and Connections

Authentication / SSH Keys and Connections

Return cPanel account access hash Deprecated

This function regenerates or retrieves a user's access hash. For more information about access hashes, read our Remote Access Key documentation.

Warning:

We deprecated this function. We strongly suggest that you use the WHM API 1 api_token_create function.

Authorizations:
BasicAuth
query Parameters
generate
required
integer
Possible Values: 0 1
Example: generate=0

Whether to regenerate the access hash.

  • 1 — Regenerate the access hash.
  • 0 — Do not regenerate the access hash.
user
required
string <username>
Example: user=root

The user's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  accesshash \
  user='root' \
  generate='0'

Response samples

Content type
application/json
{
  • "data": {
    • "accesshash": "cb523f89e9a31123fde7c6f93b580ac05bf00a2804d4febe6667ab9917a14baa1c4914da209bf55c862999ea51983a117a4d2f238140200b1e5b270b94b2c52492747e5ebfdeddb8abf4e1b0c428c6c68b701b48e13dbe39da49450e7a8e5422e18ab3b6290b5b6556bd82ee21d9c1103e7a51d1e94f2ac0c4dcc6a10954b8634c6db16a541660c3c89e10254f05583f4167adfcff7781090ea930647b46e5b981f3e16c7723ca4e12dc4b54a778dc66a28df73632a0d3a8e01e207b9fd6b555b72936a903af014f30061d712d736176a87fb5333c5b90cf0bb4f3c6735f2b45929ac79fb1184045a5f4c20bfcc553f5ab760eec077c0d6096e54d02724201281e441e7b0f642370a63f61c68766e224c8510bc32b0316780660c34352cbfeeccfee9d4f02e20ba7b664d3e84e9419ca386c41df07613f8af252aba8626a8b54796bbe616f41af1e6f11a3d0327f7608d23666fca64e6ebe899f7479a5fb0aea008b1e7a41890c9c58037682450febf91b7aa1c080d31d834b0ae466f8533df838ab271b26a7fb7de96402ad4a818d6b786af92c38414d2ef6c88deb7c685a1e60c3cbcfbf20cf6d2a00dd50d2be9bc1824d91284ec6842dd7db42564dfc3ecb75c1a9bc775c45c5f08784b9e2885c2d"
    },
  • "metadata": {
    • "command": "accesshash",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable SSH key for server

This function authorizes a public SSH key to access the server. When you call this function, it adds the key to the /root/.ssh/authorized_keys file.

Warning:

  • Do not transfer private keys over insecure ports.
  • Only root and root-enabled resellers can use this function, and it only affects the root public SSH keys. To perform this function on a regular user account, call the cPanel API 2 SSH::authkey function via the WHM API. For more information, read our Use WHM API to Call cPanel API and UAPI documentation.
Authorizations:
BasicAuth
query Parameters
authorize
required
integer
Possible Values: 1 0
Example: authorize=1

Whether to authorize the public SSH key to access the server.

  • 1 — Authorize.
  • 0 — Do not authorize.
file
required
string
Example: file=sshkey.pub

The public SSH key file's name.

Note:

  • This file must exist in the /root/.ssh directory.
  • If you call both the file and the text parameters, the function ignores the file parameter.
options
string
Example: options=agent-forwarding,cert-authority

A comma-separated list of options to include with the public SSH key. For a list of options, read the OpenBSD manaual.

This parameter defaults to no options.

text
required
string
Example: text=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCys7JbGhkAZ8E4Pmq8D4EBm1UedKK2oMhs3RVIEFRJX6S86Itw6Qmhds62LNGrxuVL11W6v25+maIiBhXnslyQpd838tHyAC7J/SJojDid8acovX/4xgJQaJHLAh9tLgyQXnNhIxIGJ4nVZ+8OqM2Vb1Cps+E5H17ivG07PXnVPEvwMaeWkm2DnGgSy5kmjVpNKlj9GWFCn/SJd7up7QnbGKoz87pxKDs3esp+ziuPEAJHLeXnKHWPVukQgtRUpUBdqkCvu5hUkhpaiWmBR8yxajkxbSObPw+ZkELhmm+fQseOfEbrwToMRJCO7gAKwBtNi7OhyFM7YFrvdo0xh6cn

The text of the SSH public key file.

Note:

  • If you call both the file and the text parameters, the function ignores the file parameter.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  authorizesshkey \
  file='sshkey.pub' \
  text='ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCys7JbGhkAZ8E4Pmq8D4EBm1UedKK2oMhs3RVIEFRJX6S86Itw6Qmhds62LNGrxuVL11W6v25+maIiBhXnslyQpd838tHyAC7J/SJojDid8acovX/4xgJQaJHLAh9tLgyQXnNhIxIGJ4nVZ+8OqM2Vb1Cps+E5H17ivG07PXnVPEvwMaeWkm2DnGgSy5kmjVpNKlj9GWFCn/SJd7up7QnbGKoz87pxKDs3esp+ziuPEAJHLeXnKHWPVukQgtRUpUBdqkCvu5hUkhpaiWmBR8yxajkxbSObPw+ZkELhmm+fQseOfEbrwToMRJCO7gAKwBtNi7OhyFM7YFrvdo0xh6cn' \
  authorize='1'

Response samples

Content type
application/json
{
  • "data": {
    • "authorized": 1,
    • "file": "sshkey.pub"
    },
  • "metadata": {
    • "command": "authorizesshkey",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate SSH connection to another server

This function tests an SSH connection to another server.

Authorizations:
BasicAuth
query Parameters
host
required
string <domain>
Example: host=example.com

The remote server's hostname.

port
integer >= 1
Default: 22
Example: port=22

The remote server's port number.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  check_remote_ssh_connection \
  host='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "comment": "null",
    • "protocol_versions": [
      • "2.0"
      ],
    • "received": "SSH-2.0-OpenSSH_5.3",
    • "server_software": "OpenSSH_5.3"
    },
  • "metadata": {
    • "command": "check_remote_ssh_connection",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create SSH key pair

This function generates an SSH key pair.

Authorizations:
BasicAuth
query Parameters
abort_on_existing_key
integer
Default: 1
Possible Values: 0 1
Example: abort_on_existing_key=1

Whether to abort the function if the user already has a key with the same name.

  • 1 — Abort.
  • 0 — Continue.
algorithm
string
Possible Values: "rsa2" "dsa"
Example: algorithm=dsa

The key's encryption algorithm. The parameter defaults to the system's default algorithm.

bits
integer
Possible Values: 1024 2048 4096
Example: bits=2048

The key's bits:

  • 1024 — The DSA algorithm's default value.
  • 2048
  • 4096 — The RSA algorithm's default value.
comment
string
Default: ""
Example: comment=NoComment

A comment.

name
string
Default: "id_rsa"
Example: name=KeyFile

The key's filename.

This parameter defaults to id_rsa if the algorithm is RSA, and id_dsa if the algorithm is DSA.

passphrase
string
Default: ""
Example: passphrase=123456luggage

The key's secure passphrase.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  generatesshkeypair

Response samples

Content type
application/json
{
  • "data": {
    • "fingerprint": null,
    • "name": "KeyFile"
    },
  • "metadata": {
    • "command": "generatesshkeypair",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Migrate OpenSSH key to PuTTY format

This function converts an OpenSSH private key to a PuTTY key.

Warning:

Do not transfer private keys over insecure ports.

Authorizations:
BasicAuth
query Parameters
file
required
string
Example: file=KeyFile

The private key file's name.

keep_file
integer
Default: 1
Possible Values: 0 1
Example: keep_file=0

Whether to keep the OpenSSH file on the server after conversion.

  • 1 — Keep the file.
  • 0 — Delete the file.
passphrase
string
Default: ""
Example: passphrase=12345luggage

The private key file's passphrase.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convertopensshtoputty \
  file='KeyFile'

Response samples

Content type
application/json
{
  • "data": {
    • "key": "PuTTY-User-Key-File-2: ssh-rsa Encryption: aes256-cbc Comment: imported-openssh-key Public-Lines: 12 AAAAB3NzaC1yc2EAAAABIwAAAgEAuuth41YYyWABsRKexJXgSMD8FvIBFCptUfZP 4U/6R41FvL/RS+99kq1WL/KASsKRoEA5uc0axM+iNgZtKuemQYGUZNvN+8X8sC/l E6GF7X3Pvj2Ml4AlD7TQv0WQZUp9xn+SlOti+3pYh+S56vzNjvdifO7U5mPGW/81 9N4vGhG3ThaAgETwkL33CM2LeNRuvoWpeQcuzEVX2aOvHQZqOvV15fTjZ64ZGL3i UDtKmeaHs4tMqgNIUXgn1P1V4TgPvTIfopH8FBX3g1pD15XD3vn+XHLwia0505c5 +QM+jElS3HHb0vrrDo3S+8koXLWp07wu/GYrvBd5+MlsSV7bpr7lmWj8uMQjc0ap eZe+eb/MteadWnqIPeOVuracssCvDLqXEPK2KjhFMPqBTepNhZaJHRfvkodPm43C 50nhqzrNoxFvXb1rfCjPPqGfhuSZhlCmo2FDiZPKdl0X7bhzDIvMVikyqJP06bqK y9iclyQv0VPfyCIx/VDcVclIoUa8A49nAinXHKeUx9QUNBHv8wXdyz7W41jQa+++ Ih3Yc4o9rpV95DDmKp7iF6kFk4aVjIWDgEsPTaL28wlvUyazoW5TAGPHDrRJoedU ag8KDRNPrGbKYu3CvoINiz0sshyCvr1gjKNG75Cwe+L4hXIkaw8wlCpwFq8VSX70 RS9Pei8= Private-Lines: 28 bb31s+xsiAv1+pclnmvreEYdxvuVmbeWMjUWJd4Y4TKIAyLEItsXNs078qn1QAZ+ Wj6t+0HcnhuUVICHyCyJrp++1g4OtzTAHRczaD5ybhb9ktSe1qlnszKD1Rg5/o+B 61h6kvMcZyuNSjtPkmqQ3XIh8OFYybB2oJXY7gJQzfRuRwk8dx9YWtIR4438Nbv5 ecTzGUDWvx+AfYzC4X/UIGiRy8AftfiBQyA+c1OFyg37qM1SLYnZYmIpSf5GsQ3A MaEGlB9P9hE2uoqZ4yT/A0aHj7w8DGEzYZqxNbMlCIJhLEO3vKZvMvaq7Q8ramG6 BzYwUz+8NPgCBUp1qyIcN2vvEHEq57pMMHYNfJMVfG9o0ijo+xxGCPV3MosmmvRI 1nxH0nrgdA2o6SJp/dJrKm3Hicbbxak/Kz4m8BROcnlCgptdjHp9V/cBnFq/UUHv or32gShGWmnG6+XyQs4LxpbLC4koz8EjPwg3/3W2Qn6Drn3i98omvZpmnX466i7e GUiHaiKTpBkqZkHmHFxNBAbbs85yngeo8o3RGUsmN69RupTqSkkLDuDFOMwgfsZG TWexWg/qBe+8Xrbshd9HphxvWv+Q3YcSeg+mm8Bc50Q5saLKYdQQsbfV5wtIpvLj 0eyjoTSh+FkPGBw/iB1MDzYV5OoIIgiDBndP2bOK2zFsLElSbbv/r3i//wL98316DgJWmJiQDqKxly4MEij8TfIVDAsdeyJJKvg6iGahonHbEBkZ9g9wcCpxlg8iMtTf /7eb8SmcPwe1NGdgB7PR1dU/RQ/kBbLaaBfo/1jQEnCC8VmksVu7B9ULImfLEOEm +A4J4NpKKlQocgCvJAtMogL+uRS5GpojJIElVqP12jnb7Ij3AYY3Zb4qotlprLeK 7dJslpNnrD/MSvbJZ/ZoAX+xyDxUMeq/83Xv30i5/wh00QBY4Cv5NTDU4rPoVmQm EWGW5aQx34in4JHY5bK3F4BvVYm7MscKLHoU8/OeKVAgzNcatUgPlN43FG9SX0AE pP3EYlVADSfULdbfBn9dZDidAiDMXnCv9259J65zA64tuT9XluinHXVs5PA/f5vm rZPQhAzGThw7h9L6rGYGfSKd9KYoTwf8kSOA6WU7OEyhfTvCdaW76vPi4CRW2M/Y RHX0IUdv3VxfKb4WnXFeQl6LshmGB1T2mbMyfThlqUCGAvPJyWDtZ6OpOUl3CK87 3jhFzO7t5wruhuWZ3RcISVsrdqcjgCrKy6Q9y+HbLJoNY40BkJm7f6WeV+hHn7o1 od7JiqDGq3Qk+ECEdexvqdRQS7BWgO7xudGFk+WFY02zoGvq5DMviNfsxqhM06P+ JgEinB8xPPCOPzi6q8T1y1Pz44gmluM15/QRX4z0Mwz6UQasVC/NsZxdfoNGtCy0 c2DAscy4zsiKhZMlLr0loPYycO2bOit6E5eYkrACJR2115/ZgVwzvzdmc/INJCxG3TvKYbeuv/tkolt56uJWGfMF2ZrfLJaaQ0iAiUyMep/keLP2bJ4Y97o+03BtQszZ zixXvzeQAX97WdBaUJU0C3mCKDOtkv4RWZ8hXV5v0m2tm7xbXVBzF22Pej2iHDKx GQkciskBRwQM4bDZorkcO+WnGn6uPbtw5v/AuIUqB1UNAcehWN6UTiFNveP4hLYu iRGWnZZ+uTbip91PNXSxXzb9yMWV2qSVIsZvud8kpR8ttL26Z4ySUKkFuPrgUeTeELnOF3GP6Ixk+IkwxU575w== Private-MAC: 1dfa6a4c8297d31e4cfadbf61aac8b4c5ca75584"
    },
  • "metadata": {
    • "command": "convertopensshtoputty",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete SSH key

This function function deletes an SSH key from the server.

Warning:

Only the root account can use this function, and it only affects the root keys. To perform this function on a cPanel user account, call the cPanel API 2 SSH::authkey function through the WHM API.

Authorizations:
BasicAuth
query Parameters
file
required
string
Example: file=/root/.ssh/test

The SSH key file's name.

leave_authorized
integer
Default: 1
Possible Values: 0 1
Example: leave_authorized=0

Whether to authorize the SSH key to access the server.

  • 1 — Leave authorized.
  • 0 — Do not leave authorized.
user
string
Deprecated
Example: user=username

The SSH key's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  deletesshkey \
  file='/root/.ssh/test'

Response samples

Content type
application/json
{
  • "data": {
    • "file": "/root/.ssh/test"
    },
  • "metadata": {
    • "command": "deletesshkey",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return SSH keys list

This function lists the server's SSH keys.

Warning:

Only the root account can use this function, and it only affects the root keys. To perform this function on a regular user account, call the cPanel API 2 SSH::listkeys function through the WHM API.

Authorizations:
BasicAuth
query Parameters
files
string
Example: files=TestKey

A filename, to limit the results to keys that have that filename.

private
integer
Default: 1
Possible Values: 0 1
Example: private=0

Whether to display only private keys.

  • 1 — Display only private keys.
  • 0 — Display all keys.
private_texts
integer
Default: 1
Possible Values: 0 1
Example: private_texts=0

Whether to include private key text.

  • 1 — Include private key text.
  • 0 — Do not include private key text.
public
integer
Possible Values: 0 1
Example: public=0

Whether to display only public keys.

  • 1 — Display only public keys.
  • 0 — Display all keys.
public_texts
integer
Default: 0
Possible Values: 0 1
Example: public_texts=0

Whether to include public key text.

  • 1 — Include public key text.
  • 0 — Do not include public key text.
sync_authorized
integer
Default: 0
Possible Values: 0 1
Example: sync_authorized=0

Whether to synchronize the keys that can access the server.

  • 1 — Synchronize the keys.
  • 0 — Do not synchronize the keys.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listsshkeys

Response samples

Content type
application/json
{
  • "data": {
    • "keys": [
      • {
        • "authorized": 0,
        • "comment": "REPO [email protected]",
        • "ctime": 1416596824,
        • "file": "TestKey",
        • "mtime": 1416596824,
        • "private": 1,
        • "text": "ssh-rsaXXXXX3XXXX1XX2XXXXXXXXXXXXXXxXXXX6XXXXX90X41X7XXXXX02XXXXX8XXXX54XXXXXXXXXXX2X07XXXXXXXXXXX7XXXX4XXX2X98XXXX98X80XXXXXXX7X/X4XXXXxX1XXXXXXXXXXXxXXXXXXXXX6+4XXXX36XXXXX3XXXXXX1XXXXXXX/X7+XX1XX6XXXX0XXXXXXX0XXXXXXXX+XxX99X7X2XXXXXX03xXXXXX0XXXXXXXXXX9XXXXXXX9XXXXXXXXXXXX/XXXXX07XXXXX3XXXXXX5XXX+/XXXXXXXXXXXXX3XxXXXXXXXXXXXX6XXXXXXXXXXXX2XXXXXXXXXXXXXXXXX3XX+XXXX3XXXXXXX== REPO [email protected]"
        }
      ]
    },
  • "metadata": {
    • "command": "listsshkeys",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Import SSH key

This function imports an SSH key.

Authorizations:
BasicAuth
query Parameters
extract_private
integer
Possible Values: 0 1
Example: extract_private=0

Whether to extract and save only the private key.

  • 1 — Private key only.
  • 0 — All data.

Note:

This parameter defaults to 1 for PPK (PuTTY Key Generator) files and 0 for all other imports.

extract_public
integer
Possible Values: 0 1
Example: extract_public=0

Whether to extract and save only the public key.

  • 1 — Public key only.
  • 0 — All data.

Note:

This parameter defaults to 1 for PPK (PuTTY Key Generator) files and 0 for all other imports.

key
required
string
Example: key=-----BEGIN RSA PRIVATE KEY----- hPH+o4NgZrky7iGBb5iUg8R4aQzLPexpYfet25bLESvHOtutsBkbN7UWAaoM0pgM hytunlM8UU4BArJWlJyY6AD59aluZowBbuowKeU+f+TRaeJNJvkxTCOAipzp6LyG nrSVJ5hxSN/RPfntho1MEsdWYewVI4eLayuiZJyD+VONCYJh/vPLaZ9AVUJuMerl s/ZJ24AwCW8cILG+C3TWJRCjl4Ji+sJ9A5P29p/ad18cyJc1F+wmAzMULWitCaB7 mmE0i1nkiZRygQzzKjqdBYWCjujxfoE2+nPufAJg8ZdIEI1xSVBe5jKnj8DRX67w NAnNjXANMRePo39/RbDOSEXsD62h1qH93SnPsAhYT1JE6xHKV85AVIVOe8ktTA8t jMBBioCudBFngqPHknUrIJZ2QfUm0fkKBZaoKW4yr3JjGk+5y6kg02gSDIA7/jGc 8rs3iKN+QJ/ug2x/v7Xe0OozVqpl5QTltEMGJzJ1jFh9WnqgsgLTiJWlE7x5VSv8 fV8A5WTafOhBHnKuOpmpjAel1GD5DT1jNx3LhWXMHOayawC0WY04lT5kkLLWhuN2 pNqY6UBk6Z3m1ifPINq85RdnHriJiD3H/+6P+cUyGSOznni8yqU764LId4nNClWd Xc+VvM1Udw0Sm7xF7err9CKHYUg3HfFYQPBQOfI0ib9wqOi7zWq2vhH21B5OgcTg Bsw/HJUQ/IVnTbsqgZSn0sckaRguv/ifmwbISO1aQ4Yxcohe/4miOw05r6ihbYGW LO5kP0I8SBMCibkGFh5AxVnNgoGAW0l33hOPPSIVUTkE+8d3zYXLzupTFXCvmohl jq0it7uIGOxSglf7XH3eXlNKaZjK7pBJgS5HeXM80JI8FCfifqnkaik8XTE66Ll0 s1ySaGevGkPpX5Rhbgsm4IqddAeFvlmKIND8Zvh/wfT++bbD7bbFwFlrWCU3chce 8KaNVUP+whCAlaS7oGcs38ygaRFXIE3vug4Ra8Xiy/qfyp4YR67sMg46avHyoVky uFbVv2n7HphZb7g3WS3ns3/gCQQv9TYcdBoRnKW2yEqbzOQb9Fdt7EjgMohT/bdS pM6nRWFNdmWoihLzLbSi3bnc9iDwXZA8KyE3mpVi4QFfijR4dfrVWxEz5Ln2l9HC SZA6VPGzEOwOVVND98/HTu3oViJUV1gyDIWlyggSUDTyhfo/Z+c3tTHa+cv0f7xY oL63hWLgZQD2m/g6rKpsN3NhC77tCyCNZavdKy7usvZyCsoH/mPR2129LcwAwbJ3 u2Ec7qLncztSePHOmfmCTTED00a0YzFhKIQoJf7GrgLCMapYN/YPu0vgTDMPSi11 RH0rdyzd6MuPVDZwLnWO+SltjX85yz1ba/Q199HZwQOw6ZyejDaPSWJHOndD3k+r Q0T38gci9k4D87EwmfpK7zOaCoaiGiRQ6+DdYOv6hlzQ6Fdb2FOtlGQZharQ9WTC jOJBEj2oGUruc6P3fqhfUVllWi4cck0GgWZwcsmG1dDr8W6K9lrGA1dPbXoOns1B l58ghMGtHG7D0VlHs6SIqFmHr5kUgSQ4jJ2KZkVU8CrPBZ2HRtHQJJyjZWW2AbrE -----END RSA PRIVATE KEY-----

The key's contents.

name
required
string
Example: name=TestKey

The key's name.

passphrase
string or null
Default: null
Example: passphrase=123456luggage

The key's passphrase.

Note:

This parameter is required whenever you import a PPK file.

user
string <username>
Deprecated
Example: user=username

The key's owner.

Note:

You can specify this parameter, but the system does not use it.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  importsshkey \
  name='TestKey' \
  key='-----BEGIN RSA PRIVATE KEY----- hPH+o4NgZrky7iGBb5iUg8R4aQzLPexpYfet25bLESvHOtutsBkbN7UWAaoM0pgM hytunlM8UU4BArJWlJyY6AD59aluZowBbuowKeU+f+TRaeJNJvkxTCOAipzp6LyG nrSVJ5hxSN/RPfntho1MEsdWYewVI4eLayuiZJyD+VONCYJh/vPLaZ9AVUJuMerl s/ZJ24AwCW8cILG+C3TWJRCjl4Ji+sJ9A5P29p/ad18cyJc1F+wmAzMULWitCaB7 mmE0i1nkiZRygQzzKjqdBYWCjujxfoE2+nPufAJg8ZdIEI1xSVBe5jKnj8DRX67w NAnNjXANMRePo39/RbDOSEXsD62h1qH93SnPsAhYT1JE6xHKV85AVIVOe8ktTA8t jMBBioCudBFngqPHknUrIJZ2QfUm0fkKBZaoKW4yr3JjGk+5y6kg02gSDIA7/jGc 8rs3iKN+QJ/ug2x/v7Xe0OozVqpl5QTltEMGJzJ1jFh9WnqgsgLTiJWlE7x5VSv8 fV8A5WTafOhBHnKuOpmpjAel1GD5DT1jNx3LhWXMHOayawC0WY04lT5kkLLWhuN2 pNqY6UBk6Z3m1ifPINq85RdnHriJiD3H/+6P+cUyGSOznni8yqU764LId4nNClWd Xc+VvM1Udw0Sm7xF7err9CKHYUg3HfFYQPBQOfI0ib9wqOi7zWq2vhH21B5OgcTg Bsw/HJUQ/IVnTbsqgZSn0sckaRguv/ifmwbISO1aQ4Yxcohe/4miOw05r6ihbYGW LO5kP0I8SBMCibkGFh5AxVnNgoGAW0l33hOPPSIVUTkE+8d3zYXLzupTFXCvmohl jq0it7uIGOxSglf7XH3eXlNKaZjK7pBJgS5HeXM80JI8FCfifqnkaik8XTE66Ll0 s1ySaGevGkPpX5Rhbgsm4IqddAeFvlmKIND8Zvh/wfT++bbD7bbFwFlrWCU3chce 8KaNVUP+whCAlaS7oGcs38ygaRFXIE3vug4Ra8Xiy/qfyp4YR67sMg46avHyoVky uFbVv2n7HphZb7g3WS3ns3/gCQQv9TYcdBoRnKW2yEqbzOQb9Fdt7EjgMohT/bdS pM6nRWFNdmWoihLzLbSi3bnc9iDwXZA8KyE3mpVi4QFfijR4dfrVWxEz5Ln2l9HC SZA6VPGzEOwOVVND98/HTu3oViJUV1gyDIWlyggSUDTyhfo/Z+c3tTHa+cv0f7xY oL63hWLgZQD2m/g6rKpsN3NhC77tCyCNZavdKy7usvZyCsoH/mPR2129LcwAwbJ3 u2Ec7qLncztSePHOmfmCTTED00a0YzFhKIQoJf7GrgLCMapYN/YPu0vgTDMPSi11 RH0rdyzd6MuPVDZwLnWO+SltjX85yz1ba/Q199HZwQOw6ZyejDaPSWJHOndD3k+r Q0T38gci9k4D87EwmfpK7zOaCoaiGiRQ6+DdYOv6hlzQ6Fdb2FOtlGQZharQ9WTC jOJBEj2oGUruc6P3fqhfUVllWi4cck0GgWZwcsmG1dDr8W6K9lrGA1dPbXoOns1B l58ghMGtHG7D0VlHs6SIqFmHr5kUgSQ4jJ2KZkVU8CrPBZ2HRtHQJJyjZWW2AbrE -----END RSA PRIVATE KEY-----'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "importsshkey",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Two-Factor Authentication

Authentication / Two-Factor Authentication

Return cPanel account 2FA data

This function returns the Two-Factor Authentication (2FA) configuration for a cPanel account, its email accounts, and its team user accounts.

Authorizations:
BasicAuth
query Parameters
user
required
string <username>
Example: user=example

The username for the account.

Responses

Response Schema: application/json
object

The cPanel user account that the API was called for.

object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_get_tfa_config_for_user \
  user='user'

Response samples

Content type
application/json
{
  • "data": {
    • "example": {
      • "email": {},
      • "primary_account": {
        • "secret": "QLLIU5WTY3UTJGNG"
        },
      • "team": {
        • "team_user@example": {
          • "secret": "QLLIU5WTY3UTJGNG"
          }
        }
      }
    },
  • "metadata": {
    • "command": "twofactorauth_get_tfa_config_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel account's 2FA data

This function updates the Two-Factor Authentication (2FA) configuration for the given cPanel user.

Authorizations:
BasicAuth
Request Body schema: application/json
required
additional property
object

The cPanel user account for which to set the 2FA config.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "example": {
    • "email": {},
    • "primary_account": {
      • "secret": "QLLIU5WTY3UTJGNG"
      },
    • "team": {
      • "team_user@example": {
        • "secret": "QLLIU5WTY3UTJGNG"
        }
      }
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "twofactorauth_set_tfa_config_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable 2FA

This function disables the Two-Factor Authentication (2FA) security policy on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_disable_policy

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "twofactorauth_disable_policy",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable 2FA

This function enables the Two-Factor Authentication (2FA) security policy on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_enable_policy

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "twofactorauth_enable_policy",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create a one-time authentication secret and code

This function generates a random secret and a one-time password authentication (OTP auth) URL for the user. Use the secret that this function returns and a valid verification token with WHM API 1's twofactorauth_set_tfa_config function to configure Two-Factor Authentication (2FA) on an account.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_generate_tfa_config

Response samples

Content type
application/json
{
  • "data": {
    • "otpauth_str": "otpauth://totp/Example:root?secret=CAOXW75HKYJJ6E5Y&issuer=Example",
    • "secret": "WJ73QJSKZBXCFIPZ"
    },
  • "metadata": {
    • "command": "twofactorauth_generate_tfa_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return configured issuer for current user

This function returns the currently configured issuer. The issuer appears within the authentication app.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_get_issuer

Response samples

Content type
application/json
{
  • "data": {
    • "issuer": "example.cpanel.net",
    • "system_wide_issuer": "example.cpanel.net"
    },
  • "metadata": {
    • "command": "twofactorauth_get_issuer",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return 2FA policy status

This function displays the Two-Factor Authentication (2FA) policy status on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_policy_status

Response samples

Content type
application/json
{
  • "data": {
    • "is_enabled": 1
    },
  • "metadata": {
    • "command": "twofactorauth_policy_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update 2FA issuer value

This function sets the issuer value that the system uses to generate the secret and otpurls values for Two-Factor Authentication on your accounts.

Authorizations:
BasicAuth
query Parameters
issuer
required
string
Example: issuer=hostname.example.com

The issuer's name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_set_issuer \
  issuer='hostname.example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "twofactorauth_set_issuer",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove 2FA settings

This function removes the Two-Factor Authentication (2FA) settings for one or more specified user accounts.

Note:

If you remove the 2FA settings for an account, the user must perform the setup procedure again to re-configure 2FA on the account.

Authorizations:
BasicAuth
query Parameters
user
required
string
Examples:
  • user=user-1=username1 user-2=username2 user-3=username3 - Multiple users.
  • user=example.com - A single user.

The account's username.

Note:

To remove multiple users, increment the parameter name. For example, user-1, user-2, or user-3.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_remove_user_config \
  user='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "failed": {
      • "username1": "You are not authorized to modify example",
      • "username2": "You are not authorized to modify example"
      },
    • "users_modified": [
      • "example"
      ]
    },
  • "metadata": {
    • "command": "twofactorauth_remove_user_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel accounts with 2FA enabled

This function returns a list of user-controlled accounts and whether the accounts have Two-Factor Authentication (2FA) enabled.

Authorizations:
BasicAuth
query Parameters
user
string <username>
Example: user=example

The username for a specified account.

Note:

If you do not specify a value, the function returns all user accounts.

Responses

Response Schema: application/json
object

The data that the function returns.

object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_get_user_configs

Response samples

Content type
application/json
{
  • "data": {
    • "example": {
      • "is_enabled": 0,
      • "primary_domain": "example.com"
      }
    },
  • "metadata": {
    • "command": "twofactorauth_get_user_configs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update 2FA authentication secret and code

This function sets the secret and the authentication code for Two-Factor Authentication (2FA) for the root or reseller account. You can generate a random secret and an OTP authentication URL with WHM API 1's twofactorauth_generate_tfa_configorauth_generate_tfa_config function.

Authorizations:
BasicAuth
query Parameters
secret
required
string
Example: secret=WJ73QJSKZBXCFIPZ

A generated code for use with 2FA in Base32 format.

tfa_token
required
string
Example: tfa_token=227174

The time-based one-time password (TOTP) that the authentication app provides.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  twofactorauth_set_tfa_config \
  secret='WJ73QJSKZBXCFIPZ' \
  tfa_token='227174'

Response samples

Content type
application/json
{
  • "data": {
    • "success": 1
    },
  • "metadata": {
    • "command": "twofactorauth_set_tfa_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Backup Destination

Backups / Backup Destination

Add a backup destination

This function adds a backup destination.

Authorizations:
BasicAuth
query Parameters
application_key
required
string
Example: application_key=A123b45CD678e9

The application key's name.

Note:

This parameter is only valid for the Backblaze backup type.

application_key_id
required
string
Example: application_key_id=12a345B678c9

The application key ID that authenticates the Backblaze B2 account.

Note:

This parameter is only valid for the Backblaze backup type.

authtype
required
string
Possible Values: "password" "key"
Example: authtype=password

The authorization type.

  • password
  • key

Note:

This parameter is only valid for the following backup types:

  • SFTP
  • Rsync
aws_access_key_id
required
string
Example: aws_access_key_id=AKIAYLWMPOZZJCERC28Q

The Amazon S3™ Access Key ID.

Note:

This parameter is only valid for the following backup types:

  • AmazonS3
  • S3Compatible
bucket
required
string
Example: bucket=ChockFullOfNuts

The Amazon S3™ bucket.

Note:

This parameter is only valid for the following backup types:

  • AmazonS3
  • S3Compatible
bucket_id
required
string
Example: bucket_id=a12b34cd5678e9f

The bucket's ID string.

Note:

This parameter is only valid for the Backblaze backup type.

bucket_name
required
string
Example: bucket_name=ChockFullOfNuts

The bucket's name.

Note:

This parameter is only valid for the Backblaze backup type.

client_id
required
string
Example: client_id=aBcdeFgHIjK123

The Google Drive client ID.

Note:

This parameter is only valid for the GoogleDrive backup type.

client_secret
required
string
Example: client_secret=aBcde123FgHIjK456

The Google Drive client secret.

Note:

This parameter is only valid for the GoogleDrive backup type.

disabled
required
integer
Possible Values: 0 1
Example: disabled=0

Whether to disable the backup destination.

  • 1 — Disable the backup destination.
  • 0 — Enable the backup destination.
folder
string
Default: ""
Example: folder=subfolder

The path to the backups directory on the remote server.

Note:

This parameter is only valid for the following backup types:

  • AmazonS3
  • GoogleDrive
  • S3Compatible
host
required
string <hostname>
Example: host=backups.example.com

The remote server's hostname.

Note:

This parameter is only valid for the following backup types:

  • Custom
  • FTP
  • SFTP
  • Rsync
  • WebDAV
  • S3Compatible
mount
integer
Default: 0
Possible Values: 0 1
Example: mount=1

Whether the path is mounted.

  • 1 — The path is mounted.
  • 0 — The path is not mounted.

Note:

This parameter is only valid for the Local backup type.

name
required
string
Example: name=destination_name

The backup destination's name.

no_mount_fail
integer
Default: 0
Possible Values: 0 1
Example: no_mount_fail=1

Whether to fail the backup attempt if the mount fails.

  • 1 — Fail the backup attempt.
  • 0 — Do not fail the backup attempt.

Note:

This parameter is only valid for the Local backup type.

only_used_for_logs
integer
Default: 0
Possible Values: 0 1
Example: only_used_for_logs=1

Whether to use this transport only for logs.

  • 1 — This destination will be skipped for regular backups.
  • 0 — Both log and regular backups will be uploaded.

This setting defaults to 0. The only time log files get their own backup is via scripts/remote_log_transfer

passive
integer
Default: 0
Possible Values: 0 1
Example: passive=1

Whether to use passive FTP.

  • 1 — Use passive FTP.
  • 0 — Use active FTP.

Note:

This parameter is only valid for the FTP backup type.

passphrase
string
Default: null
Example: passphrase=123456luggage

The private key file's passphrase, if the authtype parameter is the key value.

Note:

This parameter is only valid for the following backup types:

  • SFTP
  • Rsync
password
required
string
Example: password=123456luggage

The remote server account's password or secret access key.

Note:

This parameter is only valid for the following backup types:

  • AmazonS3
  • Custom
  • FTP
  • SFTP
  • Rsync
  • WebDAV
  • S3Compatible
path
string
Default: null
Example: path=backups

The path to the backups directory on the remote server.

  • This parameter is required for the Local backup type.
  • If you do not use this parameter, the system will not set a value.

Note:

This parameter is only valid for the following backup types:

  • Backblaze
  • Custom
  • Local
  • FTP
  • SFTP
  • Rsync
  • WebDAV
port
integer [ 1 .. 65535 ]
Example: port=21

The TCP port to use.

Note:

  • This parameter defaults to the standard port used by the queried backup type parameter.
  • This parameter is only valid for the following backup types:
    • FTP
    • SFTP
    • Rsync
    • WebDAV
privatekey
string
Default: null
Example: privatekey=/home/backups/key

The file path to the private key file, if the authtype parameter is the key value.

Note:

This parameter is only valid for the following backup types:

  • SFTP
  • Rsync
script
required
string
Example: script=/home/backups/beammeupscotty.pl

The absolute file path to the user-supplied transport solution script.

Note:

This parameter is only valid for the Custom backup type.

ssl
integer
Default: 0
Possible Values: 0 1
Example: ssl=1

Whether to use SSL.

  • 1 — Use SSL.
  • 0 — Do not use SSL.

Note:

This parameter is only valid for the WebDAV backup type.

timeout
integer
Example: timeout=30

The session timeout, measured in seconds.

Note:

  • This parameter is not valid for the Local backup type parameter.
  • The default value depends on the type parameter's value.
type
required
string
Possible Values: "Custom" "FTP" "Local" "SFTP" "WebDAV" "AmazonS3" "Rsync" "GoogleDrive" "S3Compatible" "Backblaze"
Example: type=Local

The type of backup destination.

  • Custom
  • FTP
  • Local
  • SFTP
  • WebDAV
  • AmazonS3
  • Rsync
  • GoogleDrive
  • S3Compatible
  • Backblaze

Note:

This value determines which parameters you can use with the function.

Warning:

Use any of these encrypted connections to transfer system backup files:

  • Amazon S3™
  • Backblaze
  • GoogleDrive
  • Rsync
  • S3 Compatible
  • SFTP
  • WebDAV with SSL enabled
upload_system_backup
integer
Default: 0
Possible Values: 0 1
Example: upload_system_backup=1

Whether to upload system backups.

  • 1 — Upload system backups.
  • 0 — Do not upload system backups.
username
required
string <username>
Example: username=username

The remote server account's username.

Note:

This parameter is only valid for the following backup types:

  • Custom
  • FTP
  • SFTP
  • Rsync
  • WebDAV

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_destination_add \
  name='destination_name' \
  type='Local' \
  disabled='0' \
  bucket='ChockFullOfNuts' \
  aws_access_key_id='AKIAYLWMPOZZJCERC28Q' \
  password='123456luggage' \
  application_key='A123b45CD678e9' \
  application_key_id='12a345B678c9' \
  bucket_id='a12b34cd5678e9f' \
  bucket_name='ChockFullOfNuts' \
  script='/home/backups/beammeupscotty.pl' \
  host='backups.example.com' \
  username='username' \
  client_id='aBcdeFgHIjK123' \
  client_secret='aBcde123FgHIjK456' \
  authtype='password'

Response samples

Content type
application/json
{
  • "data": {
    • "id": "PhAxIoLSdIkCI40q9vWS4BYy"
    },
  • "metadata": {
    • "command": "backup_destination_add",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete a backup destination

This function removes a backup destination from the backup configuration file.

Authorizations:
BasicAuth
query Parameters
id
required
string
Example: id=11111111

The destination's ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_destination_delete \
  id='11111111'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "backup_destination_delete",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return a list of backup destinations

This function lists backup destinations.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_destination_list

Response samples

Content type
application/json
{
  • "data": {
    • "destination_list": [
      • {
        • "disable_reason": "Could not list files in destination: example",
        • "disabled": 0,
        • "id": "0W1ei2rd3A4lI5sT6he7Be8st",
        • "name": "destination_name",
        • "type": "Local",
        • "aws_access_key_id": "s123456789",
        • "bucket": "ChockFullOfNuts",
        • "folder": "subfolder",
        • "timeout": 300
        }
      ]
    },
  • "metadata": {
    • "command": "backup_destination_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return a backup destination's settings

Use this function to obtain a backup destination's settings.

Authorizations:
BasicAuth
query Parameters
id
required
string
Example: id=0W1ei2rd3A4lI5sT6he7Be8st

The backup destination's ID.

Responses

Response Schema: application/json
any (BackupDestinationGetResponse)
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_destination_get \
  id='0W1ei2rd3A4lI5sT6he7Be8st'

Response samples

Content type
application/json
Example
{
  • "data": {
    • "aws_access_key_id": "access-key-id",
    • "bucket": "s3-bucket-brigade",
    • "disabled": 0,
    • "folder": "",
    • "id": "Sr1ThYOnnBIXUupTcSBYQywk",
    • "name": "Amazon S3",
    • "timeout": 30,
    • "type": "AmazonS3",
    • "upload_system_backup": 0
    },
  • "metadata": {
    • "command": "backup_destination_get",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Google Drive™ client ID credentials

This function returns whether a Google Drive™ client ID credential file exists.

Authorizations:
BasicAuth
query Parameters
client_id
required
string
Example: client_id=aBcdeFgHIjK123

The user's Google Drive client ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_does_client_id_have_google_credentials \
  client_id='aBcdeFgHIjK123'

Response samples

Content type
application/json
{
  • "data": {
    • "exists": 1
    },
  • "metadata": {
    • "command": "backup_does_client_id_have_google_credentials",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update backup destination settings

Use this function to edit a backup destination's settings.

Authorizations:
BasicAuth
Request Body schema: application/x-www-form-urlencoded
required

The destination settings.

aws_access_key_id
required
string

The Amazon S3 Access Key ID.

bucket
required
string

The Amazon S3™ bucket.

id
required
string

The ID of the backup destination to modify.

password
required
string

The Amazon S3 Access Key's password.

timeout
required
integer [ 30 .. 300 ]
Default: 30

The session timeout, in seconds.

disable_reason
string

An error message that explains why the backup is disabled.

disabled
integer
Possible Values: 0 1

Whether to disable the backup destination.

  • 1 — Disable the destination.
  • 0 — Enable the destination.

Note:

If you do not set this parameter, the system retains the current setting.

folder
string <path>
Default: ""

The path to the backups directory, relative to the root directory, on the remote server.

name
string

A new name for the backup destination.

Note:

If you do not set this parameter, the system retains the current setting.

only_used_for_logs
integer
Possible Values: 0 1

Whether to use this transport only for logs.

  • 1 — This destination will be skipped for regular backups.
  • 0 — Both log and regular backups will be uploaded.

This setting defaults to 0. The only time log files get their own backup is via scripts/remote_log_transfer

Note:

If you do not set this parameter, the system retains the current setting.

type
string

The type of backup destination.

Note:

If you do not set this parameter, the system retains the current setting.

Select a backup destination from the following menu to view its optional parameters:

upload_system_backup
integer
Possible Values: 0 1

Whether to upload system backups.

  • 1 — Upload.
  • 0 — Do not upload.

Note:

If you do not set this parameter, the system retains the current setting.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --input=json --output=jsonpretty \
  backup_destination_set

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "backup_destination_set",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate a backup destination

This function validates a backup destination.

Authorizations:
BasicAuth
query Parameters
disableonfail
required
integer
Possible Values: 0 1
Example: disableonfail=1

Whether to disable the backup destination if validation fails.

  • 1 — Disable.
  • 0 — Do not disable.
id
required
string
Example: id=0W1ei2rd3A4lI5sT6he7Be8st

The destination's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_destination_validate \
  id='0W1ei2rd3A4lI5sT6he7Be8st' \
  disableonfail='1'

Response samples

Content type
application/json
{
  • "data": {
    • "id": "0W1ei2rd3A4lI5sT6he7Be8st"
    },
  • "metadata": {
    • "command": "backup_destination_validate",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create Google Drive™ OAuth redirect URI

This function generates a Google Drive™ OAuth redirect URI.

Authorizations:
BasicAuth
query Parameters
client_id
required
string
Example: client_id=aBcdeFgHIjK123

The Google Drive client ID.

client_secret
required
string
Example: client_secret=aBcde123FgHIjK456

The Google Drive client secret.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_generate_google_oauth_uri \
  client_id='aBcdeFgHIjK123' \
  client_secret='aBcde123FgHIjK456'

Backup or Restore

Backups / Backup or Restore

Return backup files sent through transport

This function lists backup files that the system sent through a specified additional backup transport.

Authorizations:
BasicAuth
query Parameters
transport
string
Example: transport=nN04BhzirlJUNSLSBXSMBEYG

The transport ID.

If you do not specify this parameter, the function returns backup information for all transports.

Note:

You may obtain the IDs for all configured transports by calling WHM API 1's backup_destination_list function.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_list_transported

Response samples

Content type
application/json
{
  • "data": {
    • "remote_backups": {
      • "nN04BhzirlJUNSLSBXSMBEYG": {
        • "janedoe": [
          • "2020-08-28T00:00:00.000Z",
          • "2020-08-31T00:00:00.000Z",
          • "2020-09-02T00:00:00.000Z"
          ]
        }
      }
    },
  • "metadata": {
    • "command": "backup_list_transported",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return backup files in the local disk

This function lists backup files for the server's accounts in the local disk.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_set_list

Response samples

Content type
application/json
{
  • "data": {
    • "backup_set": { }
    },
  • "metadata": {
    • "command": "backup_set_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return backup files for the server's accounts

This function lists locally-stored and backup-destination stored backup files for the server's accounts.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_set_list_combined

Response samples

Content type
application/json
{
  • "data": {
    • "backup_set": {
      • "cpusername1": [
        • {
          • "when": "2020-01-25T00:00:00.000Z",
          • "where": "local"
          },
        • {
          • "when": "2020-01-26T00:00:00.000Z",
          • "where": "local"
          }
        ],
      • "cpusername2": [
        • {
          • "when": "2020-01-25T00:00:00.000Z",
          • "where": "local"
          },
        • {
          • "when": "2020-01-26T00:00:00.000Z",
          • "where": "local"
          }
        ]
      },
    • "destination_legend": {
      • "GLT1vFsVO8cqk2UWWFpJ9kSQ": {
        • "name": "More Backups",
        • "type": "Local"
        }
      }
    },
  • "metadata": {
    • "command": "backup_set_list_combined",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return start_background_pkgacct session state

This function returns the state of a start_background_pkgacct session.

Authorizations:
BasicAuth
query Parameters
session_id
required
string
Example: session_id=username20200323154328kDJ2Kx4xua2KtG

The start_background_pkgacct session ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_pkgacct_session_state \
  session_id='username20200323154328kDJ2Kx4xua2KtG'

Response samples

Content type
application/json
{
  • "data": {
    • "state": "COMPLETED"
    },
  • "metadata": {
    • "command": "get_pkgacct_session_state",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return users and domains with backup metadata

This function lists all users and their domains that have backup metadata.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Keys are cPanel user accounts that contain backup metadata.

object

Request samples 

whmapi1 --output=jsonpretty \
  get_users_and_domains_with_backup_metadata

Response samples

Content type
application/json
{
  • "data": {
    • "username": "example.com",
    • "username2": "example.net",
    • "username3": "example.org"
    },
  • "metadata": {
    • "command": "get_users_and_domains_with_backup_metadata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return users with backup metadata

This function lists users with backup metadata.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_users_with_backup_metadata

Response samples

Content type
application/json
{
  • "data": {
    • "accounts": [
      • "username"
      ]
    },
  • "metadata": {
    • "command": "get_users_with_backup_metadata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cparchive files list

This function lists all available cparchive files.

Note:

  • MM.DD.YYYY represents the file's date in month, date, and year format.
  • HH-MM-SS represents the file's timestamp in hour, minute, and second format.

The function checks the following filenames, where USER represents the cPanel account's filusername::

  • cpmove-USER
  • cpmove-USER.tar
  • cpmove-USER.tar.gz
  • USER.tar
  • USER.tar.gz
  • backup-{MM.DD.YYYY}{HH-MM-SS}{USER}.tar
  • backup-{MM.DD.YYYY}{HH-MM-SS}{USER}.tar.gz

The function checks for these filenames in the following locations:

  • /home
  • /home2
  • /home3
  • /root
  • /usr
  • /usr/home
  • /web
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_cparchive_files

Response samples

Content type
application/json
{
  • "data": {
    • "quickrestore_files": [
      • {
        • "file": "cpmove-username1.tar.gz",
        • "path": "/home",
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "list_cparchive_files",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Back up an account using the pkgacct script

This function backs up an account with the pkgacct script.

Note:

  • The /usr/local/cpanel/scripts/pkgacct script logs results to the /var/cpanel/pkgacct_sessions/session_id/ directory, where session_id represents the backup session's ID.
  • The target system streams the output of this function with the /usr/local/cpanel/whostmgr/docroot/cgi/live_tail_log.cgi script on the source system. Users should not directly call this script.
Authorizations:
BasicAuth
query Parameters
compressionsetting
string or null
Default: null
Value: "compress"
Example: compressionsetting=compress

Whether to compress the data in .gzip format.

  • compress - Compress the data.
  • null - Do not compress the data.
incremental
integer
Default: 0
Possible Values: 0 1
Example: incremental=1

Whether to update the destination file with any new content since the previous backup. This parameter also removes any content that no longer exists on the account. If the destination file does not exist, the function creates a new file in that location.

  • 1 — Create an incremental archive file.
  • 0 — Do not create an incremental archive file.

Note:

When you use this parameter, the system creates the backup as an uncompressed archive.

low_priority
integer
Default: 0
Possible Values: 0 1
Example: low_priority=1

Whether to run the background task with a reduced priority.

  • 1 — Run the backup as a low priority task.
  • 0 — Run the backup with normal priority.
mysqlver
string
Example: mysqlver=5.5

The minimum version of MySQL® that the system requires to restore the backed up database files.

Note:

  • You can view the server's installed version of MySQL in the /var/cpanel/cpanel.config file.
  • This parameter defaults to the current installed version of MySQL.
serialized_output
integer
Default: 0
Possible Values: 0 1
Example: serialized_output=1

Whether to encode each line of the script's output in JSON format in order to allow the live_tail_log.cgi script to stream it.

  • 1 — Serialize the output.
  • 0 — Do not serialize the output.
skipacctdb
integer
Default: 0
Possible Values: 0 1
Example: skipacctdb=1

Whether to exclude the account's databases from the cpmove archive.

  • 1 — Do not back up the account's databases.
  • 0 — Back up the account's databases.
skipapitokens
integer
Default: 0
Possible Values: 0 1
Example: skipapitokens=1

Whether to exclude the account's API tokens from the archive.

  • 1 — Do not back up the account's API tokens.
  • 0 — Back up the account's API tokens.
skipauthnlinks
integer
Default: 0
Possible Values: 0 1
Example: skipauthnlinks=1

Whether to exclude the account's external authentication credentials from the archive.

  • 1 — Do not back up the account's external authentication credentials.
  • 0 — Back up the account's external authentication credentials.
skipbwdata
integer
Default: 0
Possible Values: 0 1
Example: skipbwdata=1

Whether to exclude the account's bandwidth data from the archive.

  • 1 — Do not back up the account's bandwidth data.
  • 0 — Back up the account's data.
skipdnssec
integer
Default: 0
Possible Values: 0 1
Example: skipdnssec=1

Whether to exclude the account's DNSSEC configuration from the archive.

  • 1 — Do not back up the account's DNSSEC configuration.
  • 0 — Back up the account's DNSSEC configuration.
skipdnszones
integer
Default: 0
Possible Values: 0 1
Example: skipdnszones=1

Whether to exclude the account's DNS zone file information from the archive.

  • 1 — Do not back up the account's DNS zone file information.
  • 0 — Back up the account's DNS zone file information.
skipftpusers
integer
Default: 0
Possible Values: 0 1
Example: skipftpusers=1

Whether to exclude the account's FTP user accounts from the archive.

  • 1 — Do not back up the account's FTP user accounts.
  • 0 — Back up the account's FTP user accounts.
skiphomedir
integer
Default: 0
Possible Values: 0 1
Example: skiphomedir=1

Whether to skip the home directory's contents.

  • 1 — Do not back up the account's home directory.
  • 0 — Back up the account's home directory.
skiplinkednodes
integer
Default: 0
Possible Values: 0 1
Example: skiplinkednodes=1

Whether to exclude the account's cPanel & WHM linked server nodes configuration from the archive.

  • 1 — Do not back up the account's linked server nodes configuration.
  • 0 — Back up the account's linked server nodes configuration.
skiplogs
integer
Default: 0
Possible Values: 0 1
Example: skiplogs=1

Whether to exclude the account's log files from the archive.

  • 1 — Do not back up the account's log files.
  • 0 — Back up the account's log files.
skipresellerconfig
integer
Default: 0
Possible Values: 0 1
Example: skipresellerconfig=1

Whether to exclude the account's reseller privileges from the archive.

  • 1 — Do not back up the account's reseller privileges.
  • 0 — Back up the account's reseller privileges.
skipshell
integer
Default: 0
Possible Values: 0 1
Example: skipshell=1

Whether to exclude the account's shell information and privileges from the archive.

  • 1 — Do not back up the account's shell information and privileges.
  • 0 — Back up the account's shell information and privileges.
skipvhosttemplates
integer
Default: 0
Possible Values: 0 1
Example: skipvhosttemplates=1

Whether to exclude the account's virtual host (vhost) templates from the archive.

  • 1 — Do not back up the account's vhost templates.
  • 0 — Back up the account's vhost templates.
split
integer
Default: 0
Possible Values: 0 1
Example: split=1

Whether to create the cpmove archive in chunks.

  • 1 — Create the archive in chunks.
  • 0 — Create a single archive file.
tarroot
string
Example: tarroot=/home/user

The path to the directory in which you wish to store the cpmove archive.

Note:

This parameter defaults to /home/user, where user represents the username of the account.

use_backups
integer
Default: 0
Possible Values: 0 1
Example: use_backups=1

Whether to use the account's last known successful backup as a template when the script creates the cpmove archive, if any exist.

  • 1 — Use the account's last known successful backup as a template, if any exist.
  • 0 — Do not use the account's last known successful backup.

Note:

This parameter may reduce the amount of time that the backup process requires.

user
required
string <username>
Example: user=username

The cPanel account to back up.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_background_pkgacct \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "complete_master_error_log": "master.error_log",
    • "complete_master_log": "master.log",
    • "session_id": "example20151109162046c4xzDp55q9u4tPj"
    },
  • "metadata": {
    • "command": "start_background_pkgacct",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return start_background_pkgacct session log file

This function returns the contents of a start_background_pkgacct session's master log file.

Authorizations:
BasicAuth
query Parameters
session_id
required
string
Example: session_id=username20200323154328kDJ2Kx4xua2KtG

The start_background_pkgacct session ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_pkgacct_master_log \
  session_id='username20200323154328kDJ2Kx4xua2KtG'

Response samples

Content type
application/json
{
  • "data": {
    • "log": "{\"contents\":\"pkgacct started.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"partial\":0,\"contents\":\"pkgacct version 10 - user : username - tarball: 1 - target mysql : 5.7 - split: 1 - incremental: 0 - homedir: 0 - mailman: 1 - backup: 0 - archive version: 4 - running with uid 0\\n\",\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"partial\":0,\"contents\":\"pkgacct using ''/usr/bin/pigz -6 --processes 1 --blocksize 4096 --rsyncable'' to compress archives\\n\"}\n{\"type\":\"out\",\"indent\":0,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"contents\":\"pkgacct -- attempting to use daily backup to create an account package\\n\",\"pid\":4073}\n{\"indent\":0,\"contents\":\"pkgacct -- could not use daily backup because no daily incremental backup for user username can be found ( check if daily incremental backups are enabled )\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"contents\":\"pkgacct working dir : /home/cpmove-username\",\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\"Copying Reseller Config...\",\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"partial\":1}\n{\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"partial\":0,\"contents\":\"Done\\n\",\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"partial\":1,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"contents\":\"Copying Suspension Info (if needed)...\"}\n{\"type\":\"out\",\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"partial\":0,\"contents\":\"Done\\n\",\"pid\":4073,\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\"Copying installed SSL certificates and keys...\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:28 -0500\"}\n{\"type\":\"out\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:28 -0500\",\"contents\":\"Performing ApacheTLS component....\",\"pid\":4073,\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Completed ApacheTLS component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073}\n{\"type\":\"out\",\"pid\":4073,\"contents\":\"Done\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"indent\":0}\n{\"indent\":0,\"contents\":\"Copying DKIM keys....\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Done\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073}\n{\"type\":\"out\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"contents\":\"Copying Bandwidth Data....\",\"pid\":4073,\"indent\":0}\n{\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Performing Bandwidth component....\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"contents\":\"Summary databases \",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"indent\":0}\n{\"type\":\"out\",\"contents\":\" done!\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"indent\":0}\n{\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Completed Bandwidth component.\\n\",\"type\":\"out\"}\n{\"indent\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Done\\n\",\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"contents\":\"Copying Dns Zones....\",\"pid\":4073,\"indent\":0}\n{\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"contents\":\"...username.tld...\",\"type\":\"out\"}\n{\"indent\":0,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Done\\n\",\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\"Copying Mail files....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1}\n{\"indent\":0,\"contents\":\"Done\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"type\":\"out\"}\n{\"contents\":\"Copying proftpd file....\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"contents\":\"Done\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"type\":\"out\"}\n{\"indent\":0,\"contents\":\"Performing Logs component....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"contents\":\"...log file sizes [0 byte(s)]...\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\"...username.tld-ssl_log...\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1}\n{\"contents\":\"...username.tld...\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"contents\":\"Completed Logs component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Copy userdata...\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"pid\":4073}\n{\"contents\":\"Done\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"contents\":\"Copy custom virtualhost templates...\",\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Done\\n\",\"pid\":4073}\n{\"type\":\"out\",\"contents\":\"Copying mailman lists and archives....\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\"Done copying mailman lists and archives.\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1}\n{\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Performing Postgresql component....\",\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"contents\":\"Completed Postgresql component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Performing Mysql component....\",\"indent\":0}\n{\"contents\":\"Determining mysql dbs...\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"contents\":\"...mysqldump version: 5.7.27...\",\"indent\":0}\n{\"type\":\"out\",\"contents\":\"...mysql version: 5.7...\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Saving mysql privs...\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"pid\":4073}\n{\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Done\\n\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"contents\":\"Storing MySQL databases...\\n\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Done\\n\",\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"...Done\\n\"}\n{\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"...Done\\n\",\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Completed Mysql component.\\n\"}\n{\"indent\":0,\"contents\":\"Performing MysqlRemoteNotes component....\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"type\":\"out\"}\n{\"indent\":0,\"contents\":\"Completed MysqlRemoteNotes component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"type\":\"out\"}\n{\"pid\":4073,\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Copying cpuser file.......\",\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Done\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073}\n{\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Copying crontab file.......\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"contents\":\"Done\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"contents\":\"Performing Quota component....\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"indent\":0}\n{\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Completed Quota component.\\n\",\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Performing Integration component....\",\"pid\":4073}\n{\"pid\":4073,\"contents\":\"Completed Integration component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"contents\":\"Performing AuthnLinks component....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"contents\":\"Completed AuthnLinks component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Performing APITokens component....\"}\n{\"indent\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Completed APITokens component.\\n\",\"pid\":4073,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Performing DNSSEC component....\",\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Completed DNSSEC component.\\n\",\"pid\":4073}\n{\"type\":\"out\",\"indent\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Performing Custom component....\",\"pid\":4073}\n{\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"No custom components to perform.\\n\",\"indent\":0,\"type\":\"out\"}\n{\"contents\":\"Completed Custom component.\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\"Performing AutoSSL component....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0}\n{\"indent\":0,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Completed AutoSSL component.\\n\",\"pid\":4073,\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"contents\":\"Storing Subdomains....\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Done\\n\",\"pid\":4073}\n{\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Storing Parked Domains....\\n\",\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"contents\":\"Done\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"indent\":0}\n{\"indent\":0,\"contents\":\"Storing Addon Domains....\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"type\":\"out\"}\n{\"contents\":\"Performing Password component....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Completed Password component.\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073}\n{\"type\":\"out\",\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Performing DigestShadow component....\",\"indent\":0}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Completed DigestShadow component.\\n\"}\n{\"type\":\"out\",\"indent\":0,\"contents\":\"Copying shell.......\",\"partial\":1,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073}\n{\"type\":\"out\",\"indent\":0,\"pid\":4073,\"contents\":\&qquot;Done\\n\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0}\n{\"indent\":0,\"pid\":4073,\"contents\":\"Performing PublicContact component....\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Completed PublicContact component.\\n\",\"type\":\"out\"}\n{\"contents\":\"Performing MailLimits component....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"Completed MailLimits component.\\n\",\"pid\":4073,\"type\":\"out\"}\n{\"contents\":\"Performing LinkedNodes component....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Completed LinkedNodes component.\\n\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"pid\":4073,\"contents\":\"Creating Archive ....\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":1,\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"\\n\",\"type\":\"out\"}\n{\"contents\":\"splitpkgacctfile is: /home/cpmove-username-split/cpmove-username.tar.gz.part00001\\n\",\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"pid\":4073,\"indent\":0,\"type\":\"out\"}\n{\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"\\nsplitmd5sum is: e06a2d1f0cb499cb1d5ff15116f02df4\\n\",\"indent\":0,\"type\":\"out\"}\n{\"type\":\"out\",\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"\\nsplitsize is: 7275\\n\",\"indent\":0}\n{\"type\":\"out\",\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"Done\\n\",\"pid\":4073,\"indent\":0}\n{\"pid\":4073,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"partial\":0,\"contents\":\"\\nmysqlsize is: 0\\n\",\"indent\":0,\"type\":\"out\"}\n{\"indent\":0,\"pid\":4073,\"partial\":0,\"timestamp\":\"2020-03-23 10:43:29 -0500\",\"contents\":\"pkgacct completed\\n\",\"type\":\"out\"}"
    },
  • "metadata": {
    • "command": "fetch_pkgacct_master_log",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return backup transport events' status

This function retrieves the status of any backup transport events on the account.

Authorizations:
BasicAuth
query Parameters
state
string
Possible Values: "completed" "failed" "pending" "running"
Example: state=running

That transport's current state. If you do not specify this parameter, the function returns the status of all transports on the account.

  • completed
  • failed
  • pending
  • running
transport_id
string
Example: transport_id=transportname

The transport's identification (ID). If you do not specify this parameter, the function returns all transports on the account.

Note:

You can use this parameter or the transport_name parameter.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_get_transport_status

Response samples

Content type
application/json
{
  • "data": {
    • "pages": 3,
    • "transport_status": [
      • {
        • "date": "2019-08-30T00:00:00.000Z",
        • "end_timestamp": "2019-08-30T02:04:06.000Z",
        • "start_timestamp": "2019-08-30T02:04:08.000Z",
        • "status": "running",
        • "transport": "transportname",
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "backup_get_transport_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore one cPanel account from a backup

This function performs a full restoration of a single cPanel account from a cpmove tarball.

Authorizations:
BasicAuth
query Parameters
cpmovepath
required
string
Example: cpmovepath=/home/cpmove-newacct.tar.gz

A filepath that contains the account's cpmove tarball or the directory path that contains the extracted cpmove tarball.

Note:

You can use the pkgacct script to create a cpmove tarball.

dedicated_ip
integer
Default: 0
Possible Values: 0 1
Example: dedicated_ip=0

Whether to assign the account a dedicated IP address.

  • 1 - Assign a dedicated IP address.

  • 0 - Do not assign a dedicated IP address.

    Note:

The system must have an available IP address.

delete_archive
integer
Default: 0
Possible Values: 0 1
Example: delete_archive=0

Whether to delete the cpmove tarball or extracted directory, given in the cpmovepath parameter, after the system completes the account restoration.

  • 1 - Delete the cpmove tarball or extracted directory.
  • 0 - Do not delete the cpmove tarball or extracted directory.
string or string
Default: ".existing"

The server on which the account's email will reside after the system completes the transfer.

  • .local - Use the local server the account is being restored on.
  • .existing - Use the server location defined in the account's backup data. The system defaults to the .local parameter if this does not work.
  • ALIAS - Use a cPanel & WHM linked node server's alias. For example, the example-alias for the servernode.example.com domain. The system defaults to the .local parameter if this does not work.
overwrite
integer
Default: 0
Possible Values: 0 1
Example: overwrite=1

Whether to overwrite an existing account on the server, if one exists.

  • 1 - Overwrite an existing account.
  • 0 - Do not overwrite an existing account on the server.
restricted
integer
Default: 0
Possible Values: 0 1
Example: restricted=0

Whether to perform a restricted restore for the account. The system will perform security checks on the backup file. If you do not trust the source of the account backup with root access to your server, use this parameter to protect your server.

  • 1 - Perform a restricted restore.
  • 0 - Do not perform a restricted restore.

Important:

  • This parameter is experimental. Do not consider it as an effective security control. For more information, read our restricted restore documentation.
  • If the account owns PostgreSQL® databases, your server must use PostgreSQL version 8.4 or newer.
  • This parameter only allows restored accounts to use the noshell or jailshell environments. If the account uses a different shell, the system will set the account to use the noshell environment.
  • If there is an issue with the backup file, the system will not restore that part of the backup file. It will also adds a warning to the log file.
update_a_records
string
Default: "all"
Possible Values: "all" "basic"
Example: update_a_records=all

Whether to perform one of the following actions to the account's A records:

  • all - Replace all instances of the original server's IP address with the new server's IP address.
  • basic - Only replace the cPanel provided A records.
username
string <username>
Example: username=example

The username to give to the restored cPanel account. This will default to the username provided in the backup files.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_local_cpmove_restore \
  cpmovepath='/home/cpmove-newacct.tar.gz'

Response samples

Content type
application/json
{
  • "data": {
    • "transfer_session_id": "example202003301756425ugO"
    },
  • "metadata": {
    • "command": "start_local_cpmove_restore",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Backup Settings

Backups / Backup Settings

Update the system's backup configuration

This function configures a server's backup system. The system saves these settings in the /var/cpanel/backups/config file.

Authorizations:
BasicAuth
query Parameters
backup_daily_enable
integer
Default: 1
Possible Values: 0 1
Example: backup_daily_enable=1

Whether to enable daily backups.

  • 1 — Enable.
  • 0 — Disable.
backup_daily_retention
integer >= 0
Default: 5
Example: backup_daily_retention=5

The number of daily backups to retain.

backup_monthly_dates
integer [ 1 .. 31 ]
Default: 1
Example: backup_monthly_dates=1

Which days of the month to run backups.

Note:

To add multiple days, use a comma-delimited list.

backup_monthly_enable
integer
Default: 0
Possible Values: 0 1
Example: backup_monthly_enable=0

Whether to enable monthly backups.

  • 1 — Enable.
  • 0 — Disable.
backup_monthly_retention
integer >= 0
Default: 1
Example: backup_monthly_retention=5

The number of monthly backups to retain.

backup_weekly_day
integer [ 1 .. 6 ]
Default: 0
Example: backup_weekly_day=1

Which day of the week to run weekly backups.

  • 0 — Sunday.
  • 1 — Monday.
  • 2 — Tuesday.
  • 3 — Wednesday.
  • 4 — Thursday.
  • 5 — Friday.
  • 6 — Saturday.
backup_weekly_enable
integer
Default: 0
Possible Values: 0 1
Example: backup_weekly_enable=0

Whether to enable weekly backups.

  • 1 — Enable.
  • 0 — Disable.
backup_weekly_retention
integer >= 0
Default: 4
Example: backup_weekly_retention=4

The number of weekly backups to retain.

backupaccts
integer
Default: 1
Possible Values: 0 1
Example: backupaccts=1

Whether to back up cPanel user accounts.

  • 1 — Back up.
  • 0 — Do not back up.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

backupbwdata
integer
Default: 1
Possible Values: 0 1
Example: backupbwdata=1

Whether to back up bandwidth tracking data.

  • 1 — Back up.
  • 0 — Do not back up.
backupdays
string [ 0 .. 6 ]
Default: "0,2,4,6"
Example: backupdays=0,1,2,3,4,5,6

Which days of the week to run daily backups.

  • 0 — Sunday.
  • 1 — Monday.
  • 2 — Tuesday.
  • 3 — Wednesday.
  • 4 — Thursday.
  • 5 — Friday.
  • 6 — Saturday.

Note:

For multiple days, use a comma-delimited list.

backupdir
string
Default: "/backup"
Example: backupdir=/backup

The primary backup directory.

backupenable
integer
Default: 0
Possible Values: 0 1
Example: backupenable=0

Whether to enable backups.

  • 1 — Enable.
  • 0 — Disable.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

backupfiles
integer
Default: 1
Possible Values: 0 1
Example: backupfiles=1

Whether to back up system files.

  • 1 — Back up.
  • 0 — Do not back up.
backuplogs
integer
Default: 0
Possible Values: 0 1
Example: backuplogs=0

Whether to back up the error logs.

  • 1 — Back up.
  • 0 — Do not back up.
backupmount
integer
Default: 0
Possible Values: 0 1
Example: backupmount=0

Whether to mount a backup partition.

  • 1 — Mount.
  • 0 — Do not mount.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

backupsuspendedaccts
integer
Default: 0
Possible Values: 0 1
Example: backupsuspendedaccts=0

Whether to back up suspended accounts.

  • 1 — Back up.
  • 0 — Do not back up.
backuptype
string
Default: "compressed"
Possible Values: "compressed" "uncompressed" "incremental"
Example: backuptype=compressed

The type of backup to create.

  • compressed
  • uncompressed
  • incremental
check_min_free_space
integer
Default: 1
Possible Values: 0 1
Example: check_min_free_space=1

Whether to ensure that the destination server possesses the minimum free disk space available.

  • 1 — Check the free disk space on the destination server.
  • 0 — Do not check the free disk space on the destination server.
disable_metadata
integer
Default: 0
Possible Values: 0 1
Example: disable_metadata=0

Whether the backup system will create metadata when a backup runs.

  • 1 — Disable metadata creation.
  • 0 — Enable metadata creation.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

errorthreshhold
integer >= 0
Default: 3
Example: errorthreshhold=3

The number of times that the system will try to use the additional backup destination.

force_prune_daily
integer
Default: 0
Possible Values: 0 1
Example: force_prune_daily=0

Whether to strictly enforce the value of the backup_daily_retention parameter.

  • 1 — Strictly enforce the backup_daily_retention parameter.
  • 0 — Only enforce the backup_daily_retention parameter after a successful complete backup.
force_prune_monthly
integer
Default: 0
Possible Values: 0 1
Example: force_prune_monthly=0

Whether to strictly enforce the value of the backup_monthly_retention parameter.

  • 1 — Strictly enforce the backup_monthly_retention parameter.
  • 0 — Only enforce the backup_monthly_retention parameter after a successful complete backup.
force_prune_weekly
integer
Default: 0
Possible Values: 0 1
Example: force_prune_weekly=0

Whether to strictly enforce the value of the backup_weekly_retention parameter.

  • 1 — Strictly enforce the backup_weekly_retention parameter.
  • 0 — Only enforce the backup_weekly_retention parameter after a successful complete backup.
gziprsyncopts
string
Default: ""
Example: gziprsyncopts=--rysncable

The gzip environment variables.

keeplocal
integer
Default: 1
Possible Values: 0 1
Example: keeplocal=1

Whether to delete backups from the local directory.

  • 1 — Delete.
  • 0 — Do not delete.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

linkdest
integer
Default: 0
Possible Values: 0 1
Example: linkdest=0

Whether to check the rsync function for hardlink support.

  • 1 — Check.
  • 0 — Do not check.
localzonesonly
integer
Default: 0
Possible Values: 0 1
Example: localzonesonly=0

Whether to use a local zone file from the /var/named/domain.tld file or the dnsadmin daemon, where domain.tld represents the target domain.

  • 1 — Use the /var/named/domain.tld file.
  • 0 — Use dnsadmin.
maximum_restore_timeout
integer >= 0
Default: 21600
Example: maximum_restore_timeout=21600

How long a restoration will attempt to run, in seconds. If the restoration does not succeed in this amount of time, it will stop.

maximum_timeout
integer >= 0
Default: 7200
Example: maximum_timeout=7200

How long a backup will attempt to run, in seconds. If the backup does not succeed in this amount of time, it will stop.

min_free_space
integer >= 0
Default: 5
Example: min_free_space=1024

The minimum amount of free disk to check for on the destination server.

Note:

If the value of the min_free_space_unit parameter is percent, the maximum value is 100.

min_free_space_unit
string
Default: "percent"
Possible Values: "MB" "percent"
Example: min_free_space_unit=MB

The units of measurement of disk space for the min_free_space return.

  • MB — Megabytes.
  • percent — Percent available.
mysqlbackup
string
Default: "accounts"
Possible Values: "accounts" "dir" "both"
Example: mysqlbackup=accounts

The backup method to use for MySQL® databases.

  • accounts — Back up databases in each account's archive.
  • dir — Back up the entire MySQL directory.
  • both — Back up databases in each account's archive and the entire MySQL directory.
postbackup
integer
Default: 0
Possible Values: 0 1
Example: postbackup=0

Whether to run the /usr/local/cpanel/scripts/postcpbackup script after the backup finishes.

  • 1 — Run.
  • 0 — Do not run.
prebackup
integer
Default: 1
Possible Values: 0 1
Example: prebackup=1

Whether to run the /usr/local/cpanel/scripts/precpbackup script before the system processes backups.

  • 1 — Run.
  • 0 — Do not run.
psqlbackup
integer
Default: 0
Possible Values: 0 1
Example: psqlbackup=0

Whether to back up PostgreSQL® databases.

  • 1 — Back up.
  • 0 — Do not back up.
remote_restore_staging_dir
string
Example: remote_restore_staging_dir=/backup

The directory that temporarily stores a remote backup's data during a backup restoration. The data is a compressed (.tar.gz) or uncompressed (.tar) account tarball.

Important:

The system restores backups one at a time. The backup staging directory must be large enough to contain the largest remote backup file that you wish to restore. For example, if you wish to restore three backups, sized 1.5 GB, 528 MB, and 950 MB each, your backup staging directory must be able to hold at least 1.5 GB.

Note:

The system empties the directory after the system restores the backup.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_config_set

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "backup_config_set",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return dates where backup files exist

This function lists the dates where backup file exists, whether stored locally or stored on remote backup destinations when local backups are disabled.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_date_list

Response samples

Content type
application/json
{
  • "data": {
    • "backup_set": [
      • "2019-02-12T00:00:00.000Z",
      • "2019-02-12T00:00:00.000Z",
      • "2019-02-12T00:00:00.000Z"
      ]
    },
  • "metadata": {
    • "command": "backup_date_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable or disable backups

This function enables and disables the backup and legacy backups.

Authorizations:
BasicAuth
query Parameters
backupversion
required
string
Possible Values: "backup" "legacy"
Example: backupversion=backup

The type of backup.

  • backup - Standard backups.
  • legacy - Legacy backups.
state
required
integer
Possible Values: 0 1
Example: state=1

Whether to enable the backup type that the backupversion parameter specifies for all users.

  • 1 - Enable.
  • 0 - Disable.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_skip_users_all \
  state='1' \
  backupversion='backup'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "backup_skip_users_all",
    • "reason": "Configuration update process started",
    • "result": 1,
    • "version": 1
    }
}

Return backup configuration status

This function checks each user's backup configuration status while the backup_skip_users_all function runs.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_skip_users_all_status

Response samples

Content type
application/json
{
  • "data": {
    • "reason": {
      • "msg": "Done",
      • "perc": 100,
      • "running": 0
      }
    },
  • "metadata": {
    • "command": "backup_skip_users_all_status",
    • "reason": "OK.",
    • "result": 1,
    • "version": 1
    }
}

Return users with a backup file

This function lists users with a backup file, stored locally or on additional backup destinations, on a specified date.

Authorizations:
BasicAuth
query Parameters
restore_point
required
string <ISO-8601 Date>
Example: restore_point=2014-10-10T00:00:00.000Z

The desired date.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_user_list \
  restore_point='2014-10-10T00:00:00.000Z'

Response samples

Content type
application/json
{
  • "data": {
    • "user": [
      • {
        • "status": "active",
        • "username": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "backup_user_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable or disable legacy backups

This function enables or disables legacy backups for a user.

Authorizations:
BasicAuth
query Parameters
legacy
integer
Default: 0
Possible Values: 0 1
Example: legacy=0

Whether the account should use the legacy backup system.

  • 1 - Use the legacy backup system.
  • 0 - Use the standard backup system.
user
required
string <username>
Example: user=username

The cPanel account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  toggle_user_backup_state \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "toggle_status": 0
    },
  • "metadata": {
    • "command": "toggle_user_backup_state",
    • "reason": "Backup state modified",
    • "result": 1,
    • "version": 1
    }
}

Return backup configuration file data

This function retrieves your backup destination configuration file data.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  backup_config_get

Response samples

Content type
application/json
{
  • "data": {
    • "backup_config": {
      • "backup_daily_enable": 1,
      • "backup_daily_retention": 5,
      • "backup_monthly_dates": "1,15,22",
      • "backup_monthly_enable": 0,
      • "backup_monthly_retention": 5,
      • "backup_weekly_day": "1,3,5",
      • "backup_weekly_enable": 0,
      • "backup_weekly_retention": 4,
      • "backupaccts": 1,
      • "backupbwdata": 1,
      • "backupdays": "0,2,4,6",
      • "backupdir": "/backup",
      • "backupenable": 1,
      • "backupfiles": 1,
      • "backuplogs": 0,
      • "backupmount": 0,
      • "backupsuspendedaccounts": 0,
      • "backuptype": "compressed",
      • "check_min_free_space": 1,
      • "disable_metadata": 0,
      • "errorthreshhold": 3,
      • "force_prune_daily": 0,
      • "force_prune_monthly": 0,
      • "force_prune_weekly": 0,
      • "gziprsyncopts": "--rysncable",
      • "keeplocal": 1,
      • "linkdest": 0,
      • "localzonesonly": 0,
      • "maximum_restore_timeout": 21600,
      • "maximum_timeout": 7200,
      • "min_free_space": 1024,
      • "min_free_space_unit": "MB",
      • "mysqlbackup": "accounts",
      • "postbackup": 0,
      • "prebackup": 1,
      • "psqlbackup": 0,
      • "remote_restore_staging_dir": "/backup"
      }
    },
  • "metadata": {
    • "command": "backup_config_get",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Legacy Migration

Backups / Legacy Migration

Migrate server to new backup system

This function converts and migrates a server from the Legacy Backup system to the Backup system.

Authorizations:
BasicAuth
query Parameters
no_convert
integer
Default: 0
Possible Values: 0 1
Example: no_convert=1

Whether to convert the server from the Legacy Backup system to the Backup system.

  • 1 — Convert.
  • 0 — Do not convert.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_and_migrate_from_legacy_config

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "convert_and_migrate_from_legacy_config",
    • "reason": "Legacy Backup configuration was renamed from /etc/cpbackup.conf to /etc/cpbackup.conf-1485958451 as a backup copy for your records.",
    • "result": 1,
    • "version": 1
    }
}

Market Integration

Commerce Integration / Market Integration

Validate login token and return access token

This function validates a login token with the cPanel Store or a cPanel Market provider, and then returns access tokens.

Authorizations:
BasicAuth
query Parameters
login_token
required
string
Example: login_token=1a676e6f-99fc-11e6-9ab6-e60a769b73bc

The login token to validate.

provider
required
string
Example: provider=cPStore

The cPanel Store or cPanel Market provider's name.

url_after_login
required
string <url>
Example: url_after_login=http://hostname.example.com/redirectionlocation.cgi?state

The location to which the cPanel Store or cPanel Market provider redirects the user's browser after they log in.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_login_token \
  provider='cPStore' \
  url_after_login='http://hostname.example.com/redirectionlocation.cgi?state' \
  login_token='1a676e6f-99fc-11e6-9ab6-e60a769b73bc'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "access_token": "b7a6f029-99fc-11e6-a0bd-87581cb027ac",
        • "refresh_token": "b7a7107f-99fc-11e6-a0bd-b46329164206"
        }
      ]
    },
  • "metadata": {
    • "command": "validate_login_token",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Product Management

cPanel Market / Product Management

Return Market providers' products adjusted prices

This function lists all available cPanel Market products from enabled providers, with the prices that the adjustments database modifies.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_adjusted_market_providers_products

Response samples

Content type
application/json
{
  • "data": {
    • "products": [
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "An extended-validated (EV) SSL certificate signed by cPanel.",
        • "display_name": "cPanel EV SSL Certificate",
        • "enabled": 1,
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": 0,
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel EV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": 209,
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "recommended": 0,
        • "requires_ip": 0,
        • "x_certificate_term": [
          • 1,
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            },
          • {
            • "description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
            • "label": "Business Category",
            • "name": "business_category",
            • "options": [
              • [
                • "b",
                • "Incorporated Business (“Private Organization”)"
                ],
              • [
                • "d",
                • "Non-incorporated Business (“Business Entity”)"
                ],
              • [
                • "c",
                • "Government Entity (“Government Entity”)"
                ]
              ],
            • "type": "choose_one"
            },
          • {
            • "is_optional": 1,
            • "label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_locality_name"
            },
          • {
            • "is_optional": 1,
            • "label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_state_or_province_name"
            },
          • {
            • "label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_country_name",
            • "type": "country_code"
            },
          • {
            • "is_optional": 1,
            • "label": "Date of Incorporation",
            • "name": "date_of_incorporation",
            • "type": "date"
            },
          • {
            • "is_optional": 1,
            • "label": "Assumed Name (DBA (Doing Business As))",
            • "name": "assumed_name"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 60,
        • "x_price_per_domain_maximum": 600,
        • "x_price_per_domain_minimum": 60,
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ev",
        • "x_warn_after": 604800
        }
      ]
    },
  • "metadata": {
    • "command": "get_adjusted_market_providers_products",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Market provider product

This function sets an attribute for a cPanel Market provider's product.

Authorizations:
BasicAuth
query Parameters
attribute
required
string
Example: attribute=price

The attribute of the cPanel Market provider's product.

Note

Attributes vary between cPanel Market providers and products.

product_id
required
string
Example: product_id=12345

The cPanel Market provider product's name.

provider
required
string
Example: provider=cPStore

The cPanel Market provider's name.

value
required
string
Example: value=6.00

The value to set for the attribute.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_market_product_attribute \
  provider='cPStore' \
  product_id='12345' \
  attribute='price' \
  value='6.00'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_market_product_attribute",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Market providers products

This function lists products available in the server's cPanel Market.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_market_providers_products

Response samples

Content type
application/json
{
  • "data": {
    • "products": [
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "An extended-validated (EV) SSL certificate signed by COMODO.",
        • "display_name": "Comodo EV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "Comodo EV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "155",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "1",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            },
          • {
            • "description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
            • "label": "Business Category",
            • "name": "business_category",
            • "options": [
              • [
                • "b",
                • "Incorporated Business (“Private Organization”)"
                ],
              • [
                • "d",
                • "Non-incorporated Business (“Business Entity”)"
                ],
              • [
                • "c",
                • "Government Entity (“Government Entity”)"
                ]
              ],
            • "type": "choose_one"
            },
          • {
            • "is_optional": 1,
            • "label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_locality_name"
            },
          • {
            • "is_optional": 1,
            • "label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_state_or_province_name"
            },
          • {
            • "label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_country_name",
            • "type": "country_code"
            },
          • {
            • "is_optional": 1,
            • "label": "Date of Incorporation",
            • "name": "date_of_incorporation",
            • "type": "date"
            },
          • {
            • "is_optional": 1,
            • "label": "Assumed Name (DBA (Doing Business As))",
            • "name": "assumed_name"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 108,
        • "x_price_per_domain_maximum": 1080,
        • "x_price_per_domain_minimum": 108,
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ev",
        • "x_warn_after": 604800
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A 2-year extended-validated (EV) SSL certificate signed by Comodo.",
        • "display_name": "2-Year Comodo EV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "Comodo EV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "261",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "2",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            },
          • {
            • "description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
            • "label": "Business Category",
            • "name": "business_category",
            • "options": [
              • [
                • "b",
                • "Incorporated Business (“Private Organization”)"
                ],
              • [
                • "d",
                • "Non-incorporated Business (“Business Entity”)"
                ],
              • [
                • "c",
                • "Government Entity (“Government Entity”)"
                ]
              ],
            • "type": "choose_one"
            },
          • {
            • "is_optional": 1,
            • "label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_locality_name"
            },
          • {
            • "is_optional": 1,
            • "label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_state_or_province_name"
            },
          • {
            • "label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_country_name",
            • "type": "country_code"
            },
          • {
            • "is_optional": 1,
            • "label": "Date of Incorporation",
            • "name": "date_of_incorporation",
            • "type": "date"
            },
          • {
            • "is_optional": 1,
            • "label": "Assumed Name (DBA (Doing Business As))",
            • "name": "assumed_name"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 216,
        • "x_price_per_domain_maximum": 2160,
        • "x_price_per_domain_minimum": 216,
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ev",
        • "x_warn_after": 604800
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "An organization-validated (OV) SSL certificate signed by COMODO.",
        • "display_name": "Comodo OV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "Comodo OV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "217",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "1",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 36,
        • "x_price_per_domain_maximum": 360,
        • "x_price_per_domain_minimum": 36,
        • "x_price_per_wildcard_domain": "150.00",
        • "x_price_per_wildcard_domain_maximum": "1500.00",
        • "x_price_per_wildcard_domain_minimum": "150.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ov",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A 2-year organization-validated (OV) SSL certificate signed by Comodo.",
        • "display_name": "2-Year Comodo OV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "Comodo OV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "253",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "2",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 72,
        • "x_price_per_domain_maximum": 720,
        • "x_price_per_domain_minimum": 72,
        • "x_price_per_wildcard_domain": "300.00",
        • "x_price_per_wildcard_domain_maximum": "3000.00",
        • "x_price_per_wildcard_domain_minimum": "300.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ov",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A domain-validated (DV) SSL certificate signed by cPanel.",
        • "display_name": "cPanel DV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel DV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "159",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "1",
          • "year"
          ],
        • "x_identity_verification": null,
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "issuance",
        • "x_price_per_domain": 9,
        • "x_price_per_domain_maximum": 30,
        • "x_price_per_domain_minimum": 3,
        • "x_price_per_wildcard_domain": "75.00",
        • "x_price_per_wildcard_domain_maximum": "750.00",
        • "x_price_per_wildcard_domain_minimum": "75.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "dv",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A 2-year domain-validated (DV) SSL certificate signed by cPanel.",
        • "display_name": "2-Year cPanel DV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel DV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "225",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "2",
          • "year"
          ],
        • "x_identity_verification": null,
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "issuance",
        • "x_price_per_domain": 18,
        • "x_price_per_domain_maximum": 60,
        • "x_price_per_domain_minimum": 6,
        • "x_price_per_wildcard_domain": "150.00",
        • "x_price_per_wildcard_domain_maximum": "1500.00",
        • "x_price_per_wildcard_domain_minimum": "150.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "dv",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "An organization-validated (OV) SSL certificate signed by cPanel.",
        • "display_name": "cPanel OV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel OV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "213",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "1",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 30,
        • "x_price_per_domain_maximum": 300,
        • "x_price_per_domain_minimum": 30,
        • "x_price_per_wildcard_domain": "99.00",
        • "x_price_per_wildcard_domain_maximum": "990.00",
        • "x_price_per_wildcard_domain_minimum": "99.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ov",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A 2-year organization-validated (OV) SSL certificate signed by cPanel.",
        • "display_name": "2-Year cPanel OV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel OV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "233",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "2",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 60,
        • "x_price_per_domain_maximum": 600,
        • "x_price_per_domain_minimum": 60,
        • "x_price_per_wildcard_domain": "198.00",
        • "x_price_per_wildcard_domain_maximum": "1980.00",
        • "x_price_per_wildcard_domain_minimum": "198.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ov",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A domain-validated (DV) SSL certificate signed by COMODO.",
        • "display_name": "Comodo DV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "Comodo DV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "151",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "1",
          • "year"
          ],
        • "x_identity_verification": null,
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "issuance",
        • "x_price_per_domain": 12,
        • "x_price_per_domain_maximum": 120,
        • "x_price_per_domain_minimum": 12,
        • "x_price_per_wildcard_domain": "99.00",
        • "x_price_per_wildcard_domain_maximum": "990.00",
        • "x_price_per_wildcard_domain_minimum": "99.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "dv",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A 2-year domain-validated (DV) SSL certificate signed by Comodo.",
        • "display_name": "2-Year Comodo DV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "Comodo DV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "245",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "2",
          • "year"
          ],
        • "x_identity_verification": null,
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "issuance",
        • "x_price_per_domain": 24,
        • "x_price_per_domain_maximum": 240,
        • "x_price_per_domain_minimum": 24,
        • "x_price_per_wildcard_domain": "198.00",
        • "x_price_per_wildcard_domain_maximum": "1980.00",
        • "x_price_per_wildcard_domain_minimum": "198.00",
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "dv",
        • "x_warn_after": 604800,
        • "x_wildcard_parent_domain_free": 1
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "An extended-validated (EV) SSL certificate signed by cPanel.",
        • "display_name": "cPanel EV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel EV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "209",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "1",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            },
          • {
            • "description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
            • "label": "Business Category",
            • "name": "business_category",
            • "options": [
              • [
                • "b",
                • "Incorporated Business (“Private Organization”)"
                ],
              • [
                • "d",
                • "Non-incorporated Business (“Business Entity”)"
                ],
              • [
                • "c",
                • "Government Entity (“Government Entity”)"
                ]
              ],
            • "type": "choose_one"
            },
          • {
            • "is_optional": 1,
            • "label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_locality_name"
            },
          • {
            • "is_optional": 1,
            • "label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_state_or_province_name"
            },
          • {
            • "label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_country_name",
            • "type": "country_code"
            },
          • {
            • "is_optional": 1,
            • "label": "Date of Incorporation",
            • "name": "date_of_incorporation",
            • "type": "date"
            },
          • {
            • "is_optional": 1,
            • "label": "Assumed Name (DBA (Doing Business As))",
            • "name": "assumed_name"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 60,
        • "x_price_per_domain_maximum": 600,
        • "x_price_per_domain_minimum": 60,
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ev",
        • "x_warn_after": 604800
        },
      • {
        • "base_name": "",
        • "billing_type": "one-time",
        • "description": "A 2-year extended-validated (EV) SSL certificate signed by cPanel.",
        • "display_name": "2-Year cPanel EV SSL Certificate",
        • "icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
        • "icon_mime_type": "image/svg+xml",
        • "license_term": "0",
        • "max_users": null,
        • "maximum_server_price": null,
        • "minimum_server_price": null,
        • "price": null,
        • "price_unit": "USD",
        • "product": "cPanel EV Certificate",
        • "product_category": "N/A",
        • "product_group": "ssl_certificate",
        • "product_id": "241",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore",
        • "requires_ip": "0",
        • "x_certificate_term": [
          • "2",
          • "year"
          ],
        • "x_identity_verification": [
          • {
            • "label": "Organization Name",
            • "name": "organizationName"
            },
          • {
            • "is_optional": 1,
            • "label": "Department Name",
            • "name": "organizationalUnitName"
            },
          • {
            • "description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
            • "is_optional": 1,
            • "label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
            • "name": "duns_number",
            • "pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
            },
          • {
            • "label": "Street Address",
            • "name": "streetAddress"
            },
          • {
            • "label": "City",
            • "name": "localityName"
            },
          • {
            • "label": "State or Province",
            • "name": "stateOrProvinceName"
            },
          • {
            • "label": "Postal Code",
            • "name": "postalCode"
            },
          • {
            • "label": "Country Code",
            • "name": "countryName",
            • "type": "country_code"
            },
          • {
            • "label": "Representative’s Given (First) Name",
            • "name": "rep_forename"
            },
          • {
            • "label": "Representative’s Surname (Last Name)",
            • "name": "rep_surname"
            },
          • {
            • "label": "Representative’s Email Address",
            • "name": "rep_email_address",
            • "type": "email"
            },
          • {
            • "description": "This should be one of the organization’s publicly-listed telephone numbers.",
            • "is_optional": 1,
            • "label": "Representative’s Telephone Number",
            • "name": "rep_telephone",
            • "type": "tel"
            },
          • {
            • "description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
            • "label": "Business Category",
            • "name": "business_category",
            • "options": [
              • [
                • "b",
                • "Incorporated Business (“Private Organization”)"
                ],
              • [
                • "d",
                • "Non-incorporated Business (“Business Entity”)"
                ],
              • [
                • "c",
                • "Government Entity (“Government Entity”)"
                ]
              ],
            • "type": "choose_one"
            },
          • {
            • "is_optional": 1,
            • "label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_locality_name"
            },
          • {
            • "is_optional": 1,
            • "label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_state_or_province_name"
            },
          • {
            • "label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
            • "name": "joi_country_name",
            • "type": "country_code"
            },
          • {
            • "is_optional": 1,
            • "label": "Date of Incorporation",
            • "name": "date_of_incorporation",
            • "type": "date"
            },
          • {
            • "is_optional": 1,
            • "label": "Assumed Name (DBA (Doing Business As))",
            • "name": "assumed_name"
            }
          ],
        • "x_max_http_redirects": 0,
        • "x_payment_trigger": "checkout",
        • "x_price_per_domain": 120,
        • "x_price_per_domain_maximum": 1200,
        • "x_price_per_domain_minimum": 120,
        • "x_ssl_per_domain_pricing": 1,
        • "x_supports_dns_dcv": 1,
        • "x_validation_type": "ev",
        • "x_warn_after": 604800
        }
      ]
    },
  • "metadata": {
    • "command": "get_market_providers_products",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Market providers' products metadata

This function lists all available cPanel Market providers' products and the attributes of each product that can be managed by an administrator.

The return list includes different attribute data depending the product_group for each product.

Product Group Attributes Returned Description
ssl_certificate SSLMarketProviderMetaData Contains additional attributes only applicable to SSL Certificates
* MarketProviderMetaData Any products not in a product_group listed above will include only these attributes.

Note:

The function does not return the product_group name.

To get the product_group name for a product_id, run WHM API 1's get_market_providers_products function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_market_providers_product_metadata

Response samples

Content type
application/json
{
  • "data": {
    • "product_metadata": [
      • {
        • "attributes": {
          • "display_name": {
            • "read_only": 1
            },
          • "enabled": {
            • "read_only": 1
            },
          • "icon": {
            • "read_only": 1
            },
          • "icon_mime_type": {
            • "read_only": 1
            },
          • "minimum_server_price": {
            • "read_only": 1
            },
          • "price": {
            • "read_only": 1
            },
          • "price_unit": {
            • "read_only": 1
            },
          • "product_description": {
            • "read_only": 1
            },
          • "product_group": {
            • "read_only": 1
            },
          • "product_id": {
            • "read_only": 1
            },
          • "recommended": {
            • "read_only": 1
            }
          },
        • "product_id": "123",
        • "provider_display_name": "cPanel Store",
        • "provider_name": "cPStore"
        }
      ]
    },
  • "metadata": {
    • "command": "get_market_providers_product_metadata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Provider Management

cPanel Market / Provider Management

Disable Market provider

This function disables a cPanel Market provider.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=cPStore

The cPanel Market provider's name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_market_provider \
  name='cPStore'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "disable_market_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable Market provider

This function enables a cPanel Market provider.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=cPStore

The cPanel Market provider's name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_market_provider \
  name='cPStore'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "enable_market_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Market providers

This function lists the available cPanel Market providers.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_market_providers_list

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "display_name": "cPanel Store",
        • "enabled": 1,
        • "even_commission_divisor": 6,
        • "name": "cPStore",
        • "supports_commission": 1
        }
      ]
    },
  • "metadata": {
    • "command": "get_market_providers_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Market provider commission contact ID

This function sets the contact ID to which a cPanel Market provider will send commission.

Authorizations:
BasicAuth
query Parameters
commission_id
required
string

The cPanel Store ID to which to send cPanel Market commissions.

provider
required
string
Example: provider=cPStore

The cPanel Market provider's name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_market_provider_commission_id \
  provider='cPStore' \
  commission_id='[email protected]'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_market_provider_commission_id",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Market providers' commission configuration

This function returns the commission configuration of all available cPanel Market providers.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_market_providers_commission_config

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "get_market_providers_commission_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Support Access

cPanel Support Tickets / Support Access

Delete Support SSH key and closed tickets

This function removes cPanel Support's SSH keys and removes closed support tickets. You can view closed support tickets in WHM's Grant cPanel Support Access interface (WHM >> Home >> Support >> Grant cPanel Support Access).

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_remove_closed?api.version=1

Response samples

Content type
application/json
{
  • "data": {
    • "chain_status": "ACTIVE",
    • "csf_wl_status": "ACTIVE",
    • "host_access_wl_status": "INACTIVE",
    • "hulk_wl_status": "ACTIVE",
    • "non_fatals": [ ],
    • "revoked_keys": 9
    },
  • "metadata": {
    • "command": "ticket_remove_closed",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create Support SSH key

This function installs an SSH key from the cPanel Customer Portal.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
secure_id
required
string
Example: secure_id=rofh411bv8

The support ticket's secure ID token.

server_num
required
integer >= 1
Example: server_num=1

The server's support ticket ID number.

ssh_username
string
Example: ssh_username=username

The username for incoming SSH connections before they escalate to the root user. If you do not specify a value, the function retrieves the user from the support ticket.

ticket_id
required
integer >= 1
Example: ticket_id=999999999

The support ticket's ID number.

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_grant?api.version=1&ticket_id=999999999&secure_id=rofh411bv8&server_num=1

Response samples

Content type
application/json
{
  • "data": {
    • "auth_status": "AUTHED",
    • "auth_time": 1477338450,
    • "chain_status": "ACTIVE",
    • "csf_wl_status": "ACTIVE",
    • "host_access_wl_status": "ACTIVE",
    • "hulk_wl_status": "ACTIVE",
    • "non_fatals": [ ],
    • "server_name": "example",
    • "server_num": 1,
    • "ssh_username": "username",
    • "ticket_id": 999999999,
    • "ticket_status": "OPEN"
    },
  • "metadata": {
    • "command": "ticket_grant",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete Support SSH key

This function removes a cPanel Customer Portal SSH key from the server.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
server_num
required
integer >= 1
Example: server_num=1

The server's ID number.

ssh_username
required
string
Example: ssh_username=username

The username for incoming SSH connections before they escalate to the root user.

ticket_id
required
integer >= 1
Example: ticket_id=999999999

The support ticket's ID number.

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_revoke?api.version=1&ticket_id=999999999&server_num=1&ssh_username=username

Response samples

Content type
application/json
{
  • "data": {
    • "chain_status": "ACTIVE",
    • "csf_wl_status": "ACTIVE",
    • "host_access_wl_status": "ACTIVE",
    • "hulk_wl_status": "ACTIVE",
    • "non_fatals": [ ],
    • "revoked_keys": 1,
    • "server_num": 2,
    • "ssh_username": "username",
    • "ticket_id": 999999999
    },
  • "metadata": {
    • "command": "ticket_revoke",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate Support SSH connection

This function initiates an SSH connection test.

Important:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
server_num
required
integer >= 1
Example: server_num=1

An integer that represents the ticket's actionable server. Increment the value by one for each server in the support ticket.

ticket_id
required
integer
Example: ticket_id=7648492

The support ticket number that other functions can use to query or make additional changes to the support ticket.

Responses

Response Schema: application/json
data
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_ssh_test_start?api.version=1&ticket_id=7648492&server_num=1

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "ticket_ssh_test_start",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate Customer Portal connection

This function verifies the connection from the cPanel Customer Portal to the server.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
server_num
required
integer >= 1
Example: server_num=2

The server's ID number.

ticket_id
required
integer >= 1
Example: ticket_id=999999999

The ticket's ID number.

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_ssh_test?api.version=1&ticket_id=999999999&server_num=2

Response samples

Content type
application/json
{
  • "data": {
    • "non_fatals": [
      • "audit_log"
      ],
    • "result": "SUCCESS"
    },
  • "metadata": {
    • "command": "ticket_ssh_test",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate Support IP addresses on firewall

This function checks whether the server's firewall whitelist correlates with the granted support tickets. You can view granted support tickets in WHM's Grant cPanel Support Access interface (WHM >> Home >> Support >> Grant cPanel Support Access).

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_whitelist_check?api.version=1

Response samples

Content type
application/json
{
  • "data": {
    • "chain_status": "ACTIVE",
    • "problem": "NO"
    },
  • "metadata": {
    • "command": "ticket_whitelist_check",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add Support IP addresses to firewall

This function adds cPanel Support's IP addresses to your server's firewall whitelist. This function is firewall-specific and does not change the cPHulk whitelist.

Note:

  • This function is not available through the command line. You must call it as a request body.
  • This function logs error messages to the /usr/local/cpanel/logs/error_log file.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_whitelist_setup?api.version=1

Response samples

Content type
application/json
{
  • "data": {
    • "chain_status": "ACTIVE"
    },
  • "metadata": {
    • "command": "ticket_whitelist_setup",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove Support IP addresses from firewall

This function removes cPanel Support's IP addresses from your server's firewall whitelist. This function is firewall-specific and does not change the cPHulk whitelist.

Note:

  • This function is not available through the command line. You must call it as a request body.
  • This function logs error messages to the /usr/local/cpanel/logs/error_log file.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_whitelist_unsetup?api.version=1

Response samples

Content type
application/json
{
  • "data": {
    • "chain_status": "INACTIVE"
    },
  • "metadata": {
    • "command": "ticket_whitelist_unsetup",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Ticket Management

cPanel Support Tickets / Ticket Management

Create initial Support ticket request

This function creates a stub ticket. The system uses the stub ticket to create a cPanel support ticket.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_create_stub_ticket?api.version=1

Response samples

Content type
application/json
{
  • "data": {
    • "secure_id": "rofh411bv8",
    • "ticket_id": 7648492
    },
  • "metadata": {
    • "command": "ticket_create_stub_ticket",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Import Technical Support Agreement text

This function retrieves the WebPros International, LLC Technical Support Agreement text and metadata about the user's agreement status from the cPanel Customer Portal.

Note:

  • This function is not available through the command line. You must call it as a request body.
  • To use this function, you must set up a cPanelID token in your current session. For more information, read our cPanelID documentation.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_get_support_agreement?api.version=1

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "ticket_get_support_agreement",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Support ticket status

This function lists all active and open support tickets from the cPanel Customer Portal.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
server_num
required
integer >= 1
Example: server_num=2

The server's ID number.

ssh_username
string
Example: ssh_username=username

The username for incoming SSH connections before they escalate to the root user. If you do not specify a value, the function will select the user from the ticket.

ticket_id
required
integer >= 1
Example: ticket_id=999999999

The ticket's ID number.

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_list?api.version=1&ticket_id=999999999&server_num=2

Response samples

Content type
application/json
{
  • "data": {
    • "auths": [
      • {
        • "servers": [
          • {
            • "auth_status": "AUTHED",
            • "auth_time": 1400603208,
            • "server_name": "My Server",
            • "server_num": 2,
            • "ssh": "10.11.12.13:22",
            • "ssh_username": "username",
            • "whm_ip": "10.11.12.13"
            }
          ],
        • "ticket_id": 999999999,
        • "ticket_status": "OPEN",
        • "ticket_subject": "Example ticket"
        }
      ],
    • "non_fatals": [ ]
    },
  • "metadata": {
    • "command": "ticket_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Import customer information from Customer Portal

This function retrieves the license holder's support-related information.

Note:

  • This function is not available through the command line. You must call it as a request body.
  • To use this function, you must set up a cPanelID token in your current session. For more information, read our cPanelID documentation.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_get_support_info?api.version=1

Response samples

Content type
application/json
{}

Enable Technical Support Agreement acceptance

This function records a user's acceptance of the Technical Support Agreement (TSA). The cPanel Customer Portal stores each record with the user's login, the date and time, and the TSA's version.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
version
required
string
Example: version=2020-04.v01.TSUPPORT

The version of the TSA that the user approved.

Responses

Response Schema: application/json
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_update_service_agreement_approval?api.version=1&version=2020-04.v01.TSUPPORT

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "ticket_update_service_agreement_approval",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate Customer Portal OAuth2 code

This function validates the OAuth2 code from the cPanel Customer Portal. After the function validates the token, the system stores it on the current session.

Note:

This function is not available through the command line. You must call it as a request body.

Authorizations:
BasicAuth
query Parameters
code
required
string
Example: code=84b1a729-63e3-11e6-a0fb-bfcf357fd76d

The code from the OAuth2 redirect. The system validates this code and exchanges it for a token.

redirect_uri
required
string
Example: redirect_uri=https://hostname.example.com:2087/

The redirect URI query argument that the system sent to the initial OAuth2 authentication endpoint.

Responses

Response Schema: application/json
object

Request samples 

https://hostname.example.com:2087/cpsess##########/json-api/ticket_validate_oauth2_code?api.version=1&code=84b1a729-63e3-11e6-a0fb-bfcf357fd76d&redirect_uri=https%3a%2f%2fhostname.example.com%3a2087%2f

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "ticket_validate_oauth2_code",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

cPCloud

cPCloud Service related WHM API 1 functions.

Customizations

The Customizations module for WHM API 1.

Retrieve customization data

This function retrieves customization data.

Customization data includes brand logos and colors.

This function is used to retrieve customization data for the Jupiter theme only.

Authorizations:
BasicAuth
query Parameters
application
required
string
Possible Values: "cpanel" "webmail"
Example: application=cpanel

The application name for the customization.

theme
required
string
Example: theme=jupiter

The theme for the customization.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  retrieve_customizations \
  application='cpanel' \
  theme='jupiter'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "retrieve_customizations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete customization data

This function deletes customization data.

Customization data includes brand logos and colors.

Server owners and resellers can supply customization data to whitelabel portions of the product or customize the cPanel experience for their users.

This function is used to delete customization data for the Jupiter theme only.

If you provide the optional path parameter, the API will removed only the specific element specified in the . separated path. See the parameter for more details.

Authorizations:
BasicAuth
query Parameters
application
required
string
Possible Values: "cpanel" "webmail"
Example: application=cpanel

The application name for the customization.

path
string
Example: path=brand.icon.description

The JSONPath expression to reach to property you want to delete. We support only the subset of JSONPath using the . style notation. There is presently no other JSONPath features supported.

theme
required
string
Example: theme=jupiter

The theme name for the customization.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_customizations \
  application='cpanel' \
  theme='jupiter'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "delete_customizations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update customization data

This function supplies branding data for a specific application and theme.

Customization data includes brand logos and colors.

This function is used to save customization data for the Jupiter theme only.

Authorizations:
BasicAuth
query Parameters
application
required
string
Possible Values: "cpanel" "webmail"
Example: application=cpanel

The application name for the customization.

required
object
Example: data={"brand":{"colors":{"accent":"#00FF00","primary":"#961218"},"favicon":"AAABAAEAICACAAEAAQAwAQAAFgAAACgAAAAgAAAAQAAAAAEAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACanZoAAAAAAP///////////////////////////AD//+Ag///AEH//gDB//4AQf/+AuCq/AfAgBwP4IA8H+BABA/gQAwH8EAGArA/AgAQPwMACD+DAAAfA+AIPwP1UBQH//gAB//8AAf//gAP//wAH//+iP//////////////////////////////////////////////////////8AP//4CD//8AQf/+AMH//gBB//4C4Kr8B8CAHA/ggDwf4EAED+BADAfwQAYCsD8CABA/AwAIP4MAAB8D4Ag/A/VQFAf/+AAH//wAB//+AA///AAf//6I///////////////////////////8=","logo":{"description":"The orange logo for cPanel.","forDarkBackground":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIwLjAuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA5NCAyMCIgc3R5bGU9ImVuYWJsZS1iYWNrZ3JvdW5kOm5ldyAwIDAgOTQgMjA7IiB4bWw6c3BhY2U9InByZXNlcnZlIj4KPHN0eWxlIHR5cGU9InRleHQvY3NzIj4KCS5zdDB7ZmlsbDojRkZGRkZGO30KPC9zdHlsZT4KPHRpdGxlPmNQYW5lbCBMb2dvIC0gV2hpdGU8L3RpdGxlPgo8ZyBpZD0iTGF5ZXJfMiI+Cgk8ZyBpZD0iTGF5ZXJfMS0yIj4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNy44LDQuOWg1LjlsLTAuOSwzLjNjLTAuMSwwLjQtMC40LDAuOC0wLjgsMS4xYy0wLjQsMC4zLTAuOCwwLjQtMS4zLDAuNEg3LjljLTAuNiwwLTEuMiwwLjItMS43LDAuNQoJCQljLTAuNSwwLjQtMC44LDAuOS0xLDEuNGMtMC4xLDAuNC0wLjEsMC45LDAsMS4zYzAuMSwwLjQsMC4zLDAuNywwLjUsMS4xYzAuMiwwLjMsMC42LDAuNiwwLjksMC43QzcsMTUsNy41LDE1LjEsNy45LDE1LjFoMS43CgkJCWMwLjMsMCwwLjYsMC4xLDAuOCwwLjRjMC4yLDAuMiwwLjMsMC41LDAuMiwwLjhsLTEsMy43SDcuNmMtMS4yLDAtMi40LTAuMy0zLjQtMC44Yy0xLTAuNS0xLjktMS4yLTIuNi0yLjEKCQkJYy0xLjQtMS44LTEuOS00LjItMS4zLTYuNGwwLjEtMC40YzAuNC0xLjYsMS40LTIuOSwyLjctMy45QzMuOCw2LDQuNSw1LjYsNS4zLDUuM0M2LjEsNS4xLDYuOSw0LjksNy44LDQuOXoiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNMTAuNywyMGw1LjEtMTguNGMwLjEtMC40LDAuNC0wLjgsMC44LTEuMUMxNywwLjEsMTcuNSwwLDE4LDBoNS40YzEuMiwwLDIuNCwwLjMsMy40LDAuOGMyLjEsMSwzLjUsMi45LDQsNQoJCQljMC4zLDEuMSwwLjIsMi4zLTAuMSwzLjRsLTAuMSwwLjRjLTAuMiwwLjgtMC42LDEuNS0xLDIuMmMtMS40LDItMy44LDMuMy02LjMsMy4zaC00LjdsMC45LTMuNGMwLjEtMC40LDAuNC0wLjgsMC44LTEuMQoJCQljMC40LTAuMywwLjgtMC40LDEuMy0wLjRoMS41YzEuMiwwLDIuMy0wLjgsMi43LTJjMC4xLTAuNCwwLjEtMC44LDAtMS4yYy0wLjEtMC40LTAuMy0wLjctMC41LTEuMWMtMC4yLTAuMy0wLjYtMC42LTAuOS0wLjcKCQkJQzI0LDUsMjMuNiw0LjksMjMuMSw0LjloLTIuOWwtMy44LDEzLjZjLTAuMSwwLjQtMC40LDAuOC0wLjgsMS4xYy0wLjQsMC4zLTAuOCwwLjQtMS4zLDAuNEgxMC43eiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00My4xLDEwLjJsMC4xLTAuM2MwLTAuMSwwLTAuMi0wLjEtMC4zYy0wLjEtMC4xLTAuMi0wLjEtMC4zLTAuMWgtOC40Yy0wLjMsMC0wLjctMC4xLTEtMC4yCgkJCWMtMC4zLTAuMS0wLjUtMC4zLTAuNy0wLjZjLTAuMi0wLjItMC4zLTAuNS0wLjQtMC44Yy0wLjEtMC4zLTAuMS0wLjcsMC0xbDAuNS0xLjloMTEuNGMwLjcsMCwxLjMsMC4xLDEuOSwwLjQKCQkJYzAuNiwwLjMsMS4xLDAuNywxLjUsMS4yYzAuNCwwLjUsMC43LDEuMSwwLjgsMS43YzAuMSwwLjYsMC4xLDEuMywwLDEuOWwtMi4xLDcuM0M0NiwxOSw0NC42LDIwLDQzLDIwbC04LjQsMAoJCQljLTEuNCwwLTIuNy0wLjYtMy42LTEuN2MtMC40LTAuNS0wLjctMS4xLTAuOC0xLjdjLTAuMi0wLjctMC4xLTEuNCwwLjEtMmwwLjEtMC40YzAuMS0wLjUsMC4zLTAuOSwwLjYtMS4zYzAuMy0wLjQsMC42LTAuNywxLTEKCQkJYzAuNC0wLjMsMC44LTAuNSwxLjMtMC43YzAuNS0wLjIsMS0wLjIsMS41LTAuMmg3LjFsLTAuNSwxLjljLTAuMSwwLjQtMC40LDAuOC0wLjgsMS4xYy0wLjQsMC4zLTAuOCwwLjQtMS4zLDAuNGgtMy4yCgkJCWMtMC4zLDAtMC41LDAuMS0wLjYsMC40Yy0wLjEsMC4yLDAsMC40LDAuMSwwLjVjMC4xLDAuMSwwLjMsMC4yLDAuNSwwLjJoNS4xYzAuMiwwLDAuNCwwLDAuNS0wLjFjMC4xLTAuMSwwLjItMC4yLDAuMy0wLjQKCQkJbDAuMS0wLjJMNDMuMSwxMC4yeiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik01OC4zLDQuOWMxLjIsMCwyLjQsMC4zLDMuNSwwLjhjMSwwLjUsMS45LDEuMiwyLjYsMi4xYzAuNywwLjksMS4yLDEuOSwxLjQsM2MwLjMsMS4xLDAuMiwyLjMtMC4xLDMuNAoJCQlsLTEuMyw0LjdjLTAuMSwwLjMtMC4zLDAuNi0wLjYsMC44Yy0wLjMsMC4yLTAuNiwwLjMtMSwwLjNINjBjLTAuNSwwLTEtMC40LTEtMC45YzAtMC4xLDAtMC4yLDAtMC4zbDEuNi01LjcKCQkJYzAuMS0wLjQsMC4xLTAuOCwwLTEuMmMtMC4xLTAuNC0wLjMtMC43LTAuNS0xLjFjLTAuMi0wLjMtMC42LTAuNi0wLjktMC43Yy0wLjQtMC4yLTAuOC0wLjMtMS4yLTAuM2gtMi45bC0yLjUsOS4xCgkJCWMtMC4xLDAuMy0wLjMsMC42LTAuNiwwLjhjLTAuMywwLjItMC42LDAuMy0xLDAuM2gtMi44Yy0wLjMsMC0wLjYtMC4xLTAuOC0wLjRjLTAuMi0wLjItMC4zLTAuNS0wLjItMC44bDMuOC0xMy45TDU4LjMsNC45eiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik03My42LDkuN2MtMC4yLDAuMi0wLjQsMC40LTAuNCwwLjZMNzIsMTQuNWMtMC4xLDAuNCwwLjEsMC44LDAuNSwwLjljMC4xLDAsMC4xLDAsMC4yLDBoMTAuOGwtMC44LDMKCQkJYy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMUM4MS41LDE5LjksODEsMjAsODAuNiwyMGgtOS44Yy0wLjcsMC0xLjMtMC4xLTEuOS0wLjRjLTAuNi0wLjMtMS4xLTAuNy0xLjUtMS4yCgkJCWMtMC40LTAuNS0wLjctMS4xLTAuOC0xLjdjLTAuMS0wLjYtMC4xLTEuMywwLjEtMS45bDEuNi01LjdjMC4yLTAuNiwwLjQtMS4yLDAuOC0xLjdjMC43LTEsMS43LTEuOCwyLjktMi4yCgkJCWMwLjYtMC4yLDEuMy0wLjMsMS45LTAuM2g2LjljMC43LDAsMS4zLDAuMSwxLjksMC40YzAuNiwwLjMsMS4xLDAuNywxLjUsMS4yQzg0LjYsNyw4NC45LDcuNiw4NSw4LjJjMC4xLDAuNiwwLjEsMS4zLTAuMSwxLjkKCQkJbC0wLjUsMS43Yy0wLjIsMC43LTAuNiwxLjQtMS4zLDEuOGMtMC42LDAuNS0xLjQsMC43LTIuMSwwLjdoLTcuOGwwLjUtMS44YzAuMS0wLjQsMC40LTAuOCwwLjgtMS4xYzAuNC0wLjMsMC44LTAuNCwxLjMtMC40SDc5CgkJCWMwLjMsMCwwLjUtMC4xLDAuNi0wLjRsMC4xLTAuNGMwLjEtMC4zLTAuMS0wLjYtMC40LTAuN2MwLDAtMC4xLDAtMC4xLDBoLTQuOEM3NCw5LjQsNzMuOCw5LjUsNzMuNiw5Ljd6Ii8+CgkJPHBhdGggY2xhc3M9InN0MCIgZD0iTTgzLjUsMjBsNS4yLTE4LjljMC4xLTAuMywwLjMtMC42LDAuNi0wLjhjMC4zLTAuMiwwLjYtMC4zLDEtMC4zSDkzYzAuMywwLDAuNiwwLjEsMC44LDAuNAoJCQlDOTQsMC42LDk0LjEsMC45LDk0LDEuMmwtMy45LDEzLjljLTAuMiwwLjctMC41LDEuNC0wLjksMmMtMC40LDAuNi0wLjksMS4xLTEuNSwxLjVjLTAuNiwwLjQtMS4yLDAuOC0xLjksMQoJCQlDODUsMTkuOSw4NC4yLDIwLDgzLjUsMjB6Ii8+Cgk8L2c+CjwvZz4KPC9zdmc+","forLightBackground":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIwLjAuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9InhMYXllcl8xIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB4PSIwcHgiIHk9IjBweCIKCSB2aWV3Qm94PSIwIDAgOTQgMjAiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDk0IDIwOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+CjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI+Cgkuc3Qwe2ZpbGw6I0ZGNkMyQzt9Cjwvc3R5bGU+Cjx0aXRsZT5jUGFuZWwgTG9nbyAtIE9yYW5nZTwvdGl0bGU+CjxnIGlkPSJ4TGF5ZXJfMiI+Cgk8ZyBpZD0ieExheWVyXzEtMiI+CgkJPHBhdGggY2xhc3M9InN0MCIgZD0iTTcuOCw0LjloNS45bC0wLjksMy4zYy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMWMtMC40LDAuMy0wLjgsMC40LTEuMywwLjRINy45Yy0wLjYsMC0xLjIsMC4yLTEuNywwLjUKCQkJYy0wLjUsMC40LTAuOCwwLjktMSwxLjRjLTAuMSwwLjQtMC4xLDAuOSwwLDEuM2MwLjEsMC40LDAuMywwLjcsMC41LDEuMWMwLjIsMC4zLDAuNiwwLjYsMC45LDAuN0M3LDE1LDcuNSwxNS4xLDcuOSwxNS4xaDEuNwoJCQljMC4zLDAsMC42LDAuMSwwLjgsMC40YzAuMiwwLjIsMC4zLDAuNSwwLjIsMC44bC0xLDMuN0g3LjZjLTEuMiwwLTIuNC0wLjMtMy40LTAuOGMtMS0wLjUtMS45LTEuMi0yLjYtMi4xCgkJCWMtMS40LTEuOC0xLjktNC4yLTEuMy02LjRsMC4xLTAuNGMwLjQtMS42LDEuNC0yLjksMi43LTMuOUMzLjgsNiw0LjUsNS42LDUuMyw1LjNDNi4xLDUuMSw2LjksNC45LDcuOCw0Ljl6Ii8+CgkJPHBhdGggY2xhc3M9InN0MCIgZD0iTTEwLjcsMjBsNS4xLTE4LjRjMC4xLTAuNCwwLjQtMC44LDAuOC0xLjFDMTcsMC4xLDE3LjUsMCwxOCwwaDUuNGMxLjIsMCwyLjQsMC4zLDMuNCwwLjhjMi4xLDEsMy41LDIuOSw0LDUKCQkJYzAuMywxLjEsMC4yLDIuMy0wLjEsMy40bC0wLjEsMC40Yy0wLjIsMC44LTAuNiwxLjUtMSwyLjJjLTEuNCwyLTMuOCwzLjMtNi4zLDMuM2gtNC43bDAuOS0zLjRjMC4xLTAuNCwwLjQtMC44LDAuOC0xLjEKCQkJYzAuNC0wLjMsMC44LTAuNCwxLjMtMC40aDEuNWMxLjIsMCwyLjMtMC44LDIuNy0yYzAuMS0wLjQsMC4xLTAuOCwwLTEuMmMtMC4xLTAuNC0wLjMtMC43LTAuNS0xLjFjLTAuMi0wLjMtMC42LTAuNi0wLjktMC43CgkJCUMyNCw1LDIzLjYsNC45LDIzLjEsNC45aC0yLjlsLTMuOCwxMy42Yy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMWMtMC40LDAuMy0wLjgsMC40LTEuMywwLjRIMTAuN3oiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDMuMSwxMC4ybDAuMS0wLjNjMC0wLjEsMC0wLjItMC4xLTAuM2MtMC4xLTAuMS0wLjItMC4xLTAuMy0wLjFoLTguNGMtMC4zLDAtMC43LTAuMS0xLTAuMgoJCQljLTAuMy0wLjEtMC41LTAuMy0wLjctMC42Yy0wLjItMC4yLTAuMy0wLjUtMC40LTAuOGMtMC4xLTAuMy0wLjEtMC43LDAtMWwwLjUtMS45aDExLjRjMC43LDAsMS4zLDAuMSwxLjksMC40CgkJCWMwLjYsMC4zLDEuMSwwLjcsMS41LDEuMmMwLjQsMC41LDAuNywxLjEsMC44LDEuN2MwLjEsMC42LDAuMSwxLjMsMCwxLjlsLTIuMSw3LjNDNDYsMTksNDQuNiwyMCw0MywyMGwtOC40LDAKCQkJYy0xLjQsMC0yLjctMC42LTMuNi0xLjdjLTAuNC0wLjUtMC43LTEuMS0wLjgtMS43Yy0wLjItMC43LTAuMS0xLjQsMC4xLTJsMC4xLTAuNGMwLjEtMC41LDAuMy0wLjksMC42LTEuM2MwLjMtMC40LDAuNi0wLjcsMS0xCgkJCWMwLjQtMC4zLDAuOC0wLjUsMS4zLTAuN2MwLjUtMC4yLDEtMC4yLDEuNS0wLjJoNy4xbC0wLjUsMS45Yy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMWMtMC40LDAuMy0wLjgsMC40LTEuMywwLjRoLTMuMgoJCQljLTAuMywwLTAuNSwwLjEtMC42LDAuNGMtMC4xLDAuMiwwLDAuNCwwLjEsMC41YzAuMSwwLjEsMC4zLDAuMiwwLjUsMC4yaDUuMWMwLjIsMCwwLjQsMCwwLjUtMC4xYzAuMS0wLjEsMC4yLTAuMiwwLjMtMC40CgkJCWwwLjEtMC4yTDQzLjEsMTAuMnoiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNTguMyw0LjljMS4yLDAsMi40LDAuMywzLjUsMC44YzEsMC41LDEuOSwxLjIsMi42LDIuMWMwLjcsMC45LDEuMiwxLjksMS40LDNjMC4zLDEuMSwwLjIsMi4zLTAuMSwzLjQKCQkJbC0xLjMsNC43Yy0wLjEsMC4zLTAuMywwLjYtMC42LDAuOGMtMC4zLDAuMi0wLjYsMC4zLTEsMC4zSDYwYy0wLjUsMC0xLTAuNC0xLTAuOWMwLTAuMSwwLTAuMiwwLTAuM2wxLjYtNS43CgkJCWMwLjEtMC40LDAuMS0wLjgsMC0xLjJjLTAuMS0wLjQtMC4zLTAuNy0wLjUtMS4xYy0wLjItMC4zLTAuNi0wLjYtMC45LTAuN2MtMC40LTAuMi0wLjgtMC4zLTEuMi0wLjNoLTIuOWwtMi41LDkuMQoJCQljLTAuMSwwLjMtMC4zLDAuNi0wLjYsMC44Yy0wLjMsMC4yLTAuNiwwLjMtMSwwLjNoLTIuOGMtMC4zLDAtMC42LTAuMS0wLjgtMC40Yy0wLjItMC4yLTAuMy0wLjUtMC4yLTAuOGwzLjgtMTMuOUw1OC4zLDQuOXoiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNzMuNiw5LjdjLTAuMiwwLjItMC40LDAuNC0wLjQsMC42TDcyLDE0LjVjLTAuMSwwLjQsMC4xLDAuOCwwLjUsMC45YzAuMSwwLDAuMSwwLDAuMiwwaDEwLjhsLTAuOCwzCgkJCWMtMC4xLDAuNC0wLjQsMC44LTAuOCwxLjFDODEuNSwxOS45LDgxLDIwLDgwLjYsMjBoLTkuOGMtMC43LDAtMS4zLTAuMS0xLjktMC40Yy0wLjYtMC4zLTEuMS0wLjctMS41LTEuMgoJCQljLTAuNC0wLjUtMC43LTEuMS0wLjgtMS43Yy0wLjEtMC42LTAuMS0xLjMsMC4xLTEuOWwxLjYtNS43YzAuMi0wLjYsMC40LTEuMiwwLjgtMS43YzAuNy0xLDEuNy0xLjgsMi45LTIuMgoJCQljMC42LTAuMiwxLjMtMC4zLDEuOS0wLjNoNi45YzAuNywwLDEuMywwLjEsMS45LDAuNGMwLjYsMC4zLDEuMSwwLjcsMS41LDEuMkM4NC42LDcsODQuOSw3LjYsODUsOC4yYzAuMSwwLjYsMC4xLDEuMy0wLjEsMS45CgkJCWwtMC41LDEuN2MtMC4yLDAuNy0wLjYsMS40LTEuMywxLjhjLTAuNiwwLjUtMS40LDAuNy0yLjEsMC43aC03LjhsMC41LTEuOGMwLjEtMC40LDAuNC0wLjgsMC44LTEuMWMwLjQtMC4zLDAuOC0wLjQsMS4zLTAuNEg3OQoJCQljMC4zLDAsMC41LTAuMSwwLjYtMC40bDAuMS0wLjRjMC4xLTAuMy0wLjEtMC42LTAuNC0wLjdjMCwwLTAuMSwwLTAuMSwwaC00LjhDNzQsOS40LDczLjgsOS41LDczLjYsOS43eiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik04My41LDIwbDUuMi0xOC45YzAuMS0wLjMsMC4zLTAuNiwwLjYtMC44YzAuMy0wLjIsMC42LTAuMywxLTAuM0g5M2MwLjMsMCwwLjYsMC4xLDAuOCwwLjQKCQkJQzk0LDAuNiw5NC4xLDAuOSw5NCwxLjJsLTMuOSwxMy45Yy0wLjIsMC43LTAuNSwxLjQtMC45LDJjLTAuNCwwLjYtMC45LDEuMS0xLjUsMS41Yy0wLjYsMC40LTEuMiwwLjgtMS45LDEKCQkJQzg1LDE5LjksODQuMiwyMCw4My41LDIweiIvPgoJPC9nPgo8L2c+Cjwvc3ZnPgo="}},"documentation":{"url":"https://hosting.com/documentation"},"help":{"url":"https://hosting.com/get-help"}}

The theme data to save.

theme
required
string
Value: "jupiter"
Example: theme=jupiter

The theme name for the customization.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_customizations \
  application='cpanel' \
  theme='jupiter' \
  data='{"brand":{"colors":{"accent":"#00FF00","primary":"#961218"},"favicon":"AAABAAEAICACAAEAAQAwAQAAFgAAACgAAAAgAAAAQAAAAAEAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACanZoAAAAAAP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FAD%2F%2F%2BAg%2F%2F%2FAEH%2F%2FgDB%2F%2F4AQf%2F%2BAuCq%2FAfAgBwP4IA8H%2BBABA%2FgQAwH8EAGArA%2FAgAQPwMACD%2BDAAAfA%2BAIPwP1UBQH%2F%2FgAB%2F%2F8AAf%2F%2FgAP%2F%2FwAH%2F%2F%2BiP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8AP%2F%2F4CD%2F%2F8AQf%2F%2BAMH%2F%2FgBB%2F%2F4C4Kr8B8CAHA%2FggDwf4EAED%2BBADAfwQAYCsD8CABA%2FAwAIP4MAAB8D4Ag%2FA%2FVQFAf%2F%2BAAH%2F%2FwAB%2F%2F%2BAA%2F%2F%2FAAf%2F%2F6I%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8%3D","logo":{"description":"The orange logo for cPanel.","forDarkBackground":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIwLjAuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA5NCAyMCIgc3R5bGU9ImVuYWJsZS1iYWNrZ3JvdW5kOm5ldyAwIDAgOTQgMjA7IiB4bWw6c3BhY2U9InByZXNlcnZlIj4KPHN0eWxlIHR5cGU9InRleHQvY3NzIj4KCS5zdDB7ZmlsbDojRkZGRkZGO30KPC9zdHlsZT4KPHRpdGxlPmNQYW5lbCBMb2dvIC0gV2hpdGU8L3RpdGxlPgo8ZyBpZD0iTGF5ZXJfMiI%2BCgk8ZyBpZD0iTGF5ZXJfMS0yIj4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNy44LDQuOWg1LjlsLTAuOSwzLjNjLTAuMSwwLjQtMC40LDAuOC0wLjgsMS4xYy0wLjQsMC4zLTAuOCwwLjQtMS4zLDAuNEg3LjljLTAuNiwwLTEuMiwwLjItMS43LDAuNQoJCQljLTAuNSwwLjQtMC44LDAuOS0xLDEuNGMtMC4xLDAuNC0wLjEsMC45LDAsMS4zYzAuMSwwLjQsMC4zLDAuNywwLjUsMS4xYzAuMiwwLjMsMC42LDAuNiwwLjksMC43QzcsMTUsNy41LDE1LjEsNy45LDE1LjFoMS43CgkJCWMwLjMsMCwwLjYsMC4xLDAuOCwwLjRjMC4yLDAuMiwwLjMsMC41LDAuMiwwLjhsLTEsMy43SDcuNmMtMS4yLDAtMi40LTAuMy0zLjQtMC44Yy0xLTAuNS0xLjktMS4yLTIuNi0yLjEKCQkJYy0xLjQtMS44LTEuOS00LjItMS4zLTYuNGwwLjEtMC40YzAuNC0xLjYsMS40LTIuOSwyLjctMy45QzMuOCw2LDQuNSw1LjYsNS4zLDUuM0M2LjEsNS4xLDYuOSw0LjksNy44LDQuOXoiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNMTAuNywyMGw1LjEtMTguNGMwLjEtMC40LDAuNC0wLjgsMC44LTEuMUMxNywwLjEsMTcuNSwwLDE4LDBoNS40YzEuMiwwLDIuNCwwLjMsMy40LDAuOGMyLjEsMSwzLjUsMi45LDQsNQoJCQljMC4zLDEuMSwwLjIsMi4zLTAuMSwzLjRsLTAuMSwwLjRjLTAuMiwwLjgtMC42LDEuNS0xLDIuMmMtMS40LDItMy44LDMuMy02LjMsMy4zaC00LjdsMC45LTMuNGMwLjEtMC40LDAuNC0wLjgsMC44LTEuMQoJCQljMC40LTAuMywwLjgtMC40LDEuMy0wLjRoMS41YzEuMiwwLDIuMy0wLjgsMi43LTJjMC4xLTAuNCwwLjEtMC44LDAtMS4yYy0wLjEtMC40LTAuMy0wLjctMC41LTEuMWMtMC4yLTAuMy0wLjYtMC42LTAuOS0wLjcKCQkJQzI0LDUsMjMuNiw0LjksMjMuMSw0LjloLTIuOWwtMy44LDEzLjZjLTAuMSwwLjQtMC40LDAuOC0wLjgsMS4xYy0wLjQsMC4zLTAuOCwwLjQtMS4zLDAuNEgxMC43eiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00My4xLDEwLjJsMC4xLTAuM2MwLTAuMSwwLTAuMi0wLjEtMC4zYy0wLjEtMC4xLTAuMi0wLjEtMC4zLTAuMWgtOC40Yy0wLjMsMC0wLjctMC4xLTEtMC4yCgkJCWMtMC4zLTAuMS0wLjUtMC4zLTAuNy0wLjZjLTAuMi0wLjItMC4zLTAuNS0wLjQtMC44Yy0wLjEtMC4zLTAuMS0wLjcsMC0xbDAuNS0xLjloMTEuNGMwLjcsMCwxLjMsMC4xLDEuOSwwLjQKCQkJYzAuNiwwLjMsMS4xLDAuNywxLjUsMS4yYzAuNCwwLjUsMC43LDEuMSwwLjgsMS43YzAuMSwwLjYsMC4xLDEuMywwLDEuOWwtMi4xLDcuM0M0NiwxOSw0NC42LDIwLDQzLDIwbC04LjQsMAoJCQljLTEuNCwwLTIuNy0wLjYtMy42LTEuN2MtMC40LTAuNS0wLjctMS4xLTAuOC0xLjdjLTAuMi0wLjctMC4xLTEuNCwwLjEtMmwwLjEtMC40YzAuMS0wLjUsMC4zLTAuOSwwLjYtMS4zYzAuMy0wLjQsMC42LTAuNywxLTEKCQkJYzAuNC0wLjMsMC44LTAuNSwxLjMtMC43YzAuNS0wLjIsMS0wLjIsMS41LTAuMmg3LjFsLTAuNSwxLjljLTAuMSwwLjQtMC40LDAuOC0wLjgsMS4xYy0wLjQsMC4zLTAuOCwwLjQtMS4zLDAuNGgtMy4yCgkJCWMtMC4zLDAtMC41LDAuMS0wLjYsMC40Yy0wLjEsMC4yLDAsMC40LDAuMSwwLjVjMC4xLDAuMSwwLjMsMC4yLDAuNSwwLjJoNS4xYzAuMiwwLDAuNCwwLDAuNS0wLjFjMC4xLTAuMSwwLjItMC4yLDAuMy0wLjQKCQkJbDAuMS0wLjJMNDMuMSwxMC4yeiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik01OC4zLDQuOWMxLjIsMCwyLjQsMC4zLDMuNSwwLjhjMSwwLjUsMS45LDEuMiwyLjYsMi4xYzAuNywwLjksMS4yLDEuOSwxLjQsM2MwLjMsMS4xLDAuMiwyLjMtMC4xLDMuNAoJCQlsLTEuMyw0LjdjLTAuMSwwLjMtMC4zLDAuNi0wLjYsMC44Yy0wLjMsMC4yLTAuNiwwLjMtMSwwLjNINjBjLTAuNSwwLTEtMC40LTEtMC45YzAtMC4xLDAtMC4yLDAtMC4zbDEuNi01LjcKCQkJYzAuMS0wLjQsMC4xLTAuOCwwLTEuMmMtMC4xLTAuNC0wLjMtMC43LTAuNS0xLjFjLTAuMi0wLjMtMC42LTAuNi0wLjktMC43Yy0wLjQtMC4yLTAuOC0wLjMtMS4yLTAuM2gtMi45bC0yLjUsOS4xCgkJCWMtMC4xLDAuMy0wLjMsMC42LTAuNiwwLjhjLTAuMywwLjItMC42LDAuMy0xLDAuM2gtMi44Yy0wLjMsMC0wLjYtMC4xLTAuOC0wLjRjLTAuMi0wLjItMC4zLTAuNS0wLjItMC44bDMuOC0xMy45TDU4LjMsNC45eiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik03My42LDkuN2MtMC4yLDAuMi0wLjQsMC40LTAuNCwwLjZMNzIsMTQuNWMtMC4xLDAuNCwwLjEsMC44LDAuNSwwLjljMC4xLDAsMC4xLDAsMC4yLDBoMTAuOGwtMC44LDMKCQkJYy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMUM4MS41LDE5LjksODEsMjAsODAuNiwyMGgtOS44Yy0wLjcsMC0xLjMtMC4xLTEuOS0wLjRjLTAuNi0wLjMtMS4xLTAuNy0xLjUtMS4yCgkJCWMtMC40LTAuNS0wLjctMS4xLTAuOC0xLjdjLTAuMS0wLjYtMC4xLTEuMywwLjEtMS45bDEuNi01LjdjMC4yLTAuNiwwLjQtMS4yLDAuOC0xLjdjMC43LTEsMS43LTEuOCwyLjktMi4yCgkJCWMwLjYtMC4yLDEuMy0wLjMsMS45LTAuM2g2LjljMC43LDAsMS4zLDAuMSwxLjksMC40YzAuNiwwLjMsMS4xLDAuNywxLjUsMS4yQzg0LjYsNyw4NC45LDcuNiw4NSw4LjJjMC4xLDAuNiwwLjEsMS4zLTAuMSwxLjkKCQkJbC0wLjUsMS43Yy0wLjIsMC43LTAuNiwxLjQtMS4zLDEuOGMtMC42LDAuNS0xLjQsMC43LTIuMSwwLjdoLTcuOGwwLjUtMS44YzAuMS0wLjQsMC40LTAuOCwwLjgtMS4xYzAuNC0wLjMsMC44LTAuNCwxLjMtMC40SDc5CgkJCWMwLjMsMCwwLjUtMC4xLDAuNi0wLjRsMC4xLTAuNGMwLjEtMC4zLTAuMS0wLjYtMC40LTAuN2MwLDAtMC4xLDAtMC4xLDBoLTQuOEM3NCw5LjQsNzMuOCw5LjUsNzMuNiw5Ljd6Ii8%2BCgkJPHBhdGggY2xhc3M9InN0MCIgZD0iTTgzLjUsMjBsNS4yLTE4LjljMC4xLTAuMywwLjMtMC42LDAuNi0wLjhjMC4zLTAuMiwwLjYtMC4zLDEtMC4zSDkzYzAuMywwLDAuNiwwLjEsMC44LDAuNAoJCQlDOTQsMC42LDk0LjEsMC45LDk0LDEuMmwtMy45LDEzLjljLTAuMiwwLjctMC41LDEuNC0wLjksMmMtMC40LDAuNi0wLjksMS4xLTEuNSwxLjVjLTAuNiwwLjQtMS4yLDAuOC0xLjksMQoJCQlDODUsMTkuOSw4NC4yLDIwLDgzLjUsMjB6Ii8%2BCgk8L2c%2BCjwvZz4KPC9zdmc%2B","forLightBackground":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIwLjAuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9InhMYXllcl8xIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB4PSIwcHgiIHk9IjBweCIKCSB2aWV3Qm94PSIwIDAgOTQgMjAiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDk0IDIwOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGNkMyQzt9Cjwvc3R5bGU%2BCjx0aXRsZT5jUGFuZWwgTG9nbyAtIE9yYW5nZTwvdGl0bGU%2BCjxnIGlkPSJ4TGF5ZXJfMiI%2BCgk8ZyBpZD0ieExheWVyXzEtMiI%2BCgkJPHBhdGggY2xhc3M9InN0MCIgZD0iTTcuOCw0LjloNS45bC0wLjksMy4zYy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMWMtMC40LDAuMy0wLjgsMC40LTEuMywwLjRINy45Yy0wLjYsMC0xLjIsMC4yLTEuNywwLjUKCQkJYy0wLjUsMC40LTAuOCwwLjktMSwxLjRjLTAuMSwwLjQtMC4xLDAuOSwwLDEuM2MwLjEsMC40LDAuMywwLjcsMC41LDEuMWMwLjIsMC4zLDAuNiwwLjYsMC45LDAuN0M3LDE1LDcuNSwxNS4xLDcuOSwxNS4xaDEuNwoJCQljMC4zLDAsMC42LDAuMSwwLjgsMC40YzAuMiwwLjIsMC4zLDAuNSwwLjIsMC44bC0xLDMuN0g3LjZjLTEuMiwwLTIuNC0wLjMtMy40LTAuOGMtMS0wLjUtMS45LTEuMi0yLjYtMi4xCgkJCWMtMS40LTEuOC0xLjktNC4yLTEuMy02LjRsMC4xLTAuNGMwLjQtMS42LDEuNC0yLjksMi43LTMuOUMzLjgsNiw0LjUsNS42LDUuMyw1LjNDNi4xLDUuMSw2LjksNC45LDcuOCw0Ljl6Ii8%2BCgkJPHBhdGggY2xhc3M9InN0MCIgZD0iTTEwLjcsMjBsNS4xLTE4LjRjMC4xLTAuNCwwLjQtMC44LDAuOC0xLjFDMTcsMC4xLDE3LjUsMCwxOCwwaDUuNGMxLjIsMCwyLjQsMC4zLDMuNCwwLjhjMi4xLDEsMy41LDIuOSw0LDUKCQkJYzAuMywxLjEsMC4yLDIuMy0wLjEsMy40bC0wLjEsMC40Yy0wLjIsMC44LTAuNiwxLjUtMSwyLjJjLTEuNCwyLTMuOCwzLjMtNi4zLDMuM2gtNC43bDAuOS0zLjRjMC4xLTAuNCwwLjQtMC44LDAuOC0xLjEKCQkJYzAuNC0wLjMsMC44LTAuNCwxLjMtMC40aDEuNWMxLjIsMCwyLjMtMC44LDIuNy0yYzAuMS0wLjQsMC4xLTAuOCwwLTEuMmMtMC4xLTAuNC0wLjMtMC43LTAuNS0xLjFjLTAuMi0wLjMtMC42LTAuNi0wLjktMC43CgkJCUMyNCw1LDIzLjYsNC45LDIzLjEsNC45aC0yLjlsLTMuOCwxMy42Yy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMWMtMC40LDAuMy0wLjgsMC40LTEuMywwLjRIMTAuN3oiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDMuMSwxMC4ybDAuMS0wLjNjMC0wLjEsMC0wLjItMC4xLTAuM2MtMC4xLTAuMS0wLjItMC4xLTAuMy0wLjFoLTguNGMtMC4zLDAtMC43LTAuMS0xLTAuMgoJCQljLTAuMy0wLjEtMC41LTAuMy0wLjctMC42Yy0wLjItMC4yLTAuMy0wLjUtMC40LTAuOGMtMC4xLTAuMy0wLjEtMC43LDAtMWwwLjUtMS45aDExLjRjMC43LDAsMS4zLDAuMSwxLjksMC40CgkJCWMwLjYsMC4zLDEuMSwwLjcsMS41LDEuMmMwLjQsMC41LDAuNywxLjEsMC44LDEuN2MwLjEsMC42LDAuMSwxLjMsMCwxLjlsLTIuMSw3LjNDNDYsMTksNDQuNiwyMCw0MywyMGwtOC40LDAKCQkJYy0xLjQsMC0yLjctMC42LTMuNi0xLjdjLTAuNC0wLjUtMC43LTEuMS0wLjgtMS43Yy0wLjItMC43LTAuMS0xLjQsMC4xLTJsMC4xLTAuNGMwLjEtMC41LDAuMy0wLjksMC42LTEuM2MwLjMtMC40LDAuNi0wLjcsMS0xCgkJCWMwLjQtMC4zLDAuOC0wLjUsMS4zLTAuN2MwLjUtMC4yLDEtMC4yLDEuNS0wLjJoNy4xbC0wLjUsMS45Yy0wLjEsMC40LTAuNCwwLjgtMC44LDEuMWMtMC40LDAuMy0wLjgsMC40LTEuMywwLjRoLTMuMgoJCQljLTAuMywwLTAuNSwwLjEtMC42LDAuNGMtMC4xLDAuMiwwLDAuNCwwLjEsMC41YzAuMSwwLjEsMC4zLDAuMiwwLjUsMC4yaDUuMWMwLjIsMCwwLjQsMCwwLjUtMC4xYzAuMS0wLjEsMC4yLTAuMiwwLjMtMC40CgkJCWwwLjEtMC4yTDQzLjEsMTAuMnoiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNTguMyw0LjljMS4yLDAsMi40LDAuMywzLjUsMC44YzEsMC41LDEuOSwxLjIsMi42LDIuMWMwLjcsMC45LDEuMiwxLjksMS40LDNjMC4zLDEuMSwwLjIsMi4zLTAuMSwzLjQKCQkJbC0xLjMsNC43Yy0wLjEsMC4zLTAuMywwLjYtMC42LDAuOGMtMC4zLDAuMi0wLjYsMC4zLTEsMC4zSDYwYy0wLjUsMC0xLTAuNC0xLTAuOWMwLTAuMSwwLTAuMiwwLTAuM2wxLjYtNS43CgkJCWMwLjEtMC40LDAuMS0wLjgsMC0xLjJjLTAuMS0wLjQtMC4zLTAuNy0wLjUtMS4xYy0wLjItMC4zLTAuNi0wLjYtMC45LTAuN2MtMC40LTAuMi0wLjgtMC4zLTEuMi0wLjNoLTIuOWwtMi41LDkuMQoJCQljLTAuMSwwLjMtMC4zLDAuNi0wLjYsMC44Yy0wLjMsMC4yLTAuNiwwLjMtMSwwLjNoLTIuOGMtMC4zLDAtMC42LTAuMS0wLjgtMC40Yy0wLjItMC4yLTAuMy0wLjUtMC4yLTAuOGwzLjgtMTMuOUw1OC4zLDQuOXoiLz4KCQk8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNzMuNiw5LjdjLTAuMiwwLjItMC40LDAuNC0wLjQsMC42TDcyLDE0LjVjLTAuMSwwLjQsMC4xLDAuOCwwLjUsMC45YzAuMSwwLDAuMSwwLDAuMiwwaDEwLjhsLTAuOCwzCgkJCWMtMC4xLDAuNC0wLjQsMC44LTAuOCwxLjFDODEuNSwxOS45LDgxLDIwLDgwLjYsMjBoLTkuOGMtMC43LDAtMS4zLTAuMS0xLjktMC40Yy0wLjYtMC4zLTEuMS0wLjctMS41LTEuMgoJCQljLTAuNC0wLjUtMC43LTEuMS0wLjgtMS43Yy0wLjEtMC42LTAuMS0xLjMsMC4xLTEuOWwxLjYtNS43YzAuMi0wLjYsMC40LTEuMiwwLjgtMS43YzAuNy0xLDEuNy0xLjgsMi45LTIuMgoJCQljMC42LTAuMiwxLjMtMC4zLDEuOS0wLjNoNi45YzAuNywwLDEuMywwLjEsMS45LDAuNGMwLjYsMC4zLDEuMSwwLjcsMS41LDEuMkM4NC42LDcsODQuOSw3LjYsODUsOC4yYzAuMSwwLjYsMC4xLDEuMy0wLjEsMS45CgkJCWwtMC41LDEuN2MtMC4yLDAuNy0wLjYsMS40LTEuMywxLjhjLTAuNiwwLjUtMS40LDAuNy0yLjEsMC43aC03LjhsMC41LTEuOGMwLjEtMC40LDAuNC0wLjgsMC44LTEuMWMwLjQtMC4zLDAuOC0wLjQsMS4zLTAuNEg3OQoJCQljMC4zLDAsMC41LTAuMSwwLjYtMC40bDAuMS0wLjRjMC4xLTAuMy0wLjEtMC42LTAuNC0wLjdjMCwwLTAuMSwwLTAuMSwwaC00LjhDNzQsOS40LDczLjgsOS41LDczLjYsOS43eiIvPgoJCTxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik04My41LDIwbDUuMi0xOC45YzAuMS0wLjMsMC4zLTAuNiwwLjYtMC44YzAuMy0wLjIsMC42LTAuMywxLTAuM0g5M2MwLjMsMCwwLjYsMC4xLDAuOCwwLjQKCQkJQzk0LDAuNiw5NC4xLDAuOSw5NCwxLjJsLTMuOSwxMy45Yy0wLjIsMC43LTAuNSwxLjQtMC45LDJjLTAuNCwwLjYtMC45LDEuMS0xLjUsMS41Yy0wLjYsMC40LTEuMiwwLjgtMS45LDEKCQkJQzg1LDE5LjksODQuMiwyMCw4My41LDIweiIvPgoJPC9nPgo8L2c%2BCjwvc3ZnPgo%3D"}},"documentation":{"url":"https://hosting.com/documentation"},"help":{"url":"https://hosting.com/get-help"}}'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_customizations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Manage MySQL Server

Databases / Manage MySQL Server

Return MySQL or MariaDB upgrade status

This function retrieves the status of a background MySQL® or MariaDB® upgrade.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
upgrade_id
required
string
Example: upgrade_id=mysql_upgrade.20141108-172923

The logfile's name.

Note:

Log files exist in the /var/cpanel/logs/ directory.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  background_mysql_upgrade_status \
  upgrade_id='mysql_upgrade.20141108-172923'

Response samples

Content type
application/json
{
  • "data": {
    • "error": 0,
    • "error_log": "Starting The system failed to update MYSQL,\\n------------------------------------\\n",
    • "log": "Starting process with log file at /var/cpanel/logs/mysql_upgrade.20141108-172923/unattended_background_upgrade.log\nBeginning MariaDB 10.0 upgrade...\nObtained version information from system.\nEnsuring the MariaDB100 repository is available and working.\ncheckyum version 22.3\nEnsuring that the package MariaDB-client with version matching 10.0 is available.\nEnsuring that the package MariaDB-common with version matching 10.0 is available.\nEnsuring that the package MariaDB-devel with version matching 10.0 is available.\nEnsuring that the package MariaDB-server with version matching 10.0 is available.\nEnsuring that the package MariaDB-shared with version matching 10.0 is available.\nEnsuring that the package coreutils is available.\nEnsuring that the package grep is available.\nEnsuring that the package perl-DBI is available.\n your MariaDB server version for the right syntax to use near ''.`netcopya0I5KfqYTfHqJr` FOR UPGRADE'' at line 1 when executing ''CHECK TABLE ... FOR UPGRADE''\nFATAL ERROR: Upgrade failed\nDone building configuration.\nHooks system enabled.\nChecking for and running RPM::Versions ''post'' hooks for any RPMs about to be installed\nAll required ''post'' hooks have been run\nRunning: /usr/local/cpanel/scripts/check_cpanel_pkgs --targets=MySQL41,MySQL50,MySQL51,MySQL55,MySQL56,MariaDB100,MariaDB101 --fix\nRestarting mysql service.\nWaiting for mysql to restart waiting for mysql to initialize finished.\n\u001b[1;32mMariaDB upgrade completed successfully\u001b[0m\n------------------------------------\n",
    • "state": "success"
    },
  • "metadata": {
    • "command": "background_mysql_upgrade_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return MySQL version

This function retrieves the server's version of MySQL® or MariaDB®.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  current_mysql_version

Response samples

Content type
application/json
{
  • "data": {
    • "server": "mysql",
    • "version": "8.0"
    },
  • "metadata": {
    • "command": "current_mysql_version",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate MySQL status before upgrade

This function checks your MySQL configuration file and table engine before an upgrade to MySQL 8.0.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  background_mysql_upgrade_checker_run

Response samples

Content type
application/json
{
  • "data": {
    • "log_entry": "mysql_upgrade.20200202-172923",
    • "pid": 23456
    },
  • "metadata": {
    • "command": "background_mysql_upgrade_checker_run",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available MySQL versions

This function lists all available versions of MySQL® and MariaDB.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  installable_mysql_versions

Response samples

Content type
application/json
{
  • "data": {
    • "versions": [
      • {
        • "server": "mariadb",
        • "version": "10.0"
        }
      ]
    },
  • "metadata": {
    • "command": "installable_mysql_versions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return latest MySQL version

This function retrieves the latest available version of MySQL® or MariaDB®.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  latest_available_mysql_version

Response samples

Content type
application/json
{
  • "data": {
    • "server": "mariadb",
    • "version": "10.0"
    },
  • "metadata": {
    • "command": "latest_available_mysql_version",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update the servers SQL configuration.

This function updates the database configuration file for MySQL® or MariaDB®.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
Request Body schema: application/json
required
required
Array of objects

Array of objects that contains the requested updates to the sql configuration.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "data": [
    • {
      • "name": "max_allowed_packet",
      • "section": "mysqld",
      • "value": "268435456"
      }
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_sql_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start background MySQL upgrade

This function upgrades MySQL® or MariaDB® in the background. This will reinstall MySQL® or MariaDB® if the version given is the installed version.

Important:

When you disable the MySQL/MariaDB server role and remote MySQL® is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
version
required
number
Example: version=5.7

The desired MySQL® or MariaDB® version. Must contain one decimal.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_background_mysql_upgrade \
  version='5.7'

Response samples

Content type
application/json
{
  • "data": {
    • "upgrade_id": "mysql_upgrade.20200202-172923"
    },
  • "metadata": {
    • "command": "start_background_mysql_upgrade",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update MySQL root password

This function resets the root user's password on the local MySQL® server.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
password
required
string
Example: password=12345luggage

The new MySQL root user's password.

update_config
integer
Possible Values: 0 1
Example: update_config=1

Whether to update the configuration files.

  • 1 — Update.
  • 0 — Do not update.

Note:

This value is always enabled when localhost is the active profile, and must be specified explicitly when a remote profile is active.

Warning:

This parameter updates the /root/.my.cnf file with the new password, which could cause problems with the MySQL configuration on the server. If you are unsure, do not specify this parameter.

  • If you set this parameter to 0 when localhost is the active profile, it will stop communication with the remote MySQL server until you update the profile's password.
  • If you set this parameter to 1 when a remote host is the active profile, it will stop communication with the remote MySQL server until you update the profile's password.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_local_mysql_root_password \
  password='12345luggage'

Response samples

Content type
application/json
{
  • "data": {
    • "configs_updated": 1,
    • "password_reset": 1,
    • "profile_updated": 1
    },
  • "metadata": {
    • "command": "set_local_mysql_root_password",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

MySQL Databases

Databases / MySQL Databases

Return MySQL users

This function lists the server's database users.

Warning:

On most servers, this function returns a large amount of output. We strongly suggest that you filter and sort the output.

Important:

When you disable the MySQL/MariaDB and PostgreSQL roles and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_database_users

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "cpuser": "example",
        • "engine": "postgresql",
        • "name": "example_user1"
        }
      ]
    },
  • "metadata": {
    • "command": "list_database_users",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return MySQL databases

This function lists the server's databases.

Warning:

On most servers, this function returns a large amount of output. We strongly suggest that you filter and sort the output.

Important:

When you disable the MySQL/MariaDB and PostgreSQL roles and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_databases

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "cpuser": "example",
        • "engine": "postgresql",
        • "name": "example_db0"
        }
      ]
    },
  • "metadata": {
    • "command": "list_databases",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update MySQL database name

This function changes a MySQL® database's name. MySQL does not allow you to rename a database. When cPanel & WHM "renames" a database, the system performs the following steps:

  1. The system creates a new database.
  2. The system moves data from the old database to the new database.
  3. The system recreates grants and stored code in the new database.
  4. The system deletes the old database and its grants.

Warning:

  • If any of the first three steps fail, the system returns an error and attempts to restore the database's original state. If the restoration process fails, the API function's error response describes these additional failures.
  • In rare cases, the system creates the second database successfully but fails to delete the old database or grants. The system treats the rename action as a success; however, the API function returns warnings that describe the failure to delete the old database or grants.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
cpuser
string <username>
Example: cpuser=username

The database's owner.

newname
required
string <= 64 characters
Example: newname=database2

The database's new name.

Warning:

  • If database prefixing is enabled, this parameter must include the database prefix for the account.
  • The maximum length of the database name is 64 characters. However, due to the method that cPanel & WHM uses to store MySQL database names, each underscore character (_) requires two characters of that limit. Therefore, if you enable database prefixing, the maximum length of the database name is 63 characters, which includes both the database prefix and the underscore character. Each additional underscore requires another two characters of that limit.
oldname
required
string
Example: oldname=database

The database's current name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  rename_mysql_database \
  oldname='database' \
  newname='database2'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "rename_mysql_database",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return MySQL databases and users for account

This function retrieves the MySQL® database and user data for the specified account.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
user
required
string <username>
Example: user=username

The username for a specified account.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_mysql_databases_and_users \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "mysql_config": {
      • "mysql-version": "5.5",
      • "prefix_length": 8,
      • "use_db_prefix": 1
      },
    • "mysql_databases": {
      • "user1_database1": [
        • "user1_user1"
        ],
      • "user2_database2": [
        • "user2_user2"
        ]
      }
    },
  • "metadata": {
    • "command": "list_mysql_databases_and_users",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update MySQL username

This function changes a MySQL® database user's name.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
cpuser
string <username>
Example: cpuser=example

The database user's owner.

newname
required
string
Example: newname=username2

The database user's new name.

Warning:

If database prefix is enabled, this parameter must include the database prefix for the account.

oldname
required
string
Example: oldname=username

The database user's current name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  rename_mysql_user \
  oldname='username' \
  newname='username2'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "rename_mysql_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update MySQL user password

This function changes a MySQL® database user's password.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:
BasicAuth
query Parameters
cpuser
string <username>
Example: cpuser=example

The cPanel user that controls the database user.

password
required
string
Example: password=123456luggage

The database user's new password.

user
required
string <username>
Example: user=username

The database username. For information about database username restrictions, read the MySQL and MariaDB documentation.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_mysql_password \
  user='username' \
  password='123456luggage'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_mysql_password",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return MySQL database optimizations

This function retrieves available database optimizations.

Warning:

On some servers, this function may return a large amount of output. We strongly suggest that you filter and sort the output.

Important:

The system disables this function when you have not configured remote MySQL, and you've disabled the MySQL/MariaDB and PostgreSQL roles.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_database_optimizations

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "name": "innodb_sort_buffer_size",
        • "reason": "Your system's peak theoretical memory allocation is too high and may cause instability.",
        • "value": "2M"
        }
      ]
    },
  • "metadata": {
    • "command": "get_database_optimizations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

PostgreSQL Databases

Databases / PostgreSQL Databases

Update PostgreSQL database name

This function changes a PostgreSQL® database's name.

Warning:

The system requires more time to rename larger and more complex databases.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
cpuser
string <username>
Example: cpuser=username

The database's owner.

newname
required
string
Example: newname=database2

The database's new name.

Warning: If database prefixing is enabled, this parameter must include the database prefix for the account.

oldname
required
string
Example: oldname=database

The database's current name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  rename_postgresql_database \
  oldname='database' \
  newname='database2'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "rename_postgresql_database",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update PostgreSQL username

This function changes a PostgreSQL® database user's name.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
cpuser
string
Example: cpuser=example

The database user's owner.

newname
required
string
Example: newname=username2

The database user's new name.

Warning: If database prefix is enabled, this parameter must include the database prefix for the account.

oldname
required
string <username>
Example: oldname=username

The database user's current name.

password
required
string
Example: password=12345luggage

The database user's new password.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  rename_postgresql_user \
  oldname='username' \
  newname='username2' \
  password='12345luggage'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "rename_postgresql_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update PostgreSQL user password

This function changes a PostgreSQL® database user's password.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
cpuser
string
Example: cpuser=example

The database user's owner.

password
required
string
Example: password=12345luggage

The database user's new password.

user
required
string
Example: user=username

The account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_postgresql_password \
  user='username' \
  password='12345luggage'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_postgresql_password",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remote MySQL Databases

Databases / Remote MySQL Databases

Delete remote MySQL profile

This function deletes a specified remote MySQL® profile.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=MyProfile

The profile's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_delete_profile \
  name='MyProfile'

Response samples

Content type
application/json
{
  • "data": {
    • "profile_deleted": "MyProfile",
    • "profile_details": {
      • "active": 0,
      • "mysql_host": "192.168.0.1",
      • "mysql_pass": "12345luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "setup_via": "Main terminal"
      }
    },
  • "metadata": {
    • "command": "remote_mysql_delete_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return remote MySQL profile activation

This function reports the current status of the remote MySQL® profile activation process. The activation process contains several steps that take some time to complete, so so you may need to call this function multiple times multiple times to monitor the progress.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_monitor_profile_activation

Response samples

Content type
application/json
{
  • "data": {
    • "job_in_progress": {
      • "profile_name": "remote_server",
      • "start_time": 1432064519,
      • "status": "INPROGRESS",
      • "steps": [
        • {
          • "end_time": 1432064520,
          • "name": "Updating /root/.my.cnf",
          • "start_time": 1432064519,
          • "status": "DONE"
          }
        ]
      },
    • "last_job_details": {
      • "end_time": 1432220941,
      • "profile_name": "MyProfile",
      • "start_time": 1432064519,
      • "status": "DONE",
      • "steps": [
        • {
          • "end_time": 1432220941,
          • "name": "string",
          • "start_time": 1432220941,
          • "status": "DONE"
          }
        ]
      }
    },
  • "metadata": {
    • "command": "remote_mysql_monitor_profile_activation",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return remote MySQL profiles

This function displays the details of all remote MySQL® profiles available in WHM.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_read_profiles

Response samples

Content type
application/json
{
  • "data": {
    • "MyProfile": {
      • "active": 0,
      • "is_localhost_profile": 1,
      • "mysql_host": "192.168.0.1",
      • "mysql_pass": "123456luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "mysql_version_is_supported": 0,
      • "setup_via": "Main terminal"
      },
    • "MyProfile2": {
      • "active": 0,
      • "is_localhost_profile": "1",
      • "mysql_host": "192.168.0.2",
      • "mysql_pass": "123456luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "mysql_version_is_supported": "0",
      • "setup_via": "Main terminal"
      },
    • "localhost": {
      • "active": 1,
      • "is_localhost_profile": 1,
      • "mysql_host": "localhost",
      • "mysql_pass": "#1mpll-C",
      • "mysql_port": 3306,
      • "mysql_user": "root",
      • "mysql_version_is_supported": 0,
      • "setup_via": "Auto-Migrated active profile"
      }
    },
  • "metadata": {
    • "command": "remote_mysql_read_profiles",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return remote MySQL profile

This function displays the details of a specified remote MySQL® profile.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=MyProfile

The MySQL profile's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_read_profile \
  name='MyProfile'

Response samples

Content type
application/json
{
  • "data": {
    • "profile_details": {
      • "active": 0,
      • "mysql_host": "192.168.0.1",
      • "mysql_pass": "123456luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "setup_via": "Main terminal"
      },
    • "profile_name": "MyProfile"
    },
  • "metadata": {
    • "command": "remote_mysql_read_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start remote MySQL profile activation

This function initiates the activation process for a remote MySQL® profile.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=MyProfile

The profile's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_initiate_profile_activation \
  name='MyProfile'

Response samples

Content type
application/json
{
  • "data": {
    • "activation_job_started": 8093
    },
  • "metadata": {
    • "command": "remote_mysql_initiate_profile_activation",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate remote MySQL profile connection

This function validates a specified remote MySQL® profile's connection details.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=MyProfile

The profile's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_validate_profile \
  name='MyProfile'

Response samples

Content type
application/json
{
  • "data": {
    • "profile_validated": "MyProfile"
    },
  • "metadata": {
    • "command": "remote_mysql_validate_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update remote MySQL profile

This function updates one or more parameters for a remote MySQL® profile.

Note: This function requires the name parameter and one of more of the mysql_host , mysql_user, mysql_pass, mysql_port, or setup_via parameters.

Authorizations:
BasicAuth
query Parameters
string or string
Example: mysql_host=192.168.0.1

The MySQL server's IP address or hostname.

mysql_pass
string
Example: mysql_pass=12345luggage

The MySQL server's password.

mysql_port
integer [ 1 .. 65535 ]
Example: mysql_port=3306

The MySQL server's port.

mysql_user
string
Example: mysql_user=username

The MySQL server's username.

name
required
string
Example: name=MyProfile

The profile's name.

setup_via
string <= 255 characters
Example: setup_via=Main terminal

A description of the profile data.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_update_profile \
  name='MyProfile'

Response samples

Content type
application/json
{
  • "data": {
    • "profile_details": {
      • "active": 0,
      • "mysql_host": "192.168.0.1",
      • "mysql_pass": "12345luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "setup_via": "Main terminal"
      },
    • "profile_saved": "MyProfile"
    },
  • "metadata": {
    • "command": "remote_mysql_update_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create remote MySQL profile

This function creates a profile to access a remote MySQL® server.

Authorizations:
BasicAuth
query Parameters
cpcloud
integer
Default: 0
Example: cpcloud=1

Whether the remote database profile is a cPanel Cloud deployment.

  • 1 — Is cPanel Cloud.
  • 0 — Not cPanel Cloud.
required
string or string
Example: mysql_host=192.168.0.1

The MySQL server's IP address or hostname.

mysql_pass
required
string
Example: mysql_pass=12345luggage

The MySQL server's password.

mysql_port
required
integer [ 1 .. 65535 ]
Example: mysql_port=3306

The MySQL server's port.

mysql_user
required
string
Example: mysql_user=username

The MySQL server's username.

name
required
string
Example: name=MyProfile

The new profile's name.

setup_via
string <= 255 characters
Example: setup_via=Main terminal

A description of the profile data.

Note:

This parameter defaults to User provided MySQL credentials.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_create_profile \
  name='MyProfile' \
  mysql_host='192.168.0.1' \
  mysql_user='username' \
  mysql_pass='12345luggage' \
  mysql_port='3306'

Response samples

Content type
application/json
{
  • "data": {
    • "profile_details": {
      • "active": 0,
      • "cpcloud": 0,
      • "mysql_host": "192.168.0.1",
      • "mysql_pass": "12345luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "setup_via": "Main terminal"
      },
    • "profile_saved": "MyProfile"
    },
  • "metadata": {
    • "command": "remote_mysql_create_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create remote MySQL profile via SSH

This function uses SSH to create a profile to access a remote MySQL® server.

Authorizations:
BasicAuth
query Parameters
cpcloud
integer
Default: 0
Example: cpcloud=1

Whether the remote database profile is a cPanel Cloud deployment.

  • 1 — Is cPanel Cloud.
  • 0 — Not cPanel Cloud.
required
string or string
Example: host=192.168.0.1

The MySQL server's IP address or hostname.

name
required
string
Example: name=MyProfileSSH

The new profile's name.

password
string
Example: password=12345luggage

The SSH username's password.

Warning:

You must specify either the password or the sshkey_name parameter.

port
required
integer [ 1 .. 65535 ]
Example: port=22

The SSH server's port.

root_escalation_method
string
Possible Values: "sudo" "su"
Example: root_escalation_method=su

The escalation method to use to authenticate the account.

Warning:

This parameter is required if the user parameter's value is not root.

root_password
string
Example: root_password=username

The MySQL server's root user's password.

Warning:

This parameter is required if the root_escalation_method parameter's value is su.

sshkey_name
string
Example: sshkey_name=VinzClortho

The name of the SSH key.

Warning:

You must specify either the password or the sshkey_name parameter.

sshkey_passphrase
string
Example: sshkey_passphrase=Gozer

The SSH key's passphrase.

Warning:

This parameter is required if the sshkey_name value is password-protected.

user
required
string
Example: user=SSHuser

The SSH username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_mysql_create_profile_via_ssh \
  name='MyProfileSSH' \
  user='SSHuser' \
  host='192.168.0.1' \
  port='22'

Response samples

Content type
application/json
{
  • "data": {
    • "profile_details": {
      • "cpcloud": 0,
      • "mysql_host": "192.168.0.1",
      • "mysql_pass": "12345luggage",
      • "mysql_port": 3306,
      • "mysql_user": "username",
      • "setup_via": "Created via SSH"
      },
    • "profile_saved": "MyProfileSSH"
    },
  • "metadata": {
    • "command": "remote_mysql_create_profile_via_ssh",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

DNS Cluster Settings

DNS / DNS Cluster Settings

Update remote DNS server's nameserver software

This function sets the nameserver software that the remote servers in a DNS cluster run. The system queues the nameserver software that you select until the HTTP request finishes. Then, it sets the remote servers' nameserver software.

Authorizations:
BasicAuth
query Parameters
nameserver
required
string
Possible Values: "BIND" "PowerDNS" "Disabled"
Example: nameserver=BIND

The nameserver software.

  • BIND
  • PowerDNS
  • Disabled

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_nameserver \
  nameserver='BIND'

Response samples

Content type
application/json
{
  • "data": {
    • "message": "Queued task to set nameserver to bind successfully.",
    • "nameserver": "bind"
    },
  • "metadata": {
    • "command": "set_nameserver",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

DNS Security

DNS / DNS Security

Enable domain's DNSSEC key

This function activates a domain's DNSSEC security key.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to activate a security key.

key_id
required
integer >= 1
Example: key_id=1

The security key's ID.

Note:

Use the WHM AP1 fetch_ds_records_for_domains function to locate the domain's security key ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  activate_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "activate_zone_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable DNSSEC on domain

This function disables DNSSEC on the domain.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Warning:

  • This action is irreversible. If you disable DNSSEC on the domain, you will lose the associated keys. You can only retrieve the keys by restoring them from a full back up of the account.
  • If you disable DNSSEC, you must remove the Delegation of Signing (DS) records on your DNS server and with your registrar.
Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Examples:
  • domain=domain=example.com&domain-1=example1.com&domain-2=example2.com - Multiple domains
  • domain=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains
  • domain=example.com - A single domain.

The domain for which to disable DNSSEC.

Note:

To disable DNSSEC for multiple domains, duplicate or increment the parameter name. For example, to check three domains, you could:

  • Use the domain parameter multiple times.
  • Use the domain, domain-1, domain-2 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_dnssec_for_domains \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "disabled": 1,
        • "domain": "example.com"
        }
      ]
    },
  • "metadata": {
    • "command": "disable_dnssec_for_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable domain's DNSSEC key

This function deactivates a domain's DNSSEC security key.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to deactivate a security key.

key_id
required
integer
Example: key_id=1

The security key's ID.

Note:

Use the WHM AP1 fetch_ds_records_for_domains function to locate the domain's security key ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  deactivate_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "deactivate_zone_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable DNSSEC on domain

This function enables DNSSEC on the domain.

Note:

  • Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.
  • After you enable DNSSEC on the domain, you must add the Delegation of Signing (DS) records on your DNS server and with your registrar.
  • You cannot modify the DNSSEC security key. To make any changes, you must disable, delete, and re-create the DNSSEC security key.
Authorizations:
BasicAuth
query Parameters
active
integer
Default: 1
Possible Values: 0 1
Example: active=1

Whether to activate the newly-created key.

  • 1 - Activate the key.
  • 0 - Do not activate the key.
algo_num
integer
Default: 8
Possible Values: 5 6 7 8 10 13 14
Example: algo_num=8

The algorithm that the system uses to generate the security key.

  • 5 - RSA/SHA-1
  • 6 - DSA-NSEC3-SHA1
  • 7 - RSASHA1-NSEC3-SHA1
  • 8 - RSA/SHA-256
  • 10 - RSA/SHA-512
  • 13 - ECDSA Curve P-256 with SHA-256
  • 14 - ECDSA Curve P-384 with SHA-384

Note:

We recommend that you use an ECDSA Curve P-256 with SHA-256 (13) value if your registrar supports it.

domain
required
string <domain>
Examples:
  • domain=domain=example.com&domain-1=example1.com&domain-2=example2.com - Multiple domains
  • domain=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains
  • domain=example.com - A single domain.

The domain for which to enable DNSSEC.

Note:

To enable DNSSEC on multiple domains, duplicate or increment the parameter name. For example, to check three domains, you could:

  • Use the domain parameter multiple times.
  • Use the domain, domain-1, and domain-2 parameters.
key_setup
string
Default: "classic"
Possible Values: "classic" "simple"
Example: key_setup=classic

The manner in which the system creates the security key.

  • classic - Use separate keys for KSK and ZSK. Use this value when the algo_num parameter is equal to or less than 8.
  • simple - Use a single key for both KSK and ZSK. Use this value when the algo_num parameter is greater than 8.
nsec3_iterations
integer [ 1 .. 500 ]
Default: 7
Example: nsec3_iterations=7

The number of times that the system rehashes the first resource record hash operation.

nsec3_narrow
integer
Default: 1
Possible Values: 0 1
Example: nsec3_narrow=1

Whether NSEC3 operates in Narrow or Inclusive mode.

Note:

For information about these modes, read PowerDNS's DNSSEC documentation.

  • 1 - Narrow mode.
  • 0 - Inclusive mode.
nsec3_opt_out
integer
Default: 0
Possible Values: 0 1
Example: nsec3_opt_out=1

Whether the system will create records for all delegations.

  • 1 - Create records for all delegations.
  • 0 - Create records only for secure delegations.

Note:

Only use the 1 value if you must create records for all delegations.

nsec3_salt
string
Example: nsec3_salt=1a2b3c4d5e6f

A hexadecimal string that the system appends to the domain name before it applies the hash function to the name.

Note:

For information about salt values, read RFC 5155.

use_nsec3
integer
Default: 1
Possible Values: 0 1
Example: use_nsec3=1

Whether the domain will use Next Secure Record (NSEC) or NSEC3 semantics.

  • 1 - Use NSEC3 semantics.
  • 0 - Use NSEC semantics.

Note:

If you use this value, the system ignores the other NSEC3 options.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_dnssec_for_domains \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "domain": "example.com",
        • "enabled": 1,
        • "new_key_id": "2",
        • "nsec_error": "Error message.",
        • "nsec_version": "NSEC3"
        }
      ]
    },
  • "metadata": {
    • "command": "enable_dnssec_for_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Export domain's DNSSEC key

This function exports a DNSSEC security key to a domain.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain to export the security key to.

key_id
required
integer
Example: key_id=1

The security key's ID.

Note:

You can locate the ID with the WHM AP1 fetch_ds_records_for_domains function.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  export_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

Content type
application/json
{
  • "data": {
    • "key_tag": 40481,
    • "key_type": "CSK"
    },
  • "metadata": {
    • "command": "export_zone_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Import DNSSEC key

This function imports a DNSSEC security key.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to import the security key.

key_data
required
string
Example: key_data=Private-key-format:%20v1.2%0AAlgorithm:%2013%20\(ECDSAP256SHA256\)%0APrivateKey:%20xCM281KtWE9oCsUX8fP1hDZ02/X7JCjp4QZA/DZjfX0=%0A%0A

The security key's data that the pdnsuti utility's export-zone-key call returns.

key_type
required
string
Example: key_type=ksk

The security key's type.

  • ksk — Key-Signing Key
  • zsk — Zone Signing Key

Note:

You must call these values in lowercase.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty import_zone_key domain='example.com' key_type='ksk' key_data='Private-key-format:%20v1.2%0AAlgorithm:%2013%20\(ECDSAP256SHA256\)%0APrivateKey:%20xCM281KtWE9oCsUX8fP1hDZ02/X7JCjp4QZA/DZjfX0=%0A%0A'

Response samples

Content type
application/json
{
  • "data": {
    • "import_key_id": 1
    },
  • "metadata": {
    • "command": "import_zone_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove DNSSEC key

This function removes a DNSSEC security key.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to remove a security key.

key_id
required
integer >= 1
Example: key_id=1

The security key's ID.

Note:

Use the WHM AP1 fetch_ds_records_for_domains function to locate the domain's security key ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "remove_zone_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create domain's DNSSEC zone key

This function generates a DNSSEC zone key for a domain.

Note:

  • Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.
  • After you enable DNSSEC on the domain, you must add the Delegation of Signing (DS) records to your zone record and your registrar.
  • You cannot modify the DNSSEC security key. To make any changes, you must disable, delete, and re-create the DNSSEC security key.
Authorizations:
BasicAuth
query Parameters
active
integer
Default: 1
Possible Values: 0 1
Example: active=1

Whether to activate the new security key.

  • 1 — Activate.
  • 0 — Do not activate.
algo_num
required
integer
Possible Values: 5 6 7 8 13 14
Example: algo_num=13

The algorithm that the system uses to generate the security key.

  • 5 — RSA/SHA-1
  • 6 — DSA-NSEC3-SHA1
  • 7 — RSA SHA1-NSEC3-SHA1
  • 8 — RSA/SHA-256
  • 13 — ECDSA Curve P-256 with SHA-256
  • 14 — ECDSA Curve P-384 with SHA-384

Note:

We recommend that you use a 13 (ECDSA Curve P-256 with SHA-256) value if your registrar supports it.

domain
required
string
Example: domain=example.com

The domain for which to enable DNSSEC.

key_size
integer
Possible Values: 256 384 1024 2048
Example: key_size=256

The security key size, in bits.

Note:

This parameter defaults to the following values, depending on the algo_num and key_type values:

  • algo_num = 5
    • ksk = 2048
    • zsk = 1024
  • algo_num = 6
    • ksk = 2048
    • zsk = 1024
  • algo_num = 7
    • ksk = 2048
    • zsk = 1024
  • algo_num = 8
    • ksk = 2048
    • zsk = 1024
  • algo_num = 13
    • ksk and zsk = 256
  • algo_num = 14
    • ksk and zsk = 384
key_type
required
string
Example: key_type=ksk

The type of security key to add.

  • ksk — Key Signing Key.
  • zsk — Zone Signing Key.

Note:

You must call these values in lowercase.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  add_zone_key \
  domain='example.com' \
  algo_num='13' \
  key_type='ksk'

Response samples

Content type
application/json
{
  • "data": {
    • "new_key_id": "1"
    },
  • "metadata": {
    • "command": "add_zone_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

DNS Zones

DNS / DNS Zones

Return server's DNS zones

This function lists the server's DNS zones.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listzones

Response samples

Content type
application/json
{
  • "data": {
    • "zone": [
      • {
        • "domain": "example.com",
        • "zonefile": "example.net.db"
        }
      ]
    },
  • "metadata": {
    • "command": "listzones",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update DNS zone record

This function edits a DNS zone record. To effectively use this function, use the following workflow:

  1. Run the dumpzone function on the DNS zone record to edit.
  2. Locate the Line value that corresponds to the data to edit.
  3. Use the values from that zone record to formulate the appropriate editzonerecord parameters.

Important:

  • When you call this function, you must include the additional parameters for the selected zone record type.
  • To change the zone record's IP address, we recommend that you use the swapip script or the setsiteip function instead.
  • You cannot edit other DNS zones that reside on Write-only servers in a DNS cluster.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth
Request Body schema: application/x-www-form-urlencoded
required

The updated DNS Zone Record.

address
required
string <ipv4>

The zone record's IPv4 address.

Note:

For more information about A records, read RFC 1035 at IANA.

domain
required
string <domain>

The zone record's domain.

line
required
integer >= 1

The zone record's file line number.

ttl
required
integer >= 1

The record's Time To Live (TTL), in seconds.

string or string

The record's class.

If you do not use this parameter, the system retains the current setting.

name
string <domain>

The record's name.

If you do not use this parameter, the system retains the current setting.

Note:

Do not omit any necessary trailing periods.

You cannot use this function to modify temporary domains.

type
string

The DNS record type:

  • A - A records store IPv4 addresses. Use them to map a hostname to an IPv4 address.
  • A6 - A6 records store IPv6 addresses.
  • AAAA - AAAA records store IPv6 addresses.
  • AFSDB - AFSDB records store the location of an AFS cell's database servers.
  • ALIAS - ALIAS records create an alias to another hostname, but can coexist with other records on that name. We strongly discourage using this record type.
  • CAA - CAA records control which certificate authorities can issue SSL certificates for a domain.
  • CNAME - CNAME records create an alias to another hostname.
  • DNAME - DNAME records create an alias for a hostname and its subnames.
  • DS - DS records specify a record's delegation signer.
  • HINFO - HINFO records specify a host's CPU and OS types.
  • LOC - LOC records store a hostname's geographical location.
  • MX - MX records point a domain name to its MTAs.
  • NS - NS records store a domain's authoritative nameservers.
  • PTR - PTR records point to a CNAME.
  • RP - RP records store a domain's Responsible Person's information.
  • SOA - SOA records designate the beginning of a zone of authority.
  • SRV - SRV records store the service location records for newer protocols (for example, Autodiscover).
  • TXT - TXT records store descriptive text or useful records (for example, SPF or DKIM records).

If you do not use this parameter, the system retains the current setting.

Warning:

Additional properties may be required based on the type.

When you call this function, you must include the additional parameters for the desired zone record type if you use this parameter. Select a zone record from the menu to view the required additional parameters:

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --input=json --output=jsonpretty \
  editzonerecord

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "editzonerecord",
    • "reason": "Bind reloading on hostname using rndc zone: [example.com]\n",
    • "result": 1,
    • "version": 1
    }
}

Export domain's DNSKEY record value

This function exports a domain's DNSKEY record value.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The domain from which to fetch the DNSKEY record value.

key_id
required
integer >= 1
Example: key_id=12345

The DNSSEC record's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  export_zone_dnskey \
  domain='example.com' \
  key_id='12345'

Response samples

Content type
application/json
{
  • "data": {
    • "dnskey": "AwEAAch8SGW4vE6PjFWA9rbUm0AfTq+gJ0HC/nLu+2axdWHBIStt9lsOzKDorAr4vlmhlJzEzA62s96xp6mZ7XHUyWnkFwLs8obo6upL2in4h1ToOxzVl3lTs8O+kWtDq5/h1nwFlPDs9zpLJhlkTCtx2OTGbvimEYeqwPolUuSQR/Yb",
    • "key_id": 12345
    },
  • "metadata": {
    • "command": "export_zone_dnskey",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete DNS zone record

This function deletes a DNS zone record.

Warning:

Incorrect use of this function could cause domains to resolve incorrectly. Exercise extreme caution when you remove DNS zone records.

To effectively use this function, use the following workflow:

  1. Run the dumpzone function.
  2. Locate the Line value that corresponds to the zone record to delete.
  3. Use the values from that zone record to formulate the appropriate removezonerecord parameters.

Important:

  • When you disable the DNS role, the system disables this function.
  • You cannot use this function to modify temporary domains.
Authorizations:
BasicAuth
query Parameters
line
required
integer >= 1
Example: line=4

The DNS zone record file's line number.

serialnum
string
Example: serialnum=2013122501

The zone file's serial number.

This parameter defaults to the zone file's current serial number.

zone
required
string <domain>
Example: zone=example.com

The zone record's domain.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  removezonerecord \
  zone='example.com' \
  line='4'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "removezonerecord",
    • "reason": "Bind reloading on hostname using rndc zone: [example.com]\n",
    • "result": 1,
    • "version": 1
    }
}

Update reverse DNS cache

This function queries DNS and updates the map of local IP addresses to reverse DNS names.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_reverse_dns_cache

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_reverse_dns_cache",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return specific line from domain's DNS configuration

This function returns a line from a domain's DNS zone configuration.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.

Important:

When you disable the DNS Role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The zone record's domain.

line
required
integer >= 1
Example: line=2

The zone record's line number.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  getzonerecord \
  domain='example.com' \
  line='2'

Response samples

Content type
application/json
{
  • "data": {
    • "record": [
      • {
        • "Line": 24,
        • "class": "IN",
        • "name": "hostname.example.com.",
        • "ttl": 86400,
        • "type": "A"
        }
      ]
    },
  • "metadata": {
    • "command": "getzonerecord",
    • "reason": "Record obtained.",
    • "result": 1,
    • "version": 1
    }
}

Return whether DNS cluster server can share records

This function queries whether nameservers in a DNS cluster can share records with one another. Servers in a DNS cluster must exist in a Reverse Trust relationship to share information. This relationship requires each server to have an API token.

Note:

DNS servers in a Write-Only role do not need to exist in a Reverse Trust relationship. For more information, read our Guide to DNS Cluster Configurations documentation.

Authorizations:
BasicAuth
query Parameters
althost
string <ipv4>
Default: ""
Example: althost=192.0.3.0

The nameserver's alternate IP address. This is useful, for example, if your DNS cluster exists in a NAT-configured network.

host
required
string <ipv4>
Example: host=192.0.2.0

The nameserver's IP address.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cluster_member_has_trust_with \
  host='192.0.2.0'

Response samples

Content type
application/json
{
  • "data": {
    • "has_trust": 1
    },
  • "metadata": {
    • "command": "cluster_member_has_trust_with",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete DNS zone

This function deletes a DNS zone.

Important:

  • The WHM API 1 adddns function adds an XDNS entry for a domain in the following locations:
  • The /var/cpanel/users/USER file, where USER represents the domain's owner.
  • The /etc/vdomainaliases/DOMAIN directory, where DOMAIN represents the new zone's domain.
  • The /etc/vfilters/DOMAIN directory, where DOMAIN represents the new zone's domain.
  • This function does not automatically delete these entries. You must manually delete these entries, or you cannot use this domain as a value in other API functions.
  • You cannot delete other DNS zones that reside on Write-only servers in a DNS cluster.

Important:

When you disable the DNS role, the system disables this function.

NOTE:

You cannot use this function to delete temporary domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The zone record's domain.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  killdns \
  domain='example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "killdns",
    • "output": {
      • "raw": "example.com => deleted from example."
      },
    • "reason": "Zones Removed",
    • "result": 1,
    • "version": 1
    }
}

Return domain's DNS zone configuration Deprecated

This function returns a domain's DNS zone configuration.

Important:

  • This function is deprecated. Use WHM's parse_dns_zone function.
  • You must include either the domain or the zone parameters.
  • When you disable the DNS role, the system disables this function.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The zone record's domain.

zone
string
Example: zone=example.com.db

The zone file's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  dumpzone \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "zone": [
      • {
        • "address": "192.168.0.20",
        • "type": "A",
        • "Line": 1,
        • "class": "IN",
        • "name": "hostname.example.com",
        • "ttl": 86400
        }
      ]
    },
  • "metadata": {
    • "command": "dumpzone",
    • "reason": "Zone Serialized",
    • "result": 1,
    • "version": 1
    }
}

Export DNS zones in zone file format

This function returns one or more DNS zones, in RFC-1035 format.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
zone
required
Array of strings <domain> [ items <domain > ]
Example: zone=example.com&zone=example.net

The DNS zones to display.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  export_zone_files \
  zone='example.com' zone='example.net'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "text_b64": "AAAABBCCDdshjke==",
        • "zone": "example.com"
        },
      • {
        • "text_b64": "BBBBCCDDDdshjke==",
        • "zone": "example.net"
        }
      ]
    },
  • "metadata": {
    • "command": "export_zone_files",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update a DNS zone

This function updates a given DNS zone. It can add, edit, and remove many records in a single call. It also ensures that each record not removed will occupy the same number of lines after the edit as it did before the edit.

NOTE:

You cannot use this function to modify temporary domains.

Authorizations:
BasicAuth
query Parameters
add
Array of strings <json> [ items <json > ]
Examples:
  • add='{"dname":"example", "ttl":14400, "record_type":"A", "data":["11.22.33.44"]}' - An A record.
  • add='{"dname":"example", "ttl":14400, "record_type":"TXT", "data":["string1", "string2"]}' - A TXT record.

The records to add to the zone. Each item must be a serialized JSON object that contains:

  • dname — The record’s name.
  • ttl — The record’s TTL (Time-To-Live) value.
  • record_type — The record’s type. For example, A or TXT.
  • data — An array of strings. The format and number of the strings depend on the record_type value.
edit
Array of strings <json> [ items <json > ]
Example: edit='{"line_index": 9, "dname":"example", "ttl":14400, "record_type": "TXT", "data":["string1", "string2"]}'

The records to edit in the zone. Each item must be a serialized JSON object that contains:

  • line_index — The line number in the DNS zone where the record starts. This is a 0-based index, so to edit the first line in the file use the 0 value. To edit the second line, give 1, and so forth.
  • dname — The record’s name.
  • ttl — The record’s TTL (Time-To-Live) value.
  • record_type — The record’s new type. For example, A or TXT.
  • data — An array of strings. The format and number of the strings depend on the record_type value.
remove
Array of integers[ items >= 0 ]
Example: remove=22

The line indexes of records to remove from the zone.

serial
required
integer >= 0
Example: serial=202001010100

The current serial number in the DNS zone’s SOA (Start of Authority) record. If this value does not match the zone’s current state, the request fails.

zone
required
string
Example: zone=example.com

The name of one of the user’s DNS zones.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 mass_edit_dns_zone zone='example.com' serial='202001010100' remove=23 add='{"dname":"example", "ttl":14400, "record_type":"A", "data":["11.22.33.44"]}'

Response samples

Content type
application/json
{
  • "data": {
    • "new_serial": 2021031903
    },
  • "metadata": {
    • "command": "mass_edit_dns_zone",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return a parsed DNS zone

This function parses a given DNS zone.

Important:

Most DNS zones contain only 7-bit ASCII. However, it is possible for DNS zones to contain any binary sequence. An application that decodes this function's base64 output must be able to handle cases where the decoded octets do not match any specific character encoding.

Authorizations:
BasicAuth
query Parameters
zone
required
string
Example: zone=example.com

The name of one of the user’s DNS zones.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 parse_dns_zone zone='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "line_index": 22,
        • "type": "record",
        • "data_b64": [
          • "dGV4YXMuY29tLg=="
          ],
        • "dname_b64": "dGV4YXMuY29tLg==",
        • "record_type": "MX",
        • "ttl": 14400
        }
      ]
    },
  • "metadata": {
    • "command": "parse_dns_zone",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create DNS zone

This function creates a DNS zone. If trueowner=user, this function does the following:

  • Adds a DNS entry in the /var/cpanel/users/USER file, where USER represents the trueowner parameter's value.
  • Creates the /etc/vdomainaliases/DOMAIN file, where DOMAIN represents the new zone's domain.
  • Creates the /etc/vfilters/DOMAIN file, where DOMAIN represents the new zone's domain.

When you call this function, the system uses the domain name and IP address that you supply. WHM's standard zone template determines all other zone information.

This function generates the DNS zone's MX record, domain PTR, and A records automatically.

Important:

When you disable the DNS role, the system disables this function.

NOTE:

You cannot use this function to add temporary domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The new zone's domain.

has_ipv6
integer
Default: 0
Possible Values: 0 1
Example: has_ipv6=1

Whether to add an IPv6 address to the new zone.

  • 1 — Add the IPv6 address in the ipv6 parameter to the new zone.
  • 0 — Do not add an IPv6 address to the new zone.
ip
required
string <ipv4>
Example: ip=192.168.0.20

The domain's IP address.

ipv6
string or null <ipv6>
Example: ipv6=2001:0db8:0:0:1:0:0:1

The domain's IPv6 address.

template
string
Default: "standard"
Example: template=standard

The zone file template.

  • standard
  • simple
  • standardvirtualftp
  • The name of a custom zone template file in the /var/cpanel/zonetemplates directory.
trueowner
string or null <username>
Example: trueowner=user

The new zone's owner. This parameter defaults to the currently-authenticated user.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  adddns \
  domain='example.com' \
  trueowner='user' \
  ip='192.168.0.20'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "adddns",
    • "reason": "Added example.com ok belonging to user user",
    • "result": 1,
    • "version": 1
    }
}

Domain Management

DNS / Domain Management

Return `ALIAS` DNS record availability & resolver

This function returns whether ALIAS and ANAME records are available and the value of the running PowerDNS (PDNS) resolver setting, if any exists. For more information, read our ALIAS documentation.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  is_alias_available

Response samples

Content type
application/json
{
  • "data": {
    • "alias": 1,
    • "aname": 0,
    • "resolver": "8.8.8.8"
    },
  • "metadata": {
    • "command": "is_alias_available",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain's DS record

This function fetches a domain's Delegation of Signing (DS) record.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Examples:
  • domain=domain=example.com&domain-1=example1.com&domain-2=example2.com - Multiple domains
  • domain=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains
  • domain=example.com - A single domain.

The domain to fetch a DS record from.

Note:

To fetch records from multiple domains, duplicate or increment the parameter name. For example, to check three domains, you could:

  • Use the domain parameter multiple times.
  • Use the domain, domain-1, and domain-2 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_ds_records_for_domains \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "domain": "example.com",
        • "ds_records": {
          • "keys": {
            • "40481": {
              • "active": 1,
              • "algo_desc": "RSA/SHA-256",
              • "algo_num": 8,
              • "algo_tag": "RSASHA256",
              • "bits": 2048,
              • "created": 1575395316,
              • "digests": [
                • {
                  • "algo_desc": "SHA-1",
                  • "algo_num": 1,
                  • "digest": "2808a14b89118256119d93d24b9e6b673dca092b"
                  },
                • {
                  • "algo_desc": "SHA-256",
                  • "algo_num": 2,
                  • "digest": "02a57812deb952438382ed8dd20f00d4af844a55b5324d28bb"
                  },
                • {
                  • "algo_desc": "SHA-384",
                  • "algo_num": 4,
                  • "digest": "4569a6fcfe9e151ec6a163307e67eaa3a9547f16cd80751b0d46eb498bd96743bd4ff7c4f6fd5f76cc780aeb979cd08d"
                  }
                ],
              • "flags": 257,
              • "key_id": 1,
              • "key_tag": 40481,
              • "key_type": "KSK",
              • "privatekey": "Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: syUlztxieV1aOtuYAGGA4VBxgquwqPTWQXcDVY1VRFcPgFmLMWYr6dDnN4OUhu2yIulK3KMeZmAc/DmwM+yNdCdYc9y84gw5OyONKduuPGYXfwCiJfOJ+NpGaFomK6fVFN8BMi6LUBytdA4gotPw45Uz8FIbl1KsEOnV4/ZpjiM=\nPublicExponent: AQAB\nPrivateExponent: LxIfsQ7vQPxqbPSuJ8t21b0RVkhOjtZmRaVD1wLf2KkXhZ4BmOVDvJgLaObF6/4gxFOQPBEQN84hT5TI25vYPrAwRAlP/yGmQ4Z2aPIYeEawoqqNoYEa5Xjs1X90i6/+Y8mJSZpGvr4/Y4ElothZTUw+LCYb6o9ulg53yya8KUE=\nPrime1: 4od92Rbx9fSXRIk6eSSdTYN/Do3zgDiCuxmuZaCrrEAlkiK11iz/s4aZGj9+Yk4NfusjXr3NqU1OMfBiIp67Sw==\nPrime2: ynOJdz/E4/B6iBtuz/4y0kasljMtiJnaNIxPr4LG+hByx7WWCnaPm6p8g1pz3FC/w7HAdWq9xzR1VnbRPGcZiQ==\nExponent1: KUKmkIEWZ0c6ujgIl4IsyK6X2O3QGV2xqiSeWFJwknpInZqG5lDh7jAo+NfxzDQNTz3C/oGx0RGMmZoANfAViw==\nExponent2: ZcFkmpdmstqv+7EuJUSy7pWvMV9Px5Ts4/SSKLkmoZGa314Zp/CnhapPIwZXrai4effhsCKSeImZYHgf+qgnYQ==\nCoefficient: PBQUQquZB0kG//cy8oVA6nHvKkvVJ8zV4GVlkXHTDylbjoWBTuNWwQ93t5SM7Rz3JePHImWdOVMYNIXpPlp56g==\n"
              }
            },
          • "nsec_details": {
            • "nsec3_hash_algo_desc": "SHA-1",
            • "nsec3_hash_algo_num": 1,
            • "nsec3_iterations": 7,
            • "nsec3_narrow": 1,
            • "nsec3_opt_out": 0,
            • "nsec3_salt": "1a2b3c4d5e6f",
            • "nsec_version": "NSEC3"
            }
          }
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_ds_records_for_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate local server is authoritative

This function checks whether the local server has the authority to publish changes for the domain's DNS records.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example.com domain-1=example1.com domain-2=example2.com - Multiple domains
  • domain=example.com - A single domain

The domain to check whether the local server is authoritative for the domain's DNS records.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, to check three domains, use the domain parameter multiple times. Or the domain, domain-1, and domain-2 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  has_local_authority \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "records": [
      • {
        • "domain": "example.com",
        • "error": "(XID qdbmuk) DNS query (example3.com/SOA) timeout!",
        • "local_authority": 1,
        • "nameservers": [
          • "ns1.example.com",
          • "ns2.example.com"
          ],
        • "zone": "example.com"
        }
      ]
    },
  • "metadata": {
    • "command": "has_local_authority",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore DNS zone to default values

This function resets a DNS zone to its default values. This also resets the domain's subdomain DNS records, and restores zone file subdomains in the server's httpd.conf file. For example, use this function to restore DNS zones that are corrupt.

Note:

Zone resets preserve valid TXT records, but all other records will return to their default values.

Important:

When you disable the DNS role, the system disables this function.

Note

You must include either the domain or the zone parameters.

Authorizations:
BasicAuth
query Parameters
domain
string <domain>
Example: domain=example.com

The domain.

user
string <username>
Example: user=user

The domain's owner.

zone
string
Example: zone=example.com.db

The zone file.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  resetzone

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "resetzone",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create mail exchanger record

This function creates a new MX record.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
class
string
Default: "IN"
Example: class=IN

The record's class.

domain
required
string <domain>
Example: domain=example.com

The zone record's domain.

exchange
required
string <domain>
Example: exchange=mail.example.com

The domain's mail exchanger.

name
required
string
Example: name=mail.example.com

The record name.

preference
required
integer >= 1
Example: preference=20

The MX record's priority order.

Note:

Lower numbers indicate a higher priority order.

ttl
integer >= 1
Default: 14400
Example: ttl=14400

The record's Time To Live (TTL) in seconds.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  savemxs \
  domain='example.com' \
  name='mail.example.com' \
  exchange='mail.example.com' \
  preference='20'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "savemxs",
    • "reason": "Bind reloading on server1 using rndc zone: [example.com]\n",
    • "result": 1,
    • "version": 1
    }
}

Enable NSEC3 semantics for domain

This function configures the domain to use Next Secure Record 3 (NSEC3) semantics.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The domain for which to enable NSEC3 semantics.

nsec3_iterations
required
integer [ 0 .. 500 ]
Example: nsec3_iterations=7

The number of times that the system re-executes the first resource record hash operation.

nsec3_narrow
required
integer
Possible Values: 0 1
Example: nsec3_narrow=1

Whether NSEC3 will operate in Narrow mode or Inclusive mode.

Note

For information about these modes, read PowerDNS's DNSSEC documentation.

  • 1 - Narrow mode.
  • 0 - Inclusive mode.
nsec3_opt_out
required
integer
Possible Values: 0 1
Example: nsec3_opt_out=0

Whether the system will create records for all delegations.

  • 1 - Create records for all delegations.
  • 0 - Create records only for secure delegations.

Note

Only select 1 if you must create records for all delegations.

nsec3_salt
required
string
Example: nsec3_salt=1a2b3c4d5e6f

The salt value that PowerDNS uses in the hashes.

Note:

For information about salt values, read RFC 5155.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_nsec3_for_domains \
  domain='example.com' \
  nsec3_opt_out='0' \
  nsec3_iterations='7' \
  nsec3_narrow='1' \
  nsec3_salt='1a2b3c4d5e6f'

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "domain": "example.com",
        • "enabled": 1,
        • "error": "Error message."
        }
      ]
    },
  • "metadata": {
    • "command": "set_nsec3_for_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable NSEC semantics for domain

This function configures the domain to use Next Secure Record (NSEC) semantics instead of Next Secure Record 3 (NSEC3) semantics.

Note:

Only servers that run PowerDNS can use DNSSEC. If you call this function on a server that doesn't use PowerDNS, you will receive an error.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to disable NSEC3 semantics and use NSEC semantics.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  unset_nsec3_for_domains \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "disabled": 1,
        • "domain": "example.com",
        • "error": "Error message."
        }
      ]
    },
  • "metadata": {
    • "command": "unset_nsec3_for_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create DNS zone record

This function adds a DNS zone record.

Important:

  • When you call this function, you must include the additional parameters for the selected zone record type.
  • When you disable the DNS role, the system disables this function.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth
Request Body schema: application/x-www-form-urlencoded
required
string or string

The record's class.

domain
required
string <domain>

The new zone record's domain.

name
required
string <domain>

The record's name.

Note:

Do not omit any necessary trailing periods.

You cannot use this function to add temporary domains.

type
required
string

The DNS record type:

  • A - A records store IPv4 addresses. Use them to map a hostname to an IPv4 address.
  • A6 - A6 records store IPv6 addresses.
  • AAAA - AAAA records store IPv6 addresses.
  • AFSDB - AFSDB records store the location of an AFS cell's database servers.
  • ALIAS - ALIAS records create an alias to another hostname, but can coexist with other records on that name. We strongly discourage using this record type.
  • CAA - CAA records control which certificate authorities can issue SSL certificates for a domain.
  • CNAME - CNAME records create an alias to another hostname.
  • DNAME - DNAME records create an alias for a hostname and its subnames.
  • DS - DS records specify a record's delegation signer.
  • HINFO - HINFO records specify a host's CPU and OS types.
  • LOC - LOC records store a hostname's geographical location.
  • MX - MX records point a domain name to its MTAs.
  • NS - NS records store a domain's authoritative nameservers.
  • PTR - PTR records point to a CNAME.
  • RP - RP records store a domain's Responsible Person's information.
  • SOA - SOA records designate the beginning of a zone of authority.
  • SRV - SRV records store the service location records for newer protocols (for example, Autodiscover).
  • TXT - TXT records store descriptive text or useful records (for example, SPF or DKIM records).

When you call this function, you must include the additional parameters for the desired zone record type. Select a zone record from the menu to view the required additional parameters:

address
string <ipv4>

The zone record's IPv4 address.

Note:

For more information about A records, read RFC 1035 at IANA.

ttl
integer >= 1
Default: 86400

The record's Time To Live (TTL), in seconds.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --input=json --output=jsonpretty \
  addzonerecord

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "addzonerecord",
    • "reason": "Bind reloading on hostname using rndc zone: [example.com]\n",
    • "result": 1,
    • "version": 1
    }
}

Return domain's IP address

This function resolves a domain's IPv4 address.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The domain.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  resolvedomainname \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "192.168.0.20"
    },
  • "metadata": {
    • "command": "resolvedomainname",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain's mail exchanger records

This function lists a domain's MX records.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The zone record's domain.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listmxs \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "record": [
      • {
        • "Line": 1,
        • "class": "IN",
        • "exchange": "mail.example.com",
        • "name": "hostname.example.com",
        • "preference": 20,
        • "ttl": 86400,
        • "type": "MX"
        }
      ]
    },
  • "metadata": {
    • "command": "listmxs",
    • "reason": "Records obtained.",
    • "result": 1,
    • "version": 1
    }
}

Create domain alias

This function creates an alias (parks a domain on a web virtual host).

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=park.example.com

The domain name to park.

username
required
string
Example: username=username

The cPanel user account.

web_vhost_domain
required
string
Example: web_vhost_domain=vhost.example.com

An existing web virtual host to which the new domain name should be added.

Note:

If this is not the cPanel account’s main domain, then the system will consider the new domain to be an addon domain.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  create_parked_domain_for_user \
  domain='park.example.com' \
  username='username' \
  web_vhost_domain='vhost.example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "create_parked_domain_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create subdomain

This function creates a subdomain.

Authorizations:
BasicAuth
query Parameters
document_root
required
string
Example: document_root=public_html/directory_name

The subdomain's document root within the home directory.

Note:

  • An invalid document root path will cause this function to fail.
  • If the Restrict document roots to public_html value is set to On in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings), this parameter must begin with the public_html/ path. For more information, read the cpanel.config file documentation.
domain
required
string <domain>
Example: domain=subdomain.example.com

The subdomain name to create.

use_canonical_name
integer
Default: 0
Possible Values: 0 1
Example: use_canonical_name=0

Whether to use a canonical name in the Apache® configuration for self-referential URLs.

  • 1 — Use the canonical name.
  • 0 — Do not use the canonical name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_subdomain \
  domain='subdomain.example.com' \
  document_root='public_html/directory_name'

Response samples

Content type
application/json
{
  • "data": {
    • "username": "example"
    },
  • "metadata": {
    • "command": "create_subdomain",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete domain

This function deletes a domain.

Note:

This function does not remove an addon domain's associated subdomain. You must also run this function for the associated subdomain.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The name of the domain to delete.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_domain \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "type": "addon",
    • "username": "username"
    },
  • "metadata": {
    • "command": "delete_domain",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update /etc/userdomains file

This function updates the /etc/userdomains file based on the entries in /var/cpanel/users directory.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  updateuserdomains

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "updateuserdomains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Resolvers

DNS / Resolvers

Return `ALIAS` DNS record availability & resolver

This function returns whether ALIAS and ANAME records are available and the value of the running PowerDNS (PDNS) resolver setting, if any exists. For more information, read our ALIAS documentation.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  is_alias_available

Response samples

Content type
application/json
{
  • "data": {
    • "alias": 1,
    • "aname": 0,
    • "resolver": "8.8.8.8"
    },
  • "metadata": {
    • "command": "is_alias_available",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create unbound DNS resolver

This function creates an Unbound (libunbound) DNS resolver configuration.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_up_dns_resolver_workarounds

Response samples

Content type
application/json
{
  • "data": {
    • "flags": {
      • "do-ip6": "no",
      • "do-udp": "no",
      • "edns-buffer-size": "512"
      }
    },
  • "metadata": {
    • "command": "set_up_dns_resolver_workarounds",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's nameservers

This function retrieves the default nameservers for the currently-authenticated user.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_nameserver_config

Response samples

Content type
application/json
{
  • "data": {
    • "nameservers": [
      • "ns1.example.com",
      • "ns2.example.com"
      ]
    },
  • "metadata": {
    • "command": "get_nameserver_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return nameserver's IP address

This function retrieves a nameserver's IP address.

Authorizations:
BasicAuth
query Parameters
host
required
string <domain>
Example: host=ns1.example.com

The nameserver's hostname.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  lookupnsip \
  host='ns1.example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "192.168.0.20"
    },
  • "metadata": {
    • "command": "lookupnsip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return nameserver's IPv4 and IPv6 addresses

This function retrieves a nameserver's IPv4 and IPv6 addresses.

Authorizations:
BasicAuth
query Parameters
host
required
string
Example: host=ns1.example.com

The nameserver's hostname.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  lookupnsips \
  host='ns1.example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "ipv4": "192.0.2.0",
    • "ipv6": "2001:0db8:0:0:1:0:0:1"
    },
  • "metadata": {
    • "command": "lookupnsips",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update server's resolver nameservers

This function configures the server's resolver nameservers.

Warning:

  • The nameservers that the server uses as resolvers must function correctly. If they do not, the server will experience performance and stability issues.
  • Never set a resolver nameserver to 127.0.0.1 on a cPanel & WHM server.
Authorizations:
BasicAuth
query Parameters
required
string or string
Example: nameserver1=192.168.0.20

The server's primary resolver nameserver.

required
string or string <ipv4>
Example: nameserver2=192.168.0.21

The server's secondary resolver nameserver.

string or string
Default: ""
Example: nameserver3=2001:4860:4860::8888

The server's tertiary resolver nameserver.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setresolvers \
  nameserver1='192.168.0.20' \
  nameserver2='192.168.0.21'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setresolvers",
    • "output": {
      • "messages": "Listed in order they are:\n192.168.0.20\n192.168.0.21\n2001:4860:4860::8888\n"
      },
    • "reason": "Your resolvers have been setup!",
    • "result": 1,
    • "version": 1
    }
}

Update default nameservers

This function updates nameservers in the wwwacct.conf file. For more information, read our Installation Guide - Customize Your Installation documentation.

Authorizations:
BasicAuth
query Parameters
nameserver
string <domain>
Example: nameserver=ns1.example.com

The nameserver to add or update as the wwwacct.conf file's NS setting. If you do not supply a value, the function does not update the setting.

nameserver2
string <domain>
Example: nameserver2=ns2.example.com

The nameserver to add or update as the wwwacct.conf file's NS2 setting. If you do not supply a value, the function does not update the setting.

nameserver3
string <domain>
Example: nameserver3=ns3.example.com

The nameserver to add or update as the wwwacct.conf file's NS3 setting. If you do not supply a value, the function does not update the setting.

nameserver4
string <domain>
Example: nameserver4=ns4.example.com

The nameserver to add or update as the wwwacct.conf file's NS4 setting. If you do not supply a value, the function does not update the setting.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_nameservers_config

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_nameservers_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Feature Access

Hosting Plans / Feature Access

Return cPanel account feature access

This function checks whether a user has access to a feature on a feature list.

Authorizations:
BasicAuth
query Parameters
feature
required
string
Example: feature=sslinstall

The feature's ID.

Note:

Call WHM API 1's get_feature_names function to view available features.

user
required
string <username>
Example: user=username

The cPanel account username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_user_has_feature \
  user='username' \
  feature='sslinstall'

Response samples

Content type
application/json
{
  • "data": {
    • "has_feature": 1,
    • "query_feature": "sslinstall"
    },
  • "metadata": {
    • "command": "verify_user_has_feature",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove cPanel account feature list overrides

This function removes feature overrides from a cPanel account.

Authorizations:
BasicAuth
query Parameters
features
required
Array of strings
Example: features=["sslinstall","videotut"]

An array that contains the features' names.

Note:

  • Call WHM API 1's get_feature_names function to view available features.
user
required
string <username>
Example: user=username

The user's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_override_features_for_user \
  user='username' \
  features='["sslinstall","videotut"]'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "remove_override_features_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel accounts' feature settings

This function lists the features settings of cPanel accounts.

Authorizations:
BasicAuth
query Parameters
feature
string
Examples:
  • feature=feature-1=autossl feature-2=addoncgi feature-3=addondomains - Multiple feature.
  • feature=autossl - A single feature.

The feature's name.

Note:

  • To check multiple features, increment the parameter name. For example, feature-1, feature-2, and feature-3.
  • If you use this parameter, you must enter a feature name, or the function returns an error. If you do not use this parameter, the function returns data for all features on the server.
user
required
string
Examples:
  • user=user-1=example1 user-2=example2 user-3=example3 - Multiple users.
  • user=example - A single user.

The user's username.

Note:

To check multiple users, increment the parameter name. For example, user-1, user-2, and user-3.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_users_features_settings \
  user='example'

Response samples

Content type
application/json
{
  • "data": {
    • "users_features_settings": [
      • {
        • "cpuser_setting": 1,
        • "feature": "autossl",
        • "feature_list": "autossl",
        • "feature_list_setting": 1,
        • "user": "example"
        }
      ]
    },
  • "metadata": {
    • "command": "get_users_features_settings",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add cPanel account feature list overrides

This function adds feature overrides to a cPanel account.

Authorizations:
BasicAuth
query Parameters
required
object
Example: features={"backup":1}

A JSON-encoded list of features to override and whether to enable or disable them.

user
required
string <username>
Example: user=username

The cPanel username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  add_override_features_for_user \
  user='username' \
  features='{"backup":"1"}'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "add_override_features_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Feature Lists

Hosting Plans / Feature Lists

Return dynamicui file

This function returns the contents of a dynamicui file. For more information, read our Guide to WHM dynamicui Files documentation.

Authorizations:
BasicAuth
query Parameters
applications_list
string
Example: applications_list=create_support_ticket

A comma-separated list of the application entries to return.

To determine the application's name, find its file value in the dynamicui.conf file, and then remove the file extension.

If you do not specify this value, the function returns the entire dynamicui.conf file.

file
string
Default: "dynamicui.conf"
Example: file=dynamicui.conf

The dynamicui configuration file to retrieve, relative to the /usr/local/cpanel/whostmgr/docroot/themes/x/ directory.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_available_applications

Response samples

Content type
application/json
{
  • "data": {
    • "groups": [
      • {
        • "acl": "ACL=all",
        • "dnsonly_ok": "dns",
        • "file": "feature_name.png",
        • "group": "group_name",
        • "groupdesc": "$LANG{'Group Name'}",
        • "grouporder": 1,
        • "imgtype": "icon",
        • "items": [
          • {
            • "acl": "ACL=all",
            • "description": "View and manage reseller accounts on your server. Resellers manage other [asis,cPanel] accounts and can access [asis,cPanel].",
            • "dnsonly_ok": "dns",
            • "file": "feature_name.png",
            • "group": "group_name",
            • "imgtype": "icon",
            • "itemdesc": "$LANG{'Feature Name'}",
            • "itemorder": 1,
            • "key": "feature_name",
            • "minimum_accounts_needed": 2,
            • "multiuser_required": 1,
            • "role": {
              • "match": "any",
              • "roles": [
                • "MailLocal",
                • "MailSend"
                ]
              },
            • "searchtext": "search keywords",
            • "service": "mysql",
            • "subitems": [
              • {
                • "acl": "ACL=all",
                • "breadcrumb": "/example_plugin/feature_name",
                • "dnsonly_ok": "dns",
                • "file": "feature_name.png",
                • "group": "group_name",
                • "itemdesc": "$LANG{'Feature Name'}",
                • "key": "feature_name",
                • "parent": 1,
                • "searchtext": "search keywords",
                • "target": "_blank",
                • "type": "subitem",
                • "url": "/example_plugin/feature_name"
                }
              ],
            • "subtype": "img",
            • "target": "_blank",
            • "type": "image",
            • "url": "/example_plugin/feature_name"
            }
          ],
        • "key": "feature_name",
        • "searchtext": "search keywords",
        • "subtype": "img",
        • "target": "_blank",
        • "type": "group"
        }
      ],
    • "raw": [
      • {
        • "itemdesc": "[% PROCESS 'menu/plugins_list.tmpl' target='mainFrame' -%]",
        • "type": "raw"
        }
      ]
    },
  • "metadata": {
    • "command": "get_available_applications",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create feature list

This function creates or updates a feature list.

Note:

A reseller must possess the Add/Remove Package feature to use this function.

Authorizations:
BasicAuth
query Parameters
featurelist
required
string
Example: featurelist=CustomFeatureList

The feature list's name.

featurelistname
integer
Default: 0
Possible Values: 1 0
Example: featurelistname=1

Whether to add a specific feature in the feature list.

  • 1 — Add the feature.
  • 0 — Do not add the feature.

Note:

  • The parameter's name is a feature's name. For example, the changemx=1 adds the Change Mail Exchanger feature to the feature list.

  • You can add or omit multiple features.

overwrite
integer
Default: 0
Possible Values: 1 0
Example: overwrite=1

Whether to overwrite an existing feature list.

  • 1 — Overwrite.
  • 0 — Do not overwrite.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_featurelist \
  featurelist=Arthur webmail=1 changemx=1 overwrite=1

Response samples

Content type
application/json
{
  • "data": {
    • "featurelist": "Arthur"
    },
  • "metadata": {
    • "command": "create_featurelist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete feature list

This function deletes a feature list.

Authorizations:
BasicAuth
query Parameters
featurelist
required
string
Example: featurelist=TestList

The feature list's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_featurelist \
  featurelist='TestList'

Response samples

Content type
application/json
{
  • "data": {
    • "deleted_featurelist": "TestList"
    },
  • "metadata": {
    • "command": "delete_featurelist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's available feature lists info

This function lists the details of the authenticated user's available feature lists.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_feature_metadata

Response samples

Content type
application/json
{
  • "data": {
    • "features": [
      • {
        • "id": "addondomains",
        • "is_cpaddon": 0,
        • "is_plugin": 0,
        • "name": "Addon Domain Manager"
        }
      ]
    },
  • "metadata": {
    • "command": "get_feature_metadata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all features

This function lists all available features.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_feature_names

Response samples

Content type
application/json
{
  • "data": {
    • "feature": [
      • {
        • "id": "sslmanager",
        • "name": "SSL Manager"
        }
      ]
    },
  • "metadata": {
    • "command": "get_feature_names",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return feature list configuration

This function lists features in a specific feature list.

Authorizations:
BasicAuth
query Parameters
featurelist
required
string
Example: featurelist="Mail Only"

The feature list for which to list information.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_featurelist_data \
  featurelist='"Mail Only"'

Response samples

Content type
application/json
{
  • "data": {
    • "featurelist": "Mail Only",
    • "features": [
      • {
        • "id": "email_trace",
        • "is_disabled": 0,
        • "value": 1
        }
      ]
    },
  • "metadata": {
    • "command": "get_featurelist_data",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's available feature lists

This function lists the authenticated user's available feature lists.

Notes:

  • When you call this function with the root account, it returns all feature lists on the server.
  • When you call this function with a reseller account, it only returns feature lists that the account owns.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_featurelists

Response samples

Content type
application/json
{
  • "data": {
    • "featurelists": [
      • "default",
      • "disabled",
      • "reseller1_test1",
      • "reseller1_test2"
      ]
    },
  • "metadata": {
    • "command": "get_featurelists",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update feature list

This function creates or updates a feature list.

Authorizations:
BasicAuth
query Parameters
feature name
integer
Possible Values: 0 1
Example: feature name=1

Whether to include the feature in the feature list.

Notes:

This parameter's name is the feature's name. If you do not specify any features, the system will disable all features in the feature list.

featurelist
required
string
Example: featurelist=TheBlackLagoon

The feature list's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  update_featurelist \
  featurelist='TheBlackLagoon'

Response samples

Content type
application/json
{
  • "data": {
    • "featurelist": "TheBlackLagoon",
    • "invalid_features": [
      • {
        • "invalid feature": 1
        }
      ],
    • "updated_features": {
      • "autoresponders": null,
      • "feature name": 1
      }
    },
  • "metadata": {
    • "command": "update_featurelist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Hosting Plan Extensions

Hosting Plans / Hosting Plan Extensions

Add hosting plan extension

This function adds a package extension to a hosting plan (package).

Notes:

  • If you need to edit a package extension's parameters, call this function again with the same package extension name and the updated package extension variables.

  • You can include the extension's variables in your function call, in key=value format. Consult the extension's documentation for a list of possible variables. Extension variables are case-sensitive.

Authorizations:
BasicAuth
query Parameters
_PACKAGE_EXTENSIONS
required
string
Examples:
  • - Add multiple package extensions.
  • - Add a single package extension.

The hosting plan's package extensions.

Note:

  • Use space-delimited format to add multiple package extensions.
  • Extension names are case-sensitive.
name
required
string
Example: name=package1

The hosting plan's name.

Note:

You cannot use the extensions name for a hosting plan.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  addpkgext \
  name='package1' \
  _PACKAGE_EXTENSIONS='extension1'

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": "package1"
    },
  • "metadata": {
    • "command": "addpkgext",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove hosting plan extension

This function deletes a package extension from a hosting plan (package).

Note:

  • You can additionally include extension's variables in your function call, in key=value format. Consult the extension's documentation for a list of possible variables. Extension variable names are case-sensitive.
Authorizations:
BasicAuth
query Parameters
_DELETE_EXTENSIONS
required
string
Example:

The space delimited package extensions to delete.

Note:

  • Extension names are case-sensitive.
name
required
string
Example: name=package1

The hosting plan's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delpkgext \
  name='package1' \
  _DELETE_EXTENSIONS='extension1 extension2'

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": "package1"
    },
  • "metadata": {
    • "command": "delpkgext",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return hosting plan extension templates

This function retrieves a hosting plan's package extension templates. When you call this function, the system checks the hosting plan's _PACKAGE_EXTENSIONS value. The function returns the contents of the /var/cpanel/packages/extensions/name.tt2 file for each package extension in the list, where name represents the package extension's name.

For more information, read our Guide to Package Extensions.

Note:

This function returns only metadata if the hosting plan does not use package extensions, or if the extensions' template files are empty.

Authorizations:
BasicAuth
query Parameters
pkg
required
string
Example: pkg=package1

The hosting plan's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  _getpkgextensionform \
  pkg='package1'

Response samples

Content type
application/json
{
  • "data": {
    • "html": "<div class=\"fatBorder\" id=\"dog_Extension\"> <fieldset class=\"groupEditor\"> <div class=\"propertyGroup\"> <h3>Dog Settings</h3> <div class=\"propertyEditor\"> <div class=\"propertyLabel\">Dog Species</div> <div class=\"propertyValue\"><input id=\"dog_species\" type=\"text\" name=\"dog_species\" value=\"dalmatian\"></div> </div> <div class=\"propertyEditor\"> <div class=\"propertyLabel\">Tail Length</div> <div class=\"propertyValue\"> <input type=\"radio\" id=\"dogTailLengthTiny\" name=\"dog_tail_length\" value=\"tiny\"> <label for=\"dogTailLengthTiny\">Tiny</label><br> <input type=\"radio\" id=\"dogTailLengthNormal\" name=\"dog_tail_length\" value=\"normal\"> <label for=\"dogTailLengthNormal\">Normal</label><br> <input type=\"radio\" id=\"dogTailLengthLong\" name=\"dog_tail_length\" value=\"long\"> <label for=\"dogTailLengthLong\">Long</label> </div> </div> <div class=\"propertyEditor\"> <div class=\"propertyLabel\"><label for=\"dog_spots\">Has Spots</label></div> <div class=\"propertyValue\"> <input id=\"dog_spots\" type=\"checkbox\" name=\"dog_spots\" value=\"y\" checked=\"checked\"> </div> </div> </div> </fieldset> </div>"
    },
  • "metadata": {
    • "command": "_getpkgextensionform",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Hosting Plans

Hosting Plans / Hosting Plans

Delete hosting plan

This function deletes a hosting plan (package).

Authorizations:
BasicAuth
query Parameters
pkgname
required
string
Example: pkgname=package1

The hosting plan's name.

Note:

You cannot delete a hosting plan that a cPanel account currently uses.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  killpkg \
  pkgname='package1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "killpkg",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create hosting plan

This function creates a hosting plan (package).

Note:

The Access Control Lists restricts some of this function's parameters, which limit the features that WHM users can access.

Authorizations:
BasicAuth
query Parameters
_PACKAGE_EXTENSIONS
string
Example: _PACKAGE_EXTENSIONS='extension1 extension2 extension3'

A space-separated list of the hosting plan's package extensions.

If you do not provide a value, the hosting plan will not include package extensions.

Note:

  • We strongly recommend that you manage package extensions through WHM API 1's addpkgext and delpkgext functions.
  • You can include the extension's variables in your function call, in key=value format. Consult the extension's documentation for a list of possible variables.
  • Extension names and variables are case-sensitive.
integer or any or any or string
Default: 1048576
Example: bwlimit=1048576

The hosting plan's maximum bandwidth use, in megabytes (MB).

  • 0, unlimited, or null — The hosting plan allows unlimited bandwidth.

Note:

The 0, unlimited, and null values are only available to users that possess the corresponding unlimited ACL permission.

cgi
integer
Default: 1
Possible Values: 1 0
Example: cgi=1

Whether CGI access is enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

Note:

When a server profile disables the Web Server role, this parameter defaults to 0. On these servers, you cannot enable CGI access.

cpmod
string
Example: cpmod=jupiter

The hosting plan's cPanel theme.

This parameter defaults to the server's default cPanel theme.

digestauth
integer
Default: 0
Possible Values: 1 0
Example: digestauth=1

Whether to enable Digest Authentication for accounts on the hosting plan.

  • 1 — Enable.
  • 0 — Disable.
featurelist
string
Default: "default"
Example: featurelist=feature_list

The hosting plan's feature list.

If you do not use this parameter, the function assigns the default feature list to the account.

frontpage
integer
Deprecated
Default: 0
Possible Values: 1 0
Example: frontpage=0

Whether Microsoft® FrontPage® Extensions are enabled for the account.

  • 1 — Enabled.
  • 0 — Disabled.

Note:

cPanel & WHM ignores all FrontPage settings and parameters.

hasshell
integer
Default: 0
Possible Values: 1 0
Example: hasshell=1

Whether the hosting plan allows shell access.

  • 1 — The hosting plan allows shell access.
  • 0 — The hosting plan does not allows shell access.
ip
string
Default: "n"
Possible Values: "y" "n"
Example: ip=n

Whether the account has a dedicated IP address.

  • y — The account possesses a dedicated IP address.
  • n — The account does not possess a dedicated IP address.
language
string <ISO-3166-1 (alpha-2)>
Example: language=en

The hosting plan's default locale, in its two-letter ISO-3166 code format.

This parameter defaults to the server's default locale.

integer or string
Default: "unlimited"
Example: MAX_DEFER_FAIL_PERCENTAGE=unlimited

The percentage of failed or deferred email messages that the hosting plan allows users to send per hour before outgoing mail is rate-limited.

  • 0 or unlimited — The hosting plan allows users ot send an unlimited number of failed or deferred messages.
integer or string
Default: "unlimited"
Example: MAX_EMAIL_PER_HOUR=unlimited

The maximum number of emails that the hosting plan allows users to send in one hour.

  • 0 or unlimited — The hosting plan allows users to send an unlimited number of emails.
integer or any or any or string
Default: 1024
Example: max_emailacct_quota=1024

The hosting plan's maximum email account quota size, in megabytes (MB).

  • 0, unlimited, or null — The hosting plan allows unlimited email account quota.

Note:

The 0, unlimited, and null values are only available to users that possess the corresponding unlimited ACL permission.

max_team_users
integer [ 0 .. 7 ]
Example: max_team_users=7

The hosting plan's maximum number of Team users.

integer or any or any or string
Default: 0
Example: maxaddon=unlimited

The hosting plan's maximum number of addon domains.

  • unlimited or null — The hosting plan allows unlimited addon domains.
integer or any or any or string
Default: "unlimited"
Example: maxftp=unlimited

The hosting plan's maximum number of FTP accounts.

  • unlimited, or null — The hosting plan allows unlimited FTP accounts.
integer or any or any or string
Default: "unlimited"
Example: maxlst=unlimited

The hosting plan's maximum number of mailing lists.

  • unlimited, or null — The hosting plan allows unlimited mailing lists.
integer or any or any or string
Default: 0
Example: maxpark=unlimited

The hosting plan's maximum number of parked domains (aliases).

  • unlimited or null — The hosting plan allows unlimited parked domains.
integer or any or any or string
Default: "unlimited"
Example: maxpop=unlimited

The hosting plan's maximum number of email accounts.

  • unlimited, or null — The hosting plan allows unlimited email accounts.
integer or any or any or string
Default: "unlimited"
Example: maxsql=unlimited

The hosting plan's maximum number of each available type of SQL database.

For example, if you set this value to 5 and the system administrator allows MySQL® and PostgreSQL® databases, users can create up to five MySQL databases and up to five PostgreSQL databases.

  • unlimited, or null — The hosting allows unlimited databases.
integer or any or any or string
Default: "unlimited"
Example: maxsub=unlimited

The hosting plan's maximum number of subdomains.

  • unlimited, or null — The hosting plan allows unlimited subdomains.
name
required
string
Example: name=package1

The new hosting plan's name.

Note:

  • You cannot use the name extensions for a hosting plan.
  • You cannot modify hosting plan names after creation. Do not include details that may change over time, such as price.
integer or any or any or string
Default: 10240
Example: quota=10240

The hosting plan's disk space quota, in megabytes (MB).

  • 0, unlimited, or null — The hosting plan allows unlimited disk space.

Note:

The 0, unlimited, and null values are only available to users that possess the corresponding unlimited ACL permission.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  addpkg \
  name='package1'

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": "package1"
    },
  • "metadata": {
    • "command": "addpkg",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update hosting plan

This function edits a hosting plan (package).

Note:

  • The Access Control List (ACL) restricts some of the function's parameters, which limit the features that WHM users can access.
  • This function applies any changes you make to all accounts that exist on the hosting plan.
  • This function cannot modify hosting plan names.
Authorizations:
BasicAuth
query Parameters
_PACKAGE_EXTENSIONS
string
Examples:
  • _PACKAGE_EXTENSIONS=extension1 extension2 extension3 - Add multiple package extensions.
  • _PACKAGE_EXTENSIONS=extension1 - Add a single package.

The hosting plan's package extensions.

If you do not provide a value, the hosting plan will not include package extensions.

Note:

  • We strongly recommend that you manage package extensions through WHM API 1's addpkgext and delpkgext functions.
  • You can include the extension's variables in your function call, in key=value format. Consult the extension's documentation for a list of possible variables.
  • Extension names and variables are case-sensitive.
  • Use space-delimited format to add multiple package extensions.
integer or any or string
Default: 1048576
Example: bwlimit=1048576

The hosting plan's maximum bandwidth use, in megabytes (MB).

  • 0, unlimited, or null — The hosting plan allows unlimited bandwidth.

Note:

The 0, unlimited, or null values are only available to users that possess the corresponding unlimited ACL permission.

cgi
integer
Default: 1
Possible Values: 1 0
Example: cgi=1

Whether CGI access is enabled for the hosting plan.

  • 1 — Enabled.
  • 0 — Disabled.

Note:

When a server profile disables the Web Server role, this parameter defaults to 0. On these servers, you cannot enable CGI access.

cpmod
string
Example: cpmod=jupiter

The hosting plan's cPanel theme.

This parameter defaults to the server's default cPanel theme.

digestauth
integer
Default: 0
Possible Values: 1 0
Example: digestauth=1

Whether to enable Digest Authentication for accounts on the hosting plan.

  • 1 — Enable.
  • 0 — Disable.
featurelist
string
Default: "default"
Example: featurelist=default

The hosting plan's feature list.

If you do not use this parameter, the function assigns the default feature list to the hosting plan's accounts.

frontpage
integer
Deprecated
Default: 0
Possible Values: 1 0
Example: frontpage=0

Whether Microsoft® FrontPage Extensions are enabled for the account.

Note:

cPanel & WHM ignores all FrontPage settings and parameters.

hasshell
integer
Default: 0
Possible Values: 1 0
Example: hasshell=1

Whether the hosting plan allows shell access.

  • 1 — The hosting plan allows shell access.
  • 0 — The hosting plan does not allow shell access.
ip
string
Default: "n"
Possible Values: "y" "n"
Example: ip=n

Whether the hosting plan uses a dedicated IP address.

  • y — The hosting plan uses a dedicated IP address.
  • n — The hosting plan does not use a dedicated IP address.
language
string <ISO-3166-1 (alpha-2)>
Example: language=en

The hosting plan's default locale.

This parameter defaults to the server's default locale.

integer or string
Default: "unlimited"
Example: max_defer_fail_percentage=unlimited

The percentage of failed or deferred email messages that an account on the hosting plan can send per hour before outgoing mail is rate-limited.

  • 0 or unlimited — The hosting plan allows unlimited email messages per hour.
integer or string
Default: "unlimited"
Example: max_email_per_hour=unlimited

The maximum number of emails that the hosting plan allows accounts to send in one hour.

  • 0 or unlimited — The hosting plan allows unlimited emails per hour.
integer or any or string
Default: 1024
Example: max_emailacct_quota=1024

The hosting plan's maximum email account quota size, in megabytes (MB).

  • 0, null, or unlimited` — The hosting plan allows unlimited quota.

Note:

  • This parameter does not affect any existing email accounts.
  • The unlimited value is only available to users that possess the corresponding unlimited ACL permission.
max_team_users
integer or null [ 0 .. 7 ]
Example: max_team_users=7

The hosting plan's maximum number of Team users.

integer or any or string
Default: 0
Example: maxaddon=unlimited

The hosting plan's maximum number of addon domains.

  • unlimited or null — The hosting plan allows unlimited addon domains.
integer or any or string
Default: "unlimited"
Example: maxftp=unlimited

The hosting plan's maximum number of FTP accounts.

  • unlimited, or null — The hosting plan allows unlimited databases.
integer or any or string
Default: "unlimited"
Example: maxlst=unlimited

The hosting plan's maximum number of mailing lists.

  • unlimited, or null — The hosting plan allows unlimited mailing lists.
integer or any or string
Default: 0
Example: maxpark=unlimited

The hosting plan's maximum number of parked domains (aliases).

  • unlimited or null — The hosting plan allows unlimited parked domains.
integer or any or string
Default: "unlimited"
Example: maxpop=unlimited

The hosting plan's maximum number of email accounts.

  • unlimited, or null — The hosting plan allows unlimited email accounts.
integer or any or string
Default: "unlimited"
Example: maxsql=unlimited

The hosting plan's maximum number of each available type of SQL database.

For example, if you set this value to 5 and the system administrator allows MySQL® and PostgreSQL® databases, users with this hosting plan can create up to five MySQL databases and up to five PostgreSQL databases.

  • unlimited, or null — The hosting plan allows unlimited databases.
integer or any or string
Default: "unlimited"
Example: maxsub=unlimited

The hosting plan's maximum number of subdomains.

  • unlimited, or null — The hosting plan allows unlimited subdomains.
name
required
string
Example: name=package1

The hosting plan's name. If the hosting plan does not exist, the system will create it.

integer or any or string
Default: 10240
Example: quota=10240

The hosting plan's disk space quota, in megabytes (MB).

  • 0, unlimited, or null — The hosting plan allows unlimited disk space quota.

Note:

The 0, unlimited, or null values are only available to users that possess the corresponding unlimited ACL permission.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  editpkg \
  name='package1'

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": "package1"
    },
  • "metadata": {
    • "command": "editpkg",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return hosting plan configuration

This function lists a hosting plan's (package's) settings.

Authorizations:
BasicAuth
query Parameters
pkg
required
string
Example: pkg=package1

The hosting plan's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  getpkginfo \
  pkg='package1'

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": {
      • "BWLIMIT": "unlimited",
      • "CGI": 1,
      • "CPMOD": "jupiter",
      • "DIGESTAUTH": "n",
      • "FEATURELIST": "myfeaturelist",
      • "FRONTPAGE": 0,
      • "HASSHELL": 1,
      • "IP": 1,
      • "LANG": "en",
      • "MAXADDON": 1,
      • "MAXFTP": 2,
      • "MAXLST": "unlimited",
      • "MAXPARK": 1,
      • "MAXPOP": 20,
      • "MAXSQL": 1,
      • "MAXSUB": 5,
      • "MAX_DEFER_FAIL_PERCENTAGE": 10,
      • "MAX_EMAILACCT_QUOTA": "unlimited",
      • "MAX_EMAIL_PER_HOUR": 100,
      • "MAX_TEAM_USERS": 7,
      • "QUOTA": 100,
      • "_PACKAGE_EXTENSIONS": ""
      }
    },
  • "metadata": {
    • "command": "getpkginfo",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's available hosting plans

This function lists the authenticated user's available hosting plans (packages).

Important:

This function only returns packages that the authenticated user can access and use during account creation.

Authorizations:
BasicAuth
query Parameters
want
string
Default: "all"
Possible Values: "all" "creatable" "editable" "viewable"
Example: want=all

The permissions of packages that you wish to list.

  • all — All packages on the system.
  • creatable — Packages that the authenticated user can use for accounts.
  • editable — Packages that the authenticated user can edit.
  • viewable — Packages that the authenticated user can view.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listpkgs

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": [
      • {
        • "BWLIMIT": "unlimited",
        • "CGI": "y",
        • "CPMOD": "jupiter",
        • "DIGESTAUTH": "n",
        • "FEATURELIST": "myfeaturelist",
        • "HASSHELL": "n",
        • "IP": "n",
        • "LANG": "en",
        • "MAXADDON": "unlimited",
        • "MAXFTP": "unlimited",
        • "MAXLST": "unlimited",
        • "MAXPARK": "unlimited",
        • "MAXPOP": "unlimited",
        • "MAXSQL": "unlimited",
        • "MAXSUB": "unlimited",
        • "MAX_DEFER_FAIL_PERCENTAGE": "unlimited",
        • "MAX_EMAILACCT_QUOTA": "unlimited",
        • "MAX_EMAIL_PER_HOUR": "unlimited",
        • "MAX_TEAM_USERS": 7,
        • "QUOTA": "unlimited",
        • "_PACKAGE_EXTENSIONS": "",
        • "name": "package1"
        }
      ]
    },
  • "metadata": {
    • "command": "listpkgs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return filtered hosting plans

This function matches the server's hosting plans (packages) against your criteria.

Note:

If you do not include any input parameters, the function lists all of the server's packages.

Authorizations:
BasicAuth
query Parameters
_PACKAGE_EXTENSIONS
string
Example: _PACKAGE_EXTENSIONS='ext1 ext2 ext3'

A space-separated list of one or more of the hosting plan's package extensions.

integer or string
Example: BWLIMIT=unlimited

The hosting plan's bandwidth limit.

  • unlimited — The hosting plan allows unlimited bandwidth.
CGI
integer
Possible Values: 1 0
Example: CGI=1

Whether CGI is enabled for the hosting plan.

  • 1 — Enabled.
  • 0 — Disabled.
CPMOD
string
Example: CPMOD=jupiter

The hosting plan's cPanel interface theme.

DIGESTAUTH
string
Possible Values: "y" "n"
Example: DIGESTAUTH=n

Whether the hosting plan enables Digest Authentication.

  • y — Enabled.
  • n — Disabled.
FEATURELIST
string
Example: FEATURELIST=myfeaturelist

The hosting plan's feature list.

HASSHELL
integer
Possible Values: 1 0
Example: HASSHELL=1

Whether shell access is enabled for the hosting plan.

  • 1 — Enabled
  • 0 — Disabled.
IP
string
Possible Values: "y" "n"
Example: IP=n

Whether the hosting plan grants accounts a dedicated IP address.

  • y — Dedicated IP address.
  • n — Shared IP address.
LANG
string <ISO-3166-1 (alpha-2)>
Example: LANG=en

The hosting plan's locale.

integer or string
Example: MAX_DEFER_FAIL_PERCENTAGE=unlimited

The percentage of failed or deferred email messages that the hosting plan can send per hour before the system rate-limits outgoing mail.

  • unlimited — The hosting plan allows unlimited email messages.
integer or string
Example: MAX_EMAIL_PER_HOUR=unlimited

The maximum number of emails that the hosting plan can send in one hour.

  • unlimited — The hosting plan allows unlimited emails per hour.
integer or string
Example: MAX_EMAILACCT_QUOTA=unlimited

The hosting plan's maximum email account quota size, in megabytes (MB).

  • unlimited — The hosting plan allows an unlimited email account quota size.
MAX_TEAM_USERS
integer or null [ 0 .. 7 ]
Example: MAX_TEAM_USERS=7

The hosting plan's maximum number of Team users.

integer or string
Example: MAXADDON=unlimited

The hosting plan's maximum number of addon domains.

  • unlimited — The hosting plan allows unlimited addon domains.
integer or string
Example: MAXFTP=2

The hosting plan's maximum number of FTP accounts.

  • unlimited — The hosting plan allows for unlimited FTP accounts.
integer or string
Example: MAXLST=unlimited

The hosting plan's maximum number of mailing lists.

  • unlimited — The hosting plan allows an unlimited number of mailing lists.
integer or string
Example: MAXPARK=unlimited

The hosting plan's maximum number of parked domains (aliases).

  • unlimited — The hosting plan allows unlimited parked domains.
integer or string
Example: MAXPOP=unlimited

The hosing plan's maximum number of email accounts.

  • unlimited — The hosting plan's can create unlimited email accounts.
integer or string
Example: MAXSQL=unlimited

The hosting plan's maximum number of SQL databases.

  • unlimited — The hosting plan allows unlimited SQL databases.
integer or string
Example: MAXSUB=unlimited

The hosting plan's maximum number of subdomains.

  • unlimited — The hosting plan allows unlimited subdomains.
integer or string
Example: QUOTA=unlimited

The hosting plan's disk space limit.

  • unlimited — The hosting plan has unlimited disk space.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  matchpkgs

Response samples

Content type
application/json
{
  • "data": {
    • "pkg": {
      • "BWLIMIT": "unlimited",
      • "CGI": 1,
      • "CPMOD": "jupiter",
      • "DIGESTAUTH": "y",
      • "FEATURELIST": "myfeaturelist",
      • "FRONTPAGE": 0,
      • "HASSHELL": "n",
      • "IP": "n",
      • "LANG": "en",
      • "MAXADDON": 1,
      • "MAXFTP": "unlimited",
      • "MAXLST": 5,
      • "MAXPARK": 1,
      • "MAXPOP": 20,
      • "MAXSQL": 1,
      • "MAXSUB": 5,
      • "MAX_DEFER_FAIL_PERCENTAGE": 10,
      • "MAX_EMAILACCT_QUOTA": "unlimited",
      • "MAX_EMAIL_PER_HOUR": 100,
      • "QUOTA": 100,
      • "_PACKAGE_EXTENSIONS": "ext1 ext2 ext3"
      }
    },
  • "metadata": {
    • "command": "matchpkgs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

InProductSurvey

In-product survey information.

Get in-product survey URL

This function returns whether to display the in-product survey banner and the survey link.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_in_product_survey_url

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "get_in_product_survey_url",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

API Authentication

Integrations / API Authentication

Return remote access file's hash Deprecated

This function retrieves a hash from a remote access file.

Warning:

We deprecated this function. We strongly suggest that you use the WHM API 1 api_token_list function.

Authorizations:
BasicAuth
query Parameters
generate
integer
Default: 0
Possible Values: 0 1
Example: generate=1

Whether to generate a new hash for the user, if one does not exist.

  • 1 — Generate a new hash.
  • 0 — Do not generate a new hash.
host
required
string
Example: host=hostname.example.com

The server's hostname.

password
required
string
Example: password=123456luggage

The user's password.

username
required
string
Example: username=user

The user's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_remote_access_hash \
  username='user' \
  password='123456luggage' \
  host='hostname.example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "accesshash": "6b355856c00606648b803a7d896186632472d584eaf0dad878b8885e1f64edad24b31ff79f2675303a598ac211ad5188c589fb60c5786a3e8d85c2029ca4ea76edb62becff7e3f7c5421f51bb4896737c22eda761e2a6fd96404bf513ee9051480ea86c800ab9b45f5255590836c7b769816a8f7f5def1e0c6cb19c212f01f56bb3392854ce51178a943eab6d1ce5d44857e980f70724f50964d2fbe01cb076a119dc5bf421051c2a0882550cdc69872832167c91e11bbe5c95d98474096ebe14b6ca9da2d73faecea5ec37f208912f5da578d5f8ab7c257584002e1808614f9859dceae564e8f30a9790c232d005ebd44f912e20b72e731fc600156e5b9f2902b0dd913010022e6b0deb6a2fb0d38ff3fd005c53f321ec812d3be10643dce81c46e1b9e2abe8814d46ba49b8a173b3e01ec677ea182cabb55db6d9eab2240755be1bbb1d7094a155fd262934ec099fdba3b10f409dced62d3d570ab6478a269a95da1314a45a5916da07312bf7e5a53d57b090e9c24932776f7ffdcf90ba2fa5cd935995795348b67311185f54da6b90da8771585e78c5f587e427bead9198faaa631b8216099c25373c8d4c26a011f295188963840777d09d95b6385df8337098b7e231534323457b9388fe9ea8046"
    },
  • "metadata": {
    • "command": "get_remote_access_hash",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create integration link group

This function creates a group to store integrations links in the cPanel interface.

Authorizations:
BasicAuth
query Parameters
group_id
required
string
Example: group_id=WHMCS

The group's ID within the system.

Warning:

If you create a link with a group_id value that already exists, the function replaces the existing group with the newly-created group.

label
required
string
Example: label=WHMCS+Control

The label for the group to display in the cPanel interface.

order
required
integer >= 1
Example: order=1

The order in which to display the group in the cPanel interface.

Note:

By default, the function will automatically create an item under the username menu in the interface header.

user
required
string <username>
Example: user=username

The cPanel account name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  create_integration_group \
  user='username' \
  group_id='WHMCS' \
  label='WHMCS+Control' \
  order='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "create_integration_group",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Return integration link groups

This function lists the groups of integration links in the cPanel interface.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=username

The cPanel account name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_integration_groups \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "links": [
      • {
        • "group": "Group3"
        }
      ]
    },
  • "metadata": {
    • "command": "list_integration_groups",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove integration link group

This removes a group of integration links from the cPanel interface.

Authorizations:
BasicAuth
query Parameters
group_id
required
string
Example: group_id=WHMCS

The group's ID.

user
required
string <username>
Example: user=username

The cPanel account name.

Responses

Response Schema: application/json
data
any
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_integration_group \
  user='username' \
  group_id='WHMCS'

Response samples

Content type
application/json
{
  • "data": null,
  • "metadata": {
    • "command": "remove_integration_group",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Scripts Hooks

Integrations / Scripts Hooks

Update script hook

This function edits a script hook.

Authorizations:
BasicAuth
query Parameters
check
string
Example: check=/scripts/postcourier-authlibup

The absolute file path to the script that runs after the hook script to check the results.

description
string
Example: description=TestHook

The hook script's description.

enabled
integer
Possible Values: 0 1
Example: enabled=1

Whether the hook script is enabled.

  • 1 — Enabled.
  • 0 — Disabled.
exectype
string
Possible Values: "script" "module"
Example: exectype=script

The type of function that the script hook launches.

  • script — Runs a script.
  • module — Calls a function in a module.
hook
string
Example: hook=/scripts/postcourier-authlibup

The hook script's absolute file path or its module::subroutine invocation.

id
required
string
Example: id=HzEpGvT6QGUYwxuX3hWB8AUq

The script hook's ID.

Note:

To retrieve a hook's ID, use the WHM API 1 list_hooks function.

notes
string
Example: notes=Note.

The script hook's notes.

rollback
string
Example: rollback=/scripts/postcourier-authlibup

The absolute file path to the script that rolls back the hook script.

stage
string
Possible Values: "pre" "post"
Example: stage=post

The condition when the hook script executes.

  • pre — The script runs before the function.
  • post — The script runs after the function.
weight
integer >= 1
Example: weight=100

The script hook's priority in the hook's stage, where a lower value runs before a higher value.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  edit_hook \
  id='HzEpGvT6QGUYwxuX3hWB8AUq'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "edit_hook",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete script hook

This function removes a script hook.

Authorizations:
BasicAuth
query Parameters
id
required
string
Example: id=HzEpGvT6QGUYwxuX3hWB8AUq

The script hook's ID.

Note:

To retrieve a hook's ID, use the WHM API 1 list_hooks function.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_hook \
  id='HzEpGvT6QGUYwxuX3hWB8AUq'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "delete_hook",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return script hooks list

This function lists the server's script hooks.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_hooks

Response samples

Content type
application/json
{
  • "data": {
    • "categories": [
      • {
        • "category": "RPM::Versions",
        • "events": [
          • {
            • "event": "MariaDB-server",
            • "stage_order": [
              • "pre",
              • "post"
              ],
            • "stages": [
              • {
                • "actions": [
                  • {
                    • "blocking": null,
                    • "category": null,
                    • "check": null,
                    • "description": null,
                    • "enabled": null,
                    • "escalateprivs": null,
                    • "event": null,
                    • "exectype": null,
                    • "hook": null,
                    • "id": null,
                    • "rollback": null,
                    • "stage": null,
                    • "weight": null
                    }
                  ],
                • "attributes": {
                  • "blocking": 0,
                  • "escalateprivs": 0
                  },
                • "description": "My hook script.",
                • "stage": "post"
                }
              ]
            }
          ]
        }
      ]
    },
  • "metadata": {
    • "command": "list_hooks",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update script hooks order

This function changes the order of script hooks.

Authorizations:
BasicAuth
query Parameters
ids
required
string
Example: ids=HzEpGvT6QGUYwxuX3hWB8AUq,UNs8a8IbbAVf5oi_hXbcEw5a

A comma-seprated list of script hook IDs, in order of priority.

Note:

To retrieve a hook's ID, use the WHM API 1 list_hooks function.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  reorder_hooks \
  ids='HzEpGvT6QGUYwxuX3hWB8AUq,UNs8a8IbbAVf5oi_hXbcEw5a'

Response samples

Content type
application/json
{
  • "data": {
    • "hook_order": [
      • {
        • "id": "HzEpGvT6QGUYwxuX3hWB8AUq",
        • "weight": 100
        },
      • {
        • "id": "UNs8a8IbbAVf5oi_hXbcEw5a",
        • "weight": 200
        }
      ]
    },
  • "metadata": {
    • "command": "reorder_hooks",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

IPv4 Address Settings

IP Address Management / IPv4 Address Settings

Add IP addresses

This function adds an IPv4 address or addresses to the server. When you add an IP address, the system attempts to add an alias of that IP address to the main network interface. This process rebuilds the IP address pool, which resides in the /etc/ipaddrpool file. The system stores IP addresses within the /etc/ips file. The ipaliases service activates those IP addresses when the server starts.

Authorizations:
BasicAuth
query Parameters
excludes
string
Examples:
  • excludes=excludes=192.0.20.0,192.0.20.1 - Multiple IP addresses.
  • excludes=192.0.20.0 - A single IP address.

An IPv4 address or comma-delimited list of IPv4 addresses to exclude.

Note:

If you do not specify a value, the function does not exclude any IPv4 addresses.

ips
required
string
Examples:
  • ips=192.168.0.0 - IPv4 address
  • ips=192.168.0.20/28 - IPv4 address range

The IPv4 address or address range in Class C CIDR format.

netmask
required
string <ipv4>
Example: netmask=255.255.255.0

The IPv4 address' netmask.

Note:

If the ips parameter is in Class C CIDR format, the range mask must be a value from 24 through 30.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  addips \
  ips='192.168.0.0' \
  netmask='255.255.255.0'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "addips",
    • "output": {
      • "messages": [
        • "eth0:cp1 is now up. 192.168.0.20/255.255.255.0 broadcast 192.168.0.255 has been added."
        ]
      },
    • "reason": "Success",
    • "result": 1,
    • "version": 1
    }
}

Remove IP address

This function removes an IP address from the server.

Authorizations:
BasicAuth
query Parameters
ethernetdev
string or null
Default: ""
Example: ethernetdev=eth0

The network alias to which the IPv4 address is bound.

ip
required
string <ipv4>
Example: ip=10.1.1.1

The IPv4 address.

skipifshutdown
integer
Default: 0
Possible Values: 0 1
Example: skipifshutdown=1

Whether to remove the IP address if the ethernet interface is down.

  • 1 — Do not remove the IP address.
  • 0 — Remove the IP address.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  delip \
  ip='10.1.1.1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "delip",
    • "reason": "eth0:cp2 is now down, 10.1.1.1 has been removed",
    • "result": 1,
    • "version": 1
    }
}

Return shared IP address

This function retrieves the IP address that an account shares with the accounts that it owns.

Authorizations:
BasicAuth
query Parameters
user
string <username>
Example: user=example

The WHM user's username.

Note:

This parameter defaults to the currently-authenticated user.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_shared_ip

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "192.168.0.1"
    },
  • "metadata": {
    • "command": "get_shared_ip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return server's IP addresses

This function lists a server's IP addresses.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listips

Response samples

Content type
application/json
{
  • "data": {
    • "ip": [
      • {
        • "active": 1,
        • "dedicated": 0,
        • "if": "eth0",
        • "ip": "192.168.0.20",
        • "mainaddr": 0,
        • "netmask": "255.255.0.0",
        • "network": "192.168.0.0",
        • "public_ip": "10.1.32.177",
        • "removable": 0,
        • "used": 1
        }
      ]
    },
  • "metadata": {
    • "command": "listips",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update domain or cPanel account IP address

This function changes a site's or account's IP address.

Authorizations:
BasicAuth
query Parameters
domain
string <domain>
Example: domain=example.com

The domain's name.

Note:

You must use either the user parameter or domain parameter.

ip
required
string <ipv4>
Example: ip=192.168.4.10

The site's or user's IPv4 address.

user
string <username>
Example: user=username

The user's username.

Note:

You must use either the user parameter or domain parameter.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setsiteip \
  ip='192.168.4.10'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setsiteip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

IPv6 Address Settings

IP Address Management / IPv6 Address Settings

Remove IPv6 address range from account

This function removes the IPv6 address from an account.

Notes:

  • When you disable IPv6 on an account, the system unbinds that IPv6 address from your server and the account loses the address. If you enable IPv6 on that account again, the system assigns it a different IPv6 address.
  • For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=user1,user2,user3

A comma delimited list of account names.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_disable_account \
  user='user1,user2,user3'

Response samples

Content type
application/json
{
  • "data": {
    • "fail_cnt": 0,
    • "failures": [
      • {
        • "name": "user1",
        • "reason": "The “user1” account does not exist."
        }
      ]
    },
  • "metadata": {
    • "command": "ipv6_disable_account",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add IPv6 address range to accounts

This function assigns an IPv6 address to one or more accounts.

Note:

You must perform at least one of the following actions before you call this function:

  • Use WHM's IPv6 Ranges interface (WHM >> Home >> IP Functions >> IPv6 Ranges) or WHM API 1's ipv6_range_add function to add one or more IPv6 address ranges for use as dedicated IPv6 addresses.
  • Use WHM's Basic WebHost Manager Setup interface (WHM >> Home >> Server Configuration >> Basic WebHost Manager Setup) or modify the /etc/wwwacct.conf file to add a shared IPv6 address to the server.
  • For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
range
required
string
Example: range=Hosting_IPv6_Block

The IPv6 address range's name.

Note:

The range name SHARED will assign the server's shared IPv6 address to the account(s).

user
required
string <username>
Example: user=user1,user2,user3

A comma-delimited list of account names.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_enable_account \
  user='user1,user2,user3' \
  range='Hosting_IPv6_Block'

Response samples

Content type
application/json
{
  • "data": {
    • "fail_cnt": 2,
    • "failures": {
      • "brain": "The “brain” account does not exist.",
      • "pinky": "The “pinky” account does not exist."
      },
    • "ipv6": {
      • "chewie": "2001:0db8:1a34:56cf:0000:0000:0000:0000",
      • "cptest": "2001:0db8:1a34:56cf:0000:0000:0000:0001",
      • "domain1": "2001:0db8:1a34:56cf:0000:0000:0000:0002"
      }
    },
  • "metadata": {
    • "command": "ipv6_enable_account",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add IPv6 address range

This function adds a range of IPv6 addresses to the server.

Notes:

  • This function cannot modify the server's shared IPv6 address. To update that address, modify the /etc/wwwacct.conf file, or use WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup).
  • For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
enabled
integer
Default: 1
Possible Values: 0 1
Example: enabled=1

Whether the IPv6 address range is available.

Note

  • 1 - Available.
  • 0 - Reserved.
name
required
string
Example: name=ExampleRange

The IPv6 address range's name.

Note:

You cannot use SHARED as a range's name. It is reserved for the server's shared IPv6 address.

note
string or null
Default: null
Example: note=Initial IPv6 address pool

A note for the IPv6 address range.

range
required
string
Example: range=2001:db8:66ac:cafe::/64

The IPv6 address range and network portion in CIDR format.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_range_add \
  range='2001:db8:66ac:cafe::/64' \
  name='ExampleRange'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "ipv6_range_add",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available IPv6 address ranges

This function lists available IPv6 address ranges.

Note:

For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_range_list

Response samples

Content type
application/json
{
  • "data": {
    • "range": [
      • {
        • "CIDR": "2001:db8:100:6::/64",
        • "enabled": 1,
        • "first": "2001:db8:0100:0006:0000:0000:0000:0000",
        • "last": "2001:db8:0100:0006:ffff:ffff:ffff:ffff",
        • "mostrecent": "2001:db8:0100:0006:0000:0000:0002:00ce",
        • "name": "test_range",
        • "note": "This is used for development.",
        • "owner": "root",
        • "range_users": [
          • "user1"
          ],
        • "reclaimed": [
          • "2001:db8:0100:0006:0000:0000:0000:0002"
          ]
        }
      ]
    },
  • "metadata": {
    • "command": "ipv6_range_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update IPv6 address range name or note

This function changes an IPv6 address range's name and/or note.

Notes:

  • This function cannot modify the server's shared IPv6 address. To update that address, modify the /etc/wwwacct.conf file, or use WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup).
  • For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=ExampleRange

The IPv6 address range's current name.

Note:

You cannot edit the range named SHARED.

new_name
string
Default: null
Example: new_name=AnotherRange

The IPv6 address range's new name.

Note:

  • If not supplied the range keeps its old name.
  • You cannot change range name to SHARED.
note
string
Default: null
Example: note=This is an update to the note.

The IPv6 address range's new note.

Note:

If you don't specify this parameter, the function will not change the range's note.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_range_edit \
  name='ExampleRange'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "ipv6_range_edit",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove IPv6 address range

This function removes an IPv6 address range from the server.

Note:

  • This function cannot modify the server's shared IPv6 address. To update that address, modify the /etc/wwwacct.conf file, or use WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup).
  • For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=Range1

The IPv6 address range's name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_range_remove \
  name='Range1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "ipv6_range_remove",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return IPv6 address usage

This function retrieves usage information for IPv6 addresses in an IPv6 range.

Note:

For all of cPanel & WHM's features to function properly on IPv6, the cpsrvd daemon must listen on IPv6 addresses. To enable this functionality, select On for the Listen on IPv6 Addresses setting in the System section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=TestRange

The IPv6 address range's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ipv6_range_usage \
  name='TestRange'

Response samples

Content type
application/json
{
  • "data": {
    • "usage": {
      • "forbidden": 65536,
      • "free": 1000000,
      • "used": 20
      }
    },
  • "metadata": {
    • "command": "ipv6_range_usage",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return server's IPv6 addresses

This function lists the IPv6 addresses bound to a server’s network interfaces.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listipv6s

Response samples

Content type
application/json
{
  • "data": {
    • "ip": [
      • {
        • "ip": "2001:0db8:0:0:1:0:0:1"
        }
      ]
    },
  • "metadata": {
    • "command": "listipv6s",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Network Address Translation

IP Address Management / Network Address Translation

Return public IP address of private IP address

This function returns the public IP address for a specified public or private IP address. You can use this function to determine the system's main public IP address, especially for systems that use a 1:1 NAT configuration.

  • cPanel & WHM uses the main public IP address to perform many different functions. For example, the system uses this IP address to verify the server's license status with WebPros International, LLC.
  • System administrators can configure the main public IP address in WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup).
Authorizations:
BasicAuth
query Parameters
ip
required
string <ipv4>
Example: ip=192.0.2.0

A valid public or private IP address to query.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_public_ip \
  ip='192.0.2.0'

Response samples

Content type
application/json
{
  • "data": {
    • "public_ip": "192.0.2.0"
    },
  • "metadata": {
    • "command": "get_public_ip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate public IP address for NAT

This function validates a public IP address on a NAT-configured server.

Authorizations:
BasicAuth
query Parameters
ip
required
string <ipv4>
Example: ip=192.168.4.10

The local IPv4 address.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  nat_checkip \
  ip='192.168.4.10'

Response samples

Content type
application/json
{
  • "data": {
    • "checked_ip": "192.168.4.10"
    },
  • "metadata": {
    • "command": "nat_checkip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Register NAT IP address to public IP address

This function pairs a local IP address with a public IP address on NAT-configured servers.

Authorizations:
BasicAuth
query Parameters
local_ip
required
string <ipv4>
Example: local_ip=192.168.4.10

The local IPv4 address.

public_ip
required
string <ipv4>
Example: public_ip=10.5.3.33

The public IPv4 address.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  nat_set_public_ip \
  local_ip='192.168.4.10' \
  public_ip='10.5.3.33'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "nat_set_public_ip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Management

Login Security (cPHulk) / Management

Remove all login security records

This function removes the login history entries from the cPHulk database.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  flush_cphulk_login_history

Response samples

Content type
application/json
{
  • "data": {
    • "records_removed": 10
    },
  • "metadata": {
    • "command": "flush_cphulk_login_history",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove login security IP address block

This function removes specific login history entries from the cPHulk database. Use this function to unblock one or more IP addresses.

Authorizations:
BasicAuth
query Parameters
required
Array of strings or strings
Examples:
  • ip=192.168.0.1&ip=192.168.0.2&ip=192.168.0.3 - Multiple IPv4 addresses.
  • ip=2001:db8::1&ip=2002:db8::1&ip=2003:db8::1 - Multiple IPv6 addresses.
  • ip=192.168.0.1 - A single IPv4 address.
  • ip=2001:db8::1 - Single IPv6 Address

The record's IP address.

Note:

To unblock multiple IP addresses, increment the parameter name (for example, to unblock three IP addresses, use the ip-1, ip-2, and ip-3 parameters).

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  flush_cphulk_login_history_for_ips \
  ip='192.168.0.1'

Response samples

Content type
application/json
{
  • "data": {
    • "iptable_bans_removed": 1,
    • "records_removed": 1
    },
  • "metadata": {
    • "command": "flush_cphulk_login_history_for_ips",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security list records

This function displays a cPHulk list's records.

Authorizations:
BasicAuth
query Parameters
list_name
required
string
Possible Values: "black" "white"
Example: list_name=white

The cPHulk list's name.

  • black
  • white
skip_enabled_check
integer
Default: 0
Possible Values: 0 1
Example: skip_enabled_check=1

Whether to skip checking if cPHulk runs on the server.

Note:

If cPHulk is disabled, the function returns the following message: cPHulk is disabled on the server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  read_cphulk_records \
  list_name='white'

Response samples

Content type
application/json
{
  • "data": {
    • "ips_in_list": {
      • "10.1.4.44": "A helpful comment about the IP address.",
      • "DEED::1": "A helpful comment about the IP address."
      },
    • "list_name": "white",
    • "requester_ip": "10.1.4.228",
    • "requester_ip_is_whitelisted": 1,
    • "restart_ssh": 1,
    • "warning_ip": "The IP address is not on the white list.",
    • "warning_ssh": "The system disabled the UseDNS setting for sshd in order to add IP addresses to the whitelist. You must restart sshd to implement the change."
    },
  • "metadata": {
    • "command": "read_cphulk_records",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add login security record to list

This function adds a new record or records to cPHulk's whitelist or blacklist.

Authorizations:
BasicAuth
query Parameters
comment
string <= 255
Example: comment=George Wendt flying through the air.

A comment to include.

required
Array of strings or strings or strings or strings or strings or strings (ip-address)
Examples:
  • ip=192.168.0.1&ip=192.168.0.2&ip=192.168.0.3 - Add multiple IP addresses.
  • ip=192.168.0.1 - Add a single IP address.

The record's IP address, if there is only one IP address to add.

Note:

To add multiple IP addresses, increment the parameter name. For example, ip-1, ip-2, and ip-3.

list_name
required
string
Possible Values: "black" "white"
Example: list_name=white

The cPHulk list's name.

  • black - Add a new record or records to the blacklist.
  • white - Add a new record or records to the whitelist.
skip_enabled_check
integer
Default: 0
Possible Values: 0 1
Example: skip_enabled_check=1

Whether to skip checking if cPHulk runs on the server.

  • 1 - Do not check if cPHulk is running.
  • 0 - Check if cPHulk is running.

Note:

If cPHulk is disabled and you check its status, the function returns the following message: cPHulk is disabled on the server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_cphulk_record \
  list_name='white' \
  ip='192.168.0.1'

Response samples

Content type
application/json
{
  • "data": {
    • "comment": "George Wendt flying through the air.",
    • "ip_blocks_removed": 1,
    • "ips_added": [
      • "192.168.0.1"
      ],
    • "ips_failed": {
      • "192.168.0.1": "Invalid IP address or range: \"192.68.0.1\""
      },
    • "iptable_bans_removed": 0,
    • "list_name": "white",
    • "requester_ip": "10.1.4.228",
    • "requester_ip_is_whitelisted": 0
    },
  • "metadata": {
    • "command": "create_cphulk_record",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security status

This function returns the status of the cPHulk service.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cphulk_status

Response samples

Content type
application/json
{
  • "data": {
    • "is_enabled": 1,
    • "service": "cPHulk"
    },
  • "metadata": {
    • "command": "cphulk_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove login security record from list

This function deletes a record or records from cPHulk's whitelist or blacklist.

Authorizations:
BasicAuth
query Parameters
required
Array of strings or strings or strings or strings or strings or strings (ip-address)
Examples:
  • ip=192.168.0.1&ip=192.168.0.2&ip=2001:db8::1&ip=2002:db8::1 - Multiple IP addresses.
  • ip=192.168.0.1 - Single IP address.

The record's IP address.

Note:

To delete multiple IP addresses, increment the parameter name. For example, ip-1, ip-2, ip-3.

list_name
required
string
Possible Values: "white" "black"
Example: list_name=white

The cPHulk list's name.

  • white
  • black
skip_enabled_check
integer
Default: 0
Possible Values: 0 1
Example: skip_enabled_check=1

Whether to skip checking if cPHulk runs on the server.

  • 1 - Don’t check cPHulk’s status.
  • 0 - Check cPHulk’s status.

Note:

If cPHulk is disabled and you check its status, the function returns the following message: cPHulk is disabled on the server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_cphulk_record \
  list_name='white' \
  ip='192.168.0.1'

Response samples

Content type
application/json
{
  • "data": {
    • "ips_failed": {
      • "192.168.0.1": "This is why, alpha.",
      • "192.168.9.1": "This is why, beta."
      },
    • "ips_removed": [
      • "192.168.0.1"
      ],
    • "list_name": "white",
    • "requester_ip": "192.168.0.1",
    • "requester_ip_is_whitelisted": 1
    },
  • "metadata": {
    • "command": "delete_cphulk_record",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add login security record to list with comment

This function adds one or more records to cPHulk's whitelist or blacklist. The function includes the option to add unique comments for each IP address that you add.

Authorizations:
BasicAuth
Request Body schema: application/json
api.version
required
integer
Value: 1

The WHM API version number.

list_name
required
string
Possible Values: "black" "white"

The cPHulk list's name.

  • black - Add a new record or records to the blacklist.
  • white - Add a new record or records to the whitelist.
required
Array of objects

The list of records to add to the whitelist or blacklist.

skip_enabled_check
integer
Default: 0
Possible Values: 0 1

Whether to skip checking if cPHulk runs on the server.

  • 1 - Do not check if cPHulk is running.
  • 0 - Check if cPHulk is running.

Note:

If cPHulk is disabled and you check its status, the function returns the following message: cPHulk is disabled on the server.

Responses

Response Schema: application/json
object
object

Request samples

Content type
application/json
{
  • "api.version": 1,
  • "list_name": "white",
  • "records": [
    • {
      • "comment": "Automated update tools.",
      • "ip": "192.168.0.1"
      },
    • {
      • "comment": "System administrators and support systems.",
      • "ip": "192.168.1.0/30"
      },
    • {
      • "comment": "Owner of example.com.",
      • "ip": "122.1.56.7-122.1.56.8"
      },
    • {
      • "comment": "Special access group 1",
      • "ip": "2001:db9::"
      },
    • {
      • "comment": "Special access group 1",
      • "ip": "2001:db9::1-2001:db9::5"
      },
    • {
      • "comment": "Special access group 2",
      • "ip": "2001:db8::/32"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "comment": "George Wendt flying through the air.",
    • "ip_blocks_removed": 1,
    • "ips_added": [
      • "192.168.0.1",
      • "192.168.1.0-192.168.1.3",
      • "122.1.56.7-122.1.56.8"
      ],
    • "ips_failed": {
      • "192.168.0.1": "Invalid IP address or range: \"192.68.0.1\""
      },
    • "iptable_bans_removed": 0,
    • "list_name": "white",
    • "original_ips_added": [
      • "192.168.0.1",
      • "192.168.1.0/30",
      • "122.1.56.7-122.1.56.8"
      ],
    • "requester_ip": "10.1.4.228",
    • "requester_ip_is_whitelisted": 0
    },
  • "metadata": {
    • "command": "batch_create_cphulk_records",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Reporting

Login Security (cPHulk) / Reporting

Return login security country codes

This function lists the country codes available for whitelist and blacklist functions.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_countries_with_known_ip_ranges

Response samples

Content type
application/json
{
  • "data": {
    • "countries": [
      • {
        • "code": "US",
        • "name": "United States"
        }
      ]
    },
  • "metadata": {
    • "command": "get_countries_with_known_ip_ranges",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security brute force attacks

This function lists brute force attack entries from the cPHulk database.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_cphulk_brutes

Response samples

Content type
application/json
{
  • "data": {
    • "brutes": [
      • {
        • "exptime": "2014-12-07T00:00:00.000Z",
        • "ip": "192.168.0.1",
        • "logintime": "2014-11-20T00:00:00.000Z",
        • "notes": "this was a triumph",
        • "timeleft": 14
        }
      ]
    },
  • "metadata": {
    • "command": "get_cphulk_brutes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security excessive brute force attacks

This function retrieves excessive brute force attack entries from the cPHulk database.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_cphulk_excessive_brutes

Response samples

Content type
application/json
{
  • "data": {
    • "excessive_brutes": [
      • {
        • "exptime": "2014-12-07T00:00:00.000Z",
        • "ip": "192.168.0.1",
        • "logintime": "2014-11-20T00:00:00.000Z",
        • "notes": "this was a triumph",
        • "timeleft": 14
        }
      ]
    },
  • "metadata": {
    • "command": "get_cphulk_excessive_brutes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security brute force attacks by user

This function lists brute force attack entries from the cPHulk database, ordered by user accounts.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_cphulk_user_brutes

Response samples

Content type
application/json
{
  • "data": {
    • "user_brutes": [
      • {
        • "authservice": "dovecot",
        • "exptime": "2014-12-07T00:00:00.000Z",
        • "ip": "192.168.0.1",
        • "logintime": "2014-11-20T00:00:00.000Z",
        • "service": "ftp",
        • "timeleft": 14,
        • "user": "example"
        }
      ]
    },
  • "metadata": {
    • "command": "get_cphulk_user_brutes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security failed logins

This function lists failed login attempt entries from the cPHulk database.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_cphulk_failed_logins

Response samples

Content type
application/json
{
  • "data": {
    • "failed_logins": [
      • {
        • "authservice": "dovecot",
        • "exptime": "2014-12-07T00:00:00.000Z",
        • "ip": "192.168.0.1",
        • "logintime": "2014-11-20T00:00:00.000Z",
        • "service": "ftp",
        • "timeleft": 14,
        • "user": "example"
        }
      ]
    },
  • "metadata": {
    • "command": "get_cphulk_failed_logins",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Settings

Login Security (cPHulk) / Settings

Disable login security

This function disables the cPHulk service.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_cphulk

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "disable_cphulk",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable login security

This function enables the cPHulk service.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_cphulk

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "enable_cphulk",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return login security configuration settings

This function returns cPHulk's current settings.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  load_cphulk_config

Response samples

Content type
application/json
{
  • "data": {
    • "cphulk_config": {
      • "block_brute_force_with_firewall": 1,
      • "block_excessive_brute_force_with_firewall": 1,
      • "brute_force_period_mins": 5,
      • "brute_force_period_sec": 360,
      • "can_temp_ban_firewall": 1,
      • "command_to_run_on_brute_force": "echo \"BRUTE\"",
      • "command_to_run_on_excessive_brute_force": "echo \"TOO MUCH BRUTE\"",
      • "ip_based_protection": 1,
      • "ip_brute_force_period_mins": 15,
      • "ip_brute_force_period_sec": 300,
      • "is_enabled": 1,
      • "lookback_period_min": 360,
      • "lookback_time": 21600,
      • "mark_as_brute": 30,
      • "max_failures": 30,
      • "max_failures_byip": 5,
      • "notify_on_brute": 1,
      • "notify_on_root_login": 1,
      • "notify_on_root_login_for_known_netblock": 1,
      • "username_based_protection": 1,
      • "username_based_protection_for_root": 1,
      • "username_based_protection_local_origin": 1
      }
    },
  • "metadata": {
    • "command": "load_cphulk_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Save login security configuration settings

This function modifies cPHulk's configuration settings.

Authorizations:
BasicAuth
query Parameters
block_brute_force_with_firewall
integer
Default: 0
Possible Values: 0 1
Example: block_brute_force_with_firewall=0

Whether to use the server firewall to block brute force attacks.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
block_excessive_brute_force_with_firewall
integer
Default: 0
Possible Values: 0 1
Example: block_excessive_brute_force_with_firewall=0

Whether to use the server firewall to block excessive brute force attacks.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
brute_force_period_mins
integer >= 1
Default: 5
Example: brute_force_period_mins=5

The number of minutes over which cPHulk measures all login attempts to a specific user's account.

command_to_run_on_brute_force
string
Default: ""
Example: command_to_run_on_brute_force=

The command to run when an IP address triggers brute force protection.

Note:

For a list of commands, read the Command variables section of our cPHulk Brute Force Protection documentation.

command_to_run_on_excessive_brute_force
string
Default: ""
Example: command_to_run_on_excessive_brute_force=

The command to run when the system blocks an IP address for a one day period.

Note:

For a list of commands, read the Command variables section of our cPHulk Brute Force Protection documentation.

ip_based_protection
integer
Default: 1
Possible Values: 0 1
Example: ip_based_protection=1

Whether to enable IP address-based protection on all requests.

  • 1 — Enable IP-based protection.
  • 0 — Disable IP-based protection.

Note:

If you set this parameter to 0, you cannot use the following parameters:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_brute_force_period_mins
ip_brute_force_period_mins
integer >= 1
Default: 15
Example: ip_brute_force_period_mins=15

The number of minutes in which cPHulk measures an attacker's login attempts.

lookback_period_min
integer >= 0
Default: 360
Example: lookback_period_min=360

The number of minutes over which cPHulk counts failed logins against a user.

mark_as_brute
integer >= 0
Default: 30
Example: mark_as_brute=30

The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.

max_failures
integer >= 0
Default: 30
Example: max_failures=30

The maximum number of failures that cPHulk allows per account within the defined time range.

max_failures_byip
integer >= 0
Default: 5
Example: max_failures_byip=5

The maximum number of failures from a specific IP address before cPHulk locks out that address.

notify_on_brute
integer
Default: 0
Possible Values: 0 1
Example: notify_on_brute=0

Whether cPHulk will send a notification when it detects a brute force attack.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
notify_on_root_login
integer
Default: 0
Possible Values: 0 1
Example: notify_on_root_login=0

Whether cPHulk will send a notification when the root user successfully logs in from an IP address that is not on the whitelist.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
notify_on_root_login_for_known_netblock
integer
Default: 0
Possible Values: 0 1
Example: notify_on_root_login_for_known_netblock=0

Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
skip_enabled_check
integer
Default: 0
Possible Values: 0 1
Example: skip_enabled_check=0

Whether to skip checking if cPHulk runs on the server.

  • 1 — Don't check cPHulk's status.
  • 0 — Check cPHulk's status.

Note:

If cPHulk is disabled, the function returns the following message: cPHulk is disabled on the server.

username_based_protection
integer
Default: 0
Possible Values: 0 1
Example: username_based_protection=0

Whether to enable username-based protection on all requests.

  • 1 — Enable.
  • 0 — Disable.
username_based_protection_for_root
integer
Default: 0
Possible Values: 0 1
Example: username_based_protection_for_root=0

Whether to allow username-based protection to lock out the root user.

  • 1 — Allow.
  • 0 — Do not allow.
username_based_protection_local_origin
integer
Default: 1
Possible Values: 0 1
Example: username_based_protection_local_origin=1

Whether to enable username-based protection only on requests that originate from a local IP address.

  • 1 — Enable.
  • 0 — Disable.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  save_cphulk_config

Response samples

Content type
application/json
{
  • "data": {
    • "cphulk_config": {
      • "block_brute_force_with_firewall": 0,
      • "block_excessive_brute_force_with_firewall": 0,
      • "brute_force_period_mins": 5,
      • "brute_force_period_sec": 300,
      • "can_temp_ban_firewall": 1,
      • "command_to_run_on_brute_force": "",
      • "command_to_run_on_excessive_brute_force": "",
      • "ip_based_protection": 1,
      • "ip_brute_force_period_mins": 15,
      • "ip_brute_force_period_sec": 900,
      • "is_enabled": 1,
      • "lookback_period_min": 360,
      • "lookback_time": 21600,
      • "mark_as_brute": 30,
      • "max_failures": 30,
      • "max_failures_byip": 5,
      • "notify_on_brute": 0,
      • "notify_on_root_login": 0,
      • "notify_on_root_login_for_known_netblock": 0,
      • "username_based_protection": 0,
      • "username_based_protection_for_root": 0,
      • "username_based_protection_local_origin": 1
      },
    • "restart_ssh": 1,
    • "warning": null
    },
  • "metadata": {
    • "command": "save_cphulk_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update login security configuration settings

This function modifies a single cPHulk configuration settings as specified.

Authorizations:
BasicAuth
query Parameters
key
required
string
Possible Values: "block_brute_force_with_firewall" "block_excessive_brute_force_with_firewall" "brute_force_period_mins" "brute_force_period_sec" "command_to_run_on_brute_force" "command_to_run_on_excessive_brute_force" "country_blacklist" "country_whitelist" "ip_based_protection" "ip_brute_force_period_mins" "ip_brute_force_period_sec" "is_enabled" "lookback_period_min" "lookback_time" "mark_as_brute" "max_failures" "max_failures_byip" "notify_on_brute" "notify_on_root_login" "notify_on_root_login_for_known_netblock" "username_based_protection" "username_based_protection_for_root" "username_based_protection_local_origin"
Example: key=is_enabled

The configuration key for the setting to set/modify.

It should be one of the following:

  • block_brute_force_with_firewall - Whether to use cPanel & WHM's firewall to block brute force attacks.
  • block_excessive_brute_force_with_firewall - Whether to use cPanel & WHM's firewall to block excessive brute force attacks.
  • brute_force_period_mins - The number of minutes over which cPHulk measures all login attempts to a specific user's account.
  • brute_force_period_sec - The number of seconds over which cPHulk measures all login attempts to a specific user's account.
  • command_to_run_on_brute_force - The command to run when an IP address triggers brute force protection.
  • command_to_run_on_excessive_brute_force - The command to run when the system blocks an IP address blocked for a one day period.
  • country_blacklist - The countries to blacklist.
  • country_whitelist - The countries to whitelist.
  • ip_based_protection - Whether to enable IP address-based protection on all requests.
  • ip_brute_force_period_mins - The number of minutes in which cPHulk measures an attacker's login attempts.
  • ip_brute_force_period_sec - The number of seconds in which cPHulk measures an attacker's login attempts.
  • is_enabled - Whether to enable the cPHulk service.
  • lookback_period_min - The number of minutes over which cPHulk counts failed logins against a user.
  • lookback_time - The number of seconds over which cPHulk counts failed logins against a user.
  • mark_as_brute - The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.
  • max_failures - The maximum number of failures that cPHulk allows per account within the defined time range.
  • max_failures_byip - The maximum number of failures from a specific IP address before cPHulk locks out that address.
  • notify_on_brute - Whether cPHulk will send a notification when it detects a brute force attack.
  • notify_on_root_login - Whether cPHulk will send a notification when the root user successfully logs in from an IP address that is not on the whitelist.
  • notify_on_root_login_for_known_netblock - Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock.
  • username_based_protection - Whether to enable username-based protection on all requests.
  • username_based_protection_for_root - Whether to allow username-based protection to lock out the root user.
  • username_based_protection_local_origin - Whether to enable username-based protection only on requests that originate from a local IP address.
required
string or integer
Example: value=1

The new value for the specified key. The allowable value depends on which key is being set.

For the following keys, the value must be 0 or 1:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_based_protection
  • is_enabled
  • notify_on_brute
  • notify_on_root_login
  • notify_on_root_login_for_known_netblock
  • username_based_protection
  • username_based_protection_for_root
  • username_based_protection_local_origin

For the following keys, the value must be an integer which specifies a number of minutes or seconds:

  • brute_force_period_mins
  • brute_force_period_sec
  • ip_brute_force_period_mins
  • ip_brute_force_period_sec
  • lookback_period_min
  • lookback_time - This one is in seconds despite not having sec in the name

These keys require the value to be a string containing a command to be run: (For a list of commands, read the Command Variables section of our cPHulk Brute Force Protection documentation.)

  • command_to_run_on_brute_force
  • command_to_run_on_excessive_brute_force

These keys require the value to be a string containing a comma-separated list of country codes: (For a list of countries, run the WHM API 1 get_countries_with_known_ip_ranges function.)

  • country_blacklist
  • country_whitelist

The following keys require an integer representing a maximum number of failures

  • mark_as_brute
  • max_failures
  • max_failures_byip

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_cphulk_config_key key=is_enabled value=1

Response samples

Content type
application/json
{
  • "data": {
    • "cphulk_config": {
      • "block_brute_force_with_firewall": 0,
      • "block_excessive_brute_force_with_firewall": 0,
      • "brute_force_period_mins": 5,
      • "brute_force_period_sec": 300,
      • "can_temp_ban_firewall": 1,
      • "command_to_run_on_brute_force": "",
      • "command_to_run_on_excessive_brute_force": "",
      • "country_blacklist": "PK,BR",
      • "country_whitelist": "US,AU",
      • "ip_based_protection": 1,
      • "ip_brute_force_period_mins": 15,
      • "ip_brute_force_period_sec": 900,
      • "is_enabled": 1,
      • "lookback_period_min": 360,
      • "lookback_time": 21600,
      • "mark_as_brute": 30,
      • "max_failures": 30,
      • "max_failures_byip": 5,
      • "notify_on_brute": 0,
      • "notify_on_root_login": 0,
      • "notify_on_root_login_for_known_netblock": 0,
      • "username_based_protection": 0,
      • "username_based_protection_for_root": 0,
      • "username_based_protection_local_origin": 1
      }
    },
  • "metadata": {
    • "command": "set_cphulk_config_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

cPanel Account Mail Management

Mail / cPanel Account Mail Management

Unsuspend account outgoing email

This function unsuspends outgoing email for a cPanel account's users.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=example

The cPanel account.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  unsuspend_outgoing_email \
  user='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "unsuspend_outgoing_email",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account forward destination

This function retrieves the destination to which the system forwards a system account's email.

Note:

  • Usually, the system sends notices about the server's problems and activity to the root account.
  • If you do not use the suexec module, the nobody user receives bounce messages from email that CGI scripts send.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=root

The system account name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_user_email_forward_destination \
  user='root'

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "get_user_email_forward_destination",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account's email accounts

This function lists a cPanel account’s email accounts. To prevent falsified data or symlink exploitation, the function uses the specified cPanel account user, rather than root user, to read data from the user’s home directory. The system compares the collected data from the user’s home directory to a server-wide domains list. The comparison of the data validates whether you can trust the data.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=example

The cPanel account user for which to list all owned email accounts.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_pops_for \
  user='example'

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "list_pops_for",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel account email forward destination

This function sets the destination to which the system forwards a system account's email.

Notes:

  • Usually, the system sends notices about the server's problems and activity to the root account.
  • If you do not use the suexec module, the nobody user receives bounce messages from email that CGI scripts send.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
forward_to
required
string
Example: forward_to=user

The system account name or email address to which you wish to forward email.

Note:

To forward messages to multiple accounts or email addresses, use a comma-separated list.

user
required
string
Example: user=root

The system account name to forward.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_user_email_forward_destination \
  user='root' \
  forward_to='user'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_user_email_forward_destination",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account unique email recipients

This function gets the number of unique recipients that a system user sent mail to within a period of time. It groups this data by each of the user's email accounts.

Authorizations:
BasicAuth
query Parameters
end_time
required
integer <unix_timestamp>
Example: end_time=1550923200

An end time to query.

start_time
required
integer <unix_timestamp>
Example: start_time=1550872800

A start time to query.

user
required
string
Example: user=username

The system user's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_unique_recipient_count_per_sender_for_user \
  user='username' \
  start_time='1550872800' \
  end_time='1550923200'

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "get_unique_recipient_count_per_sender_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all cPanel account unique email recipients

This function gets a count of the email addresses that each system account sent mail to within a specific period of time. It groups the data by each system user for all the system's users.

Authorizations:
BasicAuth
query Parameters
end_time
required
integer <unix_timestamp>
Example: end_time=1551192100

An end time to query.

start_time
required
integer <unix_timestamp>
Example: start_time=1550702383

A start time to query.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_unique_sender_recipient_count_per_user \
  start_time='1550702383' \
  end_time='1551192100'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "unique_sender_recipient_count": 120,
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "get_unique_sender_recipient_count_per_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Suspend cPanel account outgoing email

This function sets Exim's queue to suspend and force failure for email that a user sends to an external address.

Note:

If mail for a cPanel user's account is suspended, the system will reject their email before the mail server puts it in queue.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=example

The cPanel account.

Note

You cannot suspend the root user's outgoing email with this function.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  suspend_outgoing_email \
  user='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "suspend_outgoing_email",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove email account messages by Dovecot query

This function removes mail messages from a cPanel account that you select with a query.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
account
required
string <email>

An email account that exists on the server.

mailbox
required
string
Example: mailbox=INBOX

A mailbox name on the account.

Note:

Because you cannot escape wildcard characters such as (*), we recommend that you use functions that use the mailbox_guid parameter instead. For example, the WHM API 1 expunge_messages_for_mailbox_guid function.

query
required
string
Example: query=savedbefore 52w

A Dovecot search query to select which messages you wish to remove from the mailbox.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  expunge_mailbox_messages \
  account='[email protected]' \
  mailbox='INBOX' \
  query='savedbefore 52w'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "expunge_mailbox_messages",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove email account messages by mailbox GUID

This function removes mail messages from a cPanel account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
account
required
string

The email account's name.

mailbox_guid
required
string
Example: mailbox_guid=2550860f0c58d158c92a000044f0d230

The mailbox's globally unique identifier (GUID).

Note:

To find the mailbox GUID, use the WHM API 1 - get_mailbox_status function.

query
required
string
Example: query=savedbefore 52w

The Dovecot search query to select which messages you wish to remove from the mailbox. For more information, read Dovecot's Search Query documentation.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  expunge_messages_for_mailbox_guid \
  account='[email protected]' \
  mailbox_guid='2550860f0c58d158c92a000044f0d230' \
  query='savedbefore 52w'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "expunge_messages_for_mailbox_guid",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account mailboxes status by name

This function lists the status of a cPanel's mail account's mailboxes.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
required
string or string

An email account or cPanel account's username.

Note:

_mainaccount is an alias representing the cPanel user's mailbox (for example, `_mainaccount@example.com represents the example mailbox.)

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_mailbox_status \
  account='[email protected]'

Response samples

Content type
application/json
{
  • "data": {
    • "INBOX": {
      • "guid": "111111234560f0c58d158c92a000044f",
      • "messages": 42000,
      • "vsize": 42
      },
    • "INBOX.Drafts": {
      • "guid": "11111111234560f0c58d158c92a00000",
      • "messages": 5,
      • "vsize": 522
      },
    • "INBOX.Sent": {
      • "guid": "1111111234560f0c58d158c92a000004",
      • "messages": 1,
      • "vsize": 56
      },
    • "INBOX.Trash": {
      • "guid": "1111234560f0c58d158c92a000044f0d",
      • "messages": 2001,
      • "vsize": 5643
      },
    • "INBOX.angel_face@example_com": {
      • "guid": "11234560f0c58d158c92a000044f0d23",
      • "messages": 3,
      • "vsize": 1524
      },
    • "INBOX.marla_singer@example_com": {
      • "guid": "1234560f0c58d158c92a000044f0d230",
      • "messages": 5,
      • "vsize": 100
      },
    • "INBOX.narrator@example_com": {
      • "guid": "11111234560f0c58d158c92a000044f0",
      • "messages": 0,
      • "vsize": 0
      },
    • "INBOX.robert_paulsen@example_com": {
      • "guid": "111111111234560f0c58d158c92a0001",
      • "messages": 2,
      • "vsize": 2222
      },
    • "INBOX.tyler_durden@example_com": {
      • "guid": "111234560f0c58d158c92a000044f0d2",
      • "messages": 55,
      • "vsize": 12244
      }
    },
  • "metadata": {
    • "command": "get_mailbox_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account mailboxes status list

This function lists the status of a cPanel's mail account's mailboxes.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
required
string or string or string

The email account's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_mailbox_status_list \
  account='[email protected]'

Response samples

Content type
application/json
{
  • "data": {
    • "mailboxes": [
      • {
        • "guid": "1234560f0c58d158c92a000044f0d230",
        • "mailbox": "INBOX.marla_singer@example_com",
        • "messages": 0,
        • "vsize": 0
        }
      ]
    },
  • "metadata": {
    • "command": "get_mailbox_status_list",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account email tracking statistics

This function retrieves email tracking statistics.

Authorizations:
BasicAuth
query Parameters
deliverytype
string
Possible Values: "remote" "remote-or-faildefer" "local"
Example: deliverytype=remote

The type of delivery to query. If you do not specify a value, this function returns all types.

  • remote
  • remote-or-faildefer
  • local
endtime
integer <unix_timestamp>
Default: "the current time"
Example: endtime=1471552781

The end time of the search window. This parameter defaults to the current time.

Note

You can also call this the enddate parameter.

nosize
integer
Default: 0
Possible Values: 0 1
Example: nosize=0

Whether to return the TOTALSIZE parameter.

  • 1 — Do not return.
  • 0 — Return.
nosuccess
integer
Default: 0
Possible Values: 0 1
Example: nosuccess=0

Whether to return the SUCCESSCOUNT parameter.

  • 1 — Do not return.
  • 0 — Return.
starttime
integer <unix_timestamp>
Default: 0
Example: starttime=1371552781

The start time of the search window.

Note

You can also call this the startdate parameter.

user
string
Example: user=username

The cPanel username to query. If you do not specify a value, the function retrieves statistics for all of the server's accounts.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  emailtrack_stats

Response samples

Content type
application/json
{
  • "data": {
    • "records": [
      • {
        • "DEFERCOUNT": 0,
        • "DEFERFAILCOUNT": 0,
        • "FAILCOUNT": 0,
        • "INPROGRESSCOUNT": 0,
        • "SENDCOUNT": 14,
        • "SUCCESSCOUNT": 14,
        • "TOTALSIZE": 27444
        }
      ]
    },
  • "metadata": {
    • "command": "emailtrack_stats",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all cPanel accounts email tracking statistics

This function retrieves email tracking statistics for each user.

Authorizations:
BasicAuth
query Parameters
deliverytype
string
Possible Values: "remote" "remote-or-faildefer" "local"
Example: deliverytype=remote

The type of delivery to query. If you do not specify a value, this function returns all types.

  • remote
  • remote-or-faildefer
  • local
endtime
integer <unix_timestamp>
Default: "the current time"
Example: endtime=1471552781

The end time of the search window.

sender
string <email>

The sender's email address. If you do not specify a value, this function returns entries for mail from all senders.

starttime
integer <unix_timestamp>
Default: 0
Example: starttime=1371552781

The start time of the search window.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  emailtrack_user_stats

Response samples

Content type
application/json
{
  • "data": {
    • "records": [
      • {
        • "DEFERCOUNT": 0,
        • "DEFERFAILCOUNT": 0,
        • "DOMAIN": "example.com",
        • "FAILCOUNT": 0,
        • "OWNER": "root",
        • "PRIMARY_DOMAIN": "example.com",
        • "REACHED_MAXDEFERFAIL": 1,
        • "REACHED_MAXEMAILS": 1,
        • "SENDCOUNT": 14,
        • "SUCCESSCOUNT": 14,
        • "TOTALSIZE": 27444,
        • "USER": "example"
        }
      ]
    },
  • "metadata": {
    • "command": "emailtrack_user_stats",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Release cPanel account queued outgoing emails

This function releases outgoing email in the email queue for a single cPanel account user.

Note:

If mail for a cPanel user's account is suspended, the system will reject their email before the mail server puts it in queue.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=example

The cPanel account.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  release_outgoing_email \
  user='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "release_outgoing_email",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add cPanel account to outbound email hold queue

This function sets Exim's queue to hold email that a user sends to an external address.

Note:

If mail for a cPanel user's account is suspended, the system will reject their email before the mail server puts it in the queue.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=example

The cPanel account.

Note

You cannot suspend the root user's outgoing email with this function.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  hold_outgoing_email \
  user='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "hold_outgoing_email",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Stop cPanel account IMAP and POP3 connections

This function terminates all IMAP and POP3 connections for a cPanel account.

Note:

This function ends connections for every email address, which includes the default address.

Authorizations:
BasicAuth
query Parameters
username
required
string <username>
Example: username=username

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  terminate_cpuser_mailbox_sessions \
  username='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "terminate_cpuser_mailbox_sessions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Mail DNS Settings

Mail / Mail DNS Settings

Set the server's default DMARC record

This function sets the server's default DMARC record.

The system uses the default DMARC record when creating new accounts or applying DMARC policies that don't specify a custom record.

Note:

You can pass an empty string to remove the custom default and revert to the built-in default record.

Authorizations:
BasicAuth
query Parameters
record
string
Examples:
  • record=v=DMARC1; p=none; - A basic DMARC record with none policy
  • record= - Remove custom default (empty string)

The DMARC record to set as the server default.

Note:

The record must be a valid DMARC record that starts with v=DMARC1; and contains a policy directive (p=none, p=quarantine, or p=reject).

Pass an empty string to remove the custom default and revert to the built-in default.

Visit the following link for more information about the DMARC record specification: https://dmarc.org/resources/specification/.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_default_dmarc_record \
  record='v=DMARC1; p=quarantine; rua=mailto:[email protected];'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": {
      • "success": 1
      }
    },
  • "metadata": {
    • "command": "set_default_dmarc_record",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Get the server's default DMARC record

This function retrieves the server's default DMARC record.

The system uses the default DMARC record when creating new accounts or applying DMARC policies that don't specify a custom record.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_default_dmarc_record

Response samples

Content type
application/json
{
  • "data": {
    • "payload": {
      • "record": "v=DMARC1; p=none;"
      }
    },
  • "metadata": {
    • "command": "get_default_dmarc_record",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate DMARC records

This function retrieves and checks the DMARC record for one or more domains.

Authorizations:
BasicAuth
query Parameters
domain
string
Examples:
  • domain=domain-1=example.com&domain-2=example.com&domain-3=example3.com - Check the DMARC record for multiple domains.
  • domain=domain=example.com&domain=example2.com&domain=example3.com - Check the DMARC record for multiple domains.
  • domain=domain=example.com - Check the DMARC records for a single domain.

The domain for which to check the DMARC record.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, domain-1, domain-2, and domain-3 parameters.

If you do not include this argument, the system will validate DMARC records for all domains on the server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_current_dmarcs \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "error": "",
        • "record": "v=DMARC1; p=none;",
        • "state": "VALID",
        • "subdomain": "_dmarc.example.com",
        • "suggested": "v=DMARC1; p=none;"
        },
      • {
        • "domain": "example2.com",
        • "error": "(XID 4krw35) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “_dmarc.example2.com”’s “TXT” records.",
        • "record": "",
        • "state": "DNS_ERROR",
        • "subdomain": "_dmarc.example2.com",
        • "suggested": "v=DMARC1; p=none;"
        }
      ]
    },
  • "metadata": {
    • "command": "validate_current_dmarcs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Apply a DMARC record to a domain

This function applies a DMARC record to the specified domain(s).

Note:

You cannot modify DMARC records on temporary domains.

Authorizations:
BasicAuth
query Parameters
domain
string
Examples:
  • domain=domain=example-1.com domain=example-2.com domain=example-3.com - To apply multiple DMARC records
  • domain=example.com - To apply a single domain DMARC record

The domain for which to apply the DMARC record.

Note:

To apply multiple domain DMARC records, duplicate the parameter name. For example, use the domain=example-1.com, domain=example-2.com, and domain=example-3.com parameters.

If you do not include this argument, the system applies the DMARC record to all domains on the system.

policy
required
string
Examples:
  • policy=policy="v=DMARC1; p=none;" policy="v=DMARC1; p=reject;" policy="v=DMARC1; p=quarantine;" - To apply multiple DMARC policies, duplicate the policy arguments.
  • policy=policy="v=DMARC1;p=reject;pct=100;rua=mailto:[email protected]" - To apply a single DMARC record to domains, specify a single policy.

The DMARC record to apply to the requested domains.

Note:

When using multiple policies, each policy must have a matching domain.

When using a single policy, it will be applied to all specified domains.

Visit the following link for more information about the DMARC record specification: https://dmarc.org/resources/specification/

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  apply_dmarc \
  domain='example.com' \
  policy='v=DMARC1; p=reject;'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "[ADD:TXT@_dmarc.example.com:v=DMARC1; p=reject;]",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "apply_dmarc",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove domains' DMARC records.

This function removes the DMARC DNS record from a domain.

Note:

You cannot remove DMARC records from temporary domains.

Authorizations:
BasicAuth
query Parameters
domain
string
Examples:
  • domain=domain=example-1.com domain=example-2.com domain=example-3.com - To remove multiple domain DMARC records
  • domain=example.com - To remove a single domain DMARC record

The domain for which to remove the DMARC record.

Note:

If you do not include this argument, the system will remove all DMARC records from all domains.

To remove multiple domain DMARC records, duplicate the parameter name. For example, use the domain=example-1.com, domain=example-2.com, and domain=example-3.com parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_dmarc \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "[REMOVE:TXT@_dmarc.exmaple.com:v=DMARC1; p=reject;]",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "remove_dmarc",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable domain's DKIM records

This function removes the DomainKeys Identified Mail (DKIM) records on the DNS server for one or more domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example-1.com domain=example-2.com domain=example-3.com - To remove multiple domain DKIM records
  • domain=example.com - To remove a single domain DKIM record

The domain for which to remove DKIM records on the DNS server.

Note:

To remove multiple domain DKIM records, duplicate the parameter name. For example, use the domain=example-1.com, domain=example-2.com, and domain=example-3.com parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_dkim \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "[REMOVE:TXT@default._domainkey:v=DKIM1; k=rsa; p=MIGfMAOGCSqGSIb3DQEBAQUAA4GNADCBiLMNOpQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO/xJtrPZKskZF8/sU0zWGTqKUOErlyJfoJzMDUv3/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB;]",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "disable_dkim",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable domain's DKIM records

This function enables DomainKeys Identified Mail (DKIM) records on the DNS server for one or more domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example-1.com domain=example-2.com domain=example-3.com - To enable multiple domain DKIM records
  • domain=example.com - To enable a single domain DKIM record

The domain for which to enable DKIM records on the DNS server.

Note:

To enable multiple domain DKIM records, duplicate the parameter name. For example, use the domain=example-1.com, domain=example-2.com, and domain=example-3.com parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_dkim \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "Installed Keys",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "enable_dkim",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain's DKIM private key

This function returns a domain's installed DKIM private key in Privacy-Enhanced Mail (PEM) format.

Warning:

We strongly recommend that you protect your private key. If others obtain your private DKIM key, they could sign emails and impersonate you as a sender.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example-1.com&domain=example-2.com&domain=example-3.com - Query multiple domains.
  • domain=example.com - Query a single domain.

The queried domain.

Note:

To retrieve multiple domain DKIM keys, increment the parameter name. For example, use the domain-1=example-1.com, domain-2=example-2.com, and domain-3=example-3.com parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_dkim_private_keys \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "pem": "-----BEGIN RSA PRIVATE KEY-----\nMIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G\nA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2VydGlmaWNhdGUgYXV0aG9y\naXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdudVRMUyBjZXJ0aWZpY2F0\nZSBhdXRob3JpdHkwHhcNMTEwNTIzMjAzODIxWhcNMTIxMjIyMDc0MTUxWjB9MQsw\nCQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2Vy\ndGlmaWNhdGUgYXV0aG9yaXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdu\ndVRMUyBjZXJ0aWZpY2F0ZSBhdXRob3JpdHkwWTATBgcqhkjOPQIBBggqhkjOPQMB\nBwNCAARS2I0jiuNn14Y2sSALCX3IybqiIJUvxUpj+oNfzngvj/Niyv2394BWnW4X\nuQ4RTEiywK87WRcWMGgJB5kX/t2no0MwQTAPBgNVHRMBAf8EBTADAQH/MA8GA1Ud\nDwEB/wQFAwMHBgAwHQYDVR0OBBYEFPC0gf6YEr+1KLlkQAPLzB9mTigDMAoGCCqG\nSM49BAMCA0gAMEUCIDGuwD1KPyG+hRf88MeyMQcqOFZD0TbVleF+UsAGQ4enAiEA\nl4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo==\n-----END RSA PRIVATE KEY-----\n"
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_dkim_private_keys",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate domain's DKIM keys

This function confirms the validity of a DomainKeys Identified Mail (DKIM) key for one or more domains.

Note:

  • If an existing DKIM key does not meet the server's security requirements, the system replaces the existing DKIM key.
  • If no DKIM key exists, the system creates a new key for the domain.
Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example1.com&domain=example2.com&domain=example3.com - Check the DKIM key validity for multiple domains.
  • domain=example.com - Check the DKIM key validity for a single domain.

The domain for which to confirm a valid DKIM key exists.

Note:

To check the DKIM key validity for multiple domain, duplicate the parameter name. For example, use the domain-1=example.com, domain-2=example2.com, and domain-3=example3.com parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ensure_dkim_keys_exist \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "created new key",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "ensure_dkim_keys_exist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Install existing private key to DKIM record

This function installs existing keys for use in a DomainKeys Identified Mail (DKIM) record. This is useful if you do not want the system to generate keys for DKIM records.

Notes:

  • This function does not update the local DNS server's records.
  • If the local DNS server is authoritative for the domain's DNS records, use the WHM API 1 enable_dkim function to update the local DNS server's DNS records.
  • We recommend that you use the WHM API 1 install_dkim_private_keys and enable_dkim functions in a batch WHM API 1 call.
Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Examples:
  • domain=domain-1=example-1.com&domain-2=example-2.com&domain-3=example-3.com - The domains for which to install an RSA private key to the local server's DKIM record.
  • domain=example.com - The domain for which to install an RSA private key to the local server's DKIM record.

The domain for which to install an RSA private key to the local server's DKIM record.

Note:

To install RSA private keys for multiple domains, increment the parameter name. For example, use the domain-1=example-1.com, domain-2=example-2.com, and domain-3=example-3.com parameters.

key
required
string
Example: key=AAAAB3NzaC1yc2EAAAABIwAAAQEA5kSivOqhs0U9ZMN20nxFe27QZ3t0lT2zbH7OSXylKd1rjAjYXGnSXC9j2uaZlemHlptBKVziMJC86ha7Hcj6dVOVrDQ6vF4q34bOCjtKLphQ0IjBzVIvqILH9eLJdRaOrS34CmgmPaisrCk5wKVlakygvUfcj3HzaTKS6THyZDGx5shdTpa9lby8tpOD3JceV7ay4w8r0DipoKPC0OLpvS4EABEeMo9sx8zQEaKv03XygjNCCYtFvxlQQIRGlVoL7mPaHSaL3anI05RpNbm/PS+9BhZg+BqNjU4ofHBbfkXk5MiN6M7ieR4Sk5BquccboGF13U5slNgmCEekdt0amw

An RSA key in Privacy-Enhanced Mail (PEM) format.

Note:

  • You must provide this parameter for each domain parameter.
  • To install multiple RSA keys for a domain, increment the parameter name. For example, use the key-1, key-2 parameters. examples: single: summary: An RSA key in Privacy-Enhanced Mail (PEM) format. value: key multiple: summary: RSA keys in Privacy-Enhanced Mail (PEM) format. value: key-1=KEYKEYKEY&key-2=KEYKEYKEY

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  install_dkim_private_keys \
  domain='example.com' \
  key='AAAAB3NzaC1yc2EAAAABIwAAAQEA5kSivOqhs0U9ZMN20nxFe27QZ3t0lT2zbH7OSXylKd1rjAjYXGnSXC9j2uaZlemHlptBKVziMJC86ha7Hcj6dVOVrDQ6vF4q34bOCjtKLphQ0IjBzVIvqILH9eLJdRaOrS34CmgmPaisrCk5wKVlakygvUfcj3HzaTKS6THyZDGx5shdTpa9lby8tpOD3JceV7ay4w8r0DipoKPC0OLpvS4EABEeMo9sx8zQEaKv03XygjNCCYtFvxlQQIRGlVoL7mPaHSaL3anI05RpNbm/PS+9BhZg+BqNjU4ofHBbfkXk5MiN6M7ieR4Sk5BquccboGF13U5slNgmCEekdt0amw'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "Installed Keys",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "install_dkim_private_keys",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Install domain SPF record

This function installs a Sender Policy Framework (SPF) record for a domain on the DNS server.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Examples:
  • domain=domain-1=example-1.com&domain-2=example-2.com&domain-3=example-3.com - Multiple domains
  • domain=example.com - Single domain

The domain for which to install an SPF record on the DNS server.

Note:

To install multiple SPF records, increment the parameter name. For example, use the domain-1=example-1.com, domain-2=example-2.com, and domain-3=example3.com parameters.

record
required
string
Example: record=v%3Dspf1%20%2Bip4%3A1192.0.2.0%20-all

An SPF record.

You must provide this parameter for every domain parameter.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  install_spf_records \
  domain='example.com' \
  record='v%3Dspf1%20%2Bip4%3A1192.0.2.0%20-all'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "msg": "[REPLACE:[email protected].:v=spf1 ip4:192.0.2.0 -all]",
        • "status": 1
        }
      ]
    },
  • "metadata": {
    • "command": "install_spf_records",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate DKIM records

This function retrieves and checks the DomainKeys Identified Mail (DKIM) records for one or more domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain-1=example.com&domain-2=example.com&domain-3=example3.com - Check the DKIM records for multiple domains.
  • domain=domain=example.com&domain=example2.com&domain=example3.com - Check the DKIM records for multiple domains.
  • domain=example.com - Check the DKIM records for a single domain.

The domain for which to check the DKIM records.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, domain-1, domain-2, and domain-3 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_current_dkims \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "default._domainkey.example.com",
        • "expected": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO/xJtrPZKskZF8/sU0zWGTqKUOErlyJfoJzMDUv3/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB\\",
        • "records": [
          • {
            • "current": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO/xJtrPZKskZF8/sU0zWGTqKUOErlyJfoJzMDUv3/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB\\",
            • "state": "VALID"
            }
          ],
        • "state": "VALID",
        • "validity_cache_update": "valid"
        },
      • {
        • "domain": "default._domainkey.example2.com",
        • "error": "(XID 4krw35) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “default._domainkey.example2.com”’s “TXT” records.",
        • "expected": "v=DKIM1; k=rsa; p=MIIBIjAAAgkrhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4mA8NH3BkYvOmB0+ll23U78JesahG8304unKhW+MAm0ZE+i6EWN6iXhUj7FRPvI/6jFRd7qAHCPKFLo5+/PTy8C8eK312tfSnF3N0eucYFbgZ8F8iSRdgrcgEjvJ1vM1uvcUF211yd/e3jxT2Ge4/fmZcTYNjfH3uAuriv61L6pdIwHUWPhcjQvgOQoKQgXgooCUbUkWFDkMAH+EF/0g1dnXf289LjlvQsKhY7Y135Zpvm21kjUcj5mrLDlHJALzCVb8K/r/LCxjV5GFUyJiiNLAxkI9V1vZ4pMQvKIsN7wzu6gXK87w6mEWvKvipMAP8A2choDrk6H/fcQtfNodgwIDADAB;",
        • "records": [ ],
        • "state": "ERROR",
        • "validity_cache_update": "none"
        }
      ]
    },
  • "metadata": {
    • "command": "validate_current_dkims",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate domain SPF records

This function validates a Sender Policy Framework (SPF) record for one or more domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Examples:
  • domain=domain-1=example.com domain-2=example2.com domain-3=example3.com - Check multiple domains.
  • domain=domain=example.com domain=example2.com domain=example3.com - Check multiple domains.
  • domain=example.com - Check a single domain.

The domain for which to check the SPF records.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_current_spfs \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "domain": "example.com",
        • "expected": "ip6:0:0:0:0:0:ffff:c0a8:101",
        • "ip_address": "0:0:0:0:0:ffff:c0a8:101",
        • "ip_version": 6,
        • "records": [
          • {
            • "current": "v=spf1 ~all",
            • "reason": "example.com: Sender is not authorized by default to use 'example.com' in 'helo' identity (mechanism '-all' matched)",
            • "state": "FAIL"
            }
          ],
        • "state": "VALID"
        },
      • {
        • "domain": "example2.com",
        • "error": "(XID rm8h9f) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “example2.com”’s “TXT” records.",
        • "ip_address": "198.252.32.45",
        • "ip_version": 4,
        • "records": [ ],
        • "state": "ERROR"
        }
      ]
    },
  • "metadata": {
    • "command": "validate_current_spfs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate domain PTR records

This function validates the pointer records (PTR) for IPv4 and IPv6 addresses an account's domains send mail from. It retrieves the PTR records for each IP address and determines which of the domain's IP addresses send mail. It then validates the PTR records for each IP address and validates the A (IPv4) or AAAA (IPv6) records pointing to each domain. This function also ensures that at least one of that domain's A or AAAA records points back to the IP address.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain-1=example.com domain-2=example2.com domain-3=example3.com - Validate multiple domains' PTR records.
  • domain=domain=example.com&domain=example2.com&domain=example3.com - Validate multiple domains' PTR records.
  • domain=example.com - Validate a single domain's PTR records.

The domain for which to validate the PTR records.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, use the domain-1, domain-2, and domain-3 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_current_ptrs \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "arpa_domain": "1.0.0.10.in-addr.arpa",
        • "domain": "example.com",
        • "helo": "example.com",
        • "ip_address": "10.0.0.1",
        • "ip_version": 4,
        • "nameservers": [
          • "ns1.example.com",
          • "ns2.example.com",
          • "ns3.example.com"
          ],
        • "ptr_records": [
          • {
            • "domain": "example.com",
            • "forward_records": [
              • "10.0.0.1"
              ],
            • "state": "VALID"
            }
          ],
        • "state": "VALID"
        },
      • {
        • "arpa_domain": "3.0.0.10.in-addr.arpa",
        • "domain": "example.com",
        • "helo": "example.com",
        • "ip_address": "10.0.0.3",
        • "ip_version": 4,
        • "nameservers": [
          • "ns1.example.com",
          • "ns2.example.com",
          • "ns3.example.com"
          ],
        • "ptr_records": [
          • {
            • "domain": "example.com",
            • "forward_records": [
              • "192.168.12.34"
              ],
            • "state": "FWD_MISMATCH"
            }
          ],
        • "state": "PTR_MISMATCH"
        },
      • {
        • "arpa_domain": "4.3.3.7.0.7.3.0.e.2.a.8.0.0.0.0.0.0.0.0.3.a.5.8.8.b.d.0.1.0.0.2.ip6.arpa",
        • "domain": "example.com",
        • "helo": "example.com",
        • "ip_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
        • "ip_version": 6,
        • "nameservers": [
          • "ns1.example.com",
          • "ns2.example.com",
          • "ns3.example.com"
          ],
        • "ptr_records": [
          • {
            • "domain": "example.com",
            • "forward_records": [
              • "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
              ],
            • "state": "VALID"
            }
          ],
        • "state": "VALID"
        },
      • {
        • "arpa_domain": "2.0.0.10.in-addr.arpa",
        • "domain": "example.com",
        • "helo": "example.com",
        • "ip_address": "10.0.0.2",
        • "ip_version": 4,
        • "nameservers": [
          • "ns1.example.com",
          • "ns2.example.com",
          • "ns3.example.com"
          ],
        • "ptr_records": [ ],
        • "state": "MISSING_PTR"
        },
      • {
        • "domain": "thisotheremaildomain.com",
        • "error": "1.1.1.1.1 is not a valid IP address.",
        • "helo": "thisothermaildomain.com",
        • "ip_address": "1.1.1.1.1",
        • "ptr_records": [ ],
        • "state": "ERROR"
        },
      • {
        • "arpa_domain": "4.0.0.10.in-addr.arpa",
        • "domain": "example.com",
        • "helo": "example.com",
        • "ip_address": "10.0.0.4",
        • "ip_version": 4,
        • "nameservers": [
          • "ns1.example.com",
          • "ns2.example.com",
          • "ns3.example.com"
          ],
        • "ptr_records": [
          • {
            • "domain": "example.com",
            • "forward_records": [ ],
            • "state": "MISSING_FWD"
            }
          ],
        • "state": "PTR_MISMATCH"
        }
      ]
    },
  • "metadata": {
    • "command": "validate_current_ptrs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add manual mail exchanger redirect record

This function lets you create a manual Exim mail exchanger (MX) redirect for a domain. An MX redirection lets you bypass the domain's MX lookup via the Domain Name System (DNS). This function adds the manual redirect entries to the /etc/manualmx file.

Note:

To remove a domain's manual MX redirection, use the WHM API 1 unset_manual_mx_redirect function.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to add a manual MX redirect entry.

Note:

To add multiple domain entries, increment the parameter. For example, use the domain, domain-1, and domain-2 parameters. For multiple domains, you must include its corresponding mx_host value.

mx_host
required
string
Example: mx_host=mailhostexample.com

The domain or IP address (IPv4 or IPv6) to redirect the domain value's emails to.

Note:

To add multiple MX hosts, increment the parameter. For example, use the mx_host, mx_host-1, and mx_host-2 parameters. For multiple MX hosts, you must include its corresponding domain value.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_manual_mx_redirects \
  domain='example.com' \
  mx_host='mailhostexample.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": {
      • "example.com": "mailhostexample.com",
      • "example.org": null
      }
    },
  • "metadata": {
    • "command": "set_manual_mx_redirects",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove manual mail exchanger redirect record

This function removes a domain's manual Exim mail exchanger (MX) redirect entry. The function also removes the manual MX redirect entry from the /etc/manualmx file.

Note:

To set a domain's manual MX redirection, use the WHM API 1 set_manual_mx_redirects function.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The domain for which to remove a manual MX redirect entry.

Note:

To remove multiple domain entries, increment the parameter. For example, use the domain, domain-1, and domain-2 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  unset_manual_mx_redirects \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": {
      • "example.com": "mailhostexample.com",
      • "example.org": null
      }
    },
  • "metadata": {
    • "command": "unset_manual_mx_redirects",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Mail Server Settings

Mail / Mail Server Settings

Create email account mobile profile configuration

This function generates a mobile configuration profile for an email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
account
required
string
Example: account=username

The email account's username.

selected_account_services
string
Default: "email,caldav,carddav"
Possible Values: "caldav" "carddav" "email"
Example: selected_account_services=email

A comma-separated list of the email account service's .mobileconfig file names.

  • caldav — The .mobileconfig file for calendar setup.
  • carddav — The .mobileconfig file for contacts setup.
  • email — The .mobileconfig file for email setup.

Note:

  • If you don't specify a value, this parameter uses the default values.
  • You can request one, two, or all possible values.
  • The function ignores unsupported values.
use_ssl
required
integer
Possible Values: 0 1
Example: use_ssl=1

Whether to use an SSL-encrypted connection.

  • 1 — Use an SSL-encrypted connnection.
  • 0 — Do not use an SSL-encrypted connection.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  generate_mobileconfig \
  account='username' \
  use_ssl='1'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": "MIIcIwYJKoZIhvcNAQcCoIIcFDCCHBACAQExDzANBglghkgBZQMEAgEFADCCFS4GCSqGSIb3DQEH\nAaCCFR8EghUbPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjwhRE9DVFlQ\nRSBwbGlzdCBQVUJMSUMgIi0vL0FwcGxlLy9EVEQgUExJU1QgMS4wLy9FTiIgImh0dHA6Ly93d3cu\nYXBwbGUuY29tL0RURHMvUHJvcGVydHlMaXN0LTEuMC5kdGQiPg0KPHBsaXN0IHZlcnNpb249IjEu\nMCI+DQo8ZGljdD4NCiAgPGtleT5QYXlsb2FkQ29udGVudDwva2V5Pg0KICA8YXJyYXk+DQogICAg\nPGRpY3Q+DQogICAgICAgIDxrZXk+Q2FsREFWQWNjb3VudERlc2NyaXB0aW9uPC9rZXk+DQogICAg\nICAgIDxzdHJpbmc+dXNlcm5hbWVAaG9zdC0xNzItMTYtMS0xMS5hc2hsZXk4MnNiLnRsZDwvc3Ry\naW5nPg0KICAgICAgICA8a2V5PkNhbERBVkhvc3ROYW1lPC9rZXk+DQogICAgICAgIDxzdHJpbmc+\naG9zdC0xNzItMTYtMS0xMS5hc2hsZXk4MnNiLnRsZDwvc3RyaW5nPg0KICAgICAgICA8a2V5PkNh\nbERBVlBvcnQ8L2tleT4NCiAgICAgICAgPGludGVnZXI+ODQ0MzwvaW50ZWdlcj4NCiAgICAgICAg\nPGtleT5DYWxEQVZQcmluY2lwYWxVUkw8L2tleT4NCiAgICAgICAgPHN0cmluZz4vcHJpbmNpcGFs\ncy9fX3VpZHNfXy8vPC9zdHJpbmc+DQogICAgICAgIDxrZXk+Q2FsREFWVXNlU1NMPC9rZXk+DQog\nICAgICAgIDx0cnVlLz4NCiAgICAgICAgPGtleT5DYWxEQVZVc2VybmFtZTwva2V5Pg0KICAgICAg\nICA8c3RyaW5nPnVzZXJuYW1lPC9zdHJpbmc+DQogICAgICAgIDxrZXk+UGF5bG9hZERlc2NyaXB0\naW9uPC9rZXk+DQogICAgICAgIDxzdHJpbmc+dXNlcm5hbWVAaG9zdC0xNzItMTYtMS0xMS5hc2hs\nZXk4MnNiLnRsZCBTZWN1cmUgQ2FsZW5kYXIgU2V0dXA8L3N0cmluZz4NCiAgICAgICAgPGtleT5Q\nYXlsb2FkRGlzcGxheU5hbWU8L2tleT4NCiAgICAgICAgPHN0cmluZz51c2VybmFtZUBob3N0LTE3\nMi0xNi0xLTExLmFzaGxleTgyc2IudGxkIFNlY3VyZSBDYWxlbmRhciBTZXR1cDwvc3RyaW5nPg0K\nICAgICAgICA8a2V5PlBheWxvYWRJZGVudGlmaWVyPC9rZXk+DQogICAgICAgIDxzdHJpbmc+Y3Bh\nbmVsLm1haWwub3JnLnVzZXJuYW1lLmhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQ8L3N0\ncmluZz4NCiAgICAgICAgPGtleT5QYXlsb2FkT3JnYW5pemF0aW9uPC9rZXk+DQogICAgICAgIDxz\ndHJpbmc+aG9zdC0xNzItMTYtMS0xMS5hc2hsZXk4MnNiLnRsZDwvc3RyaW5nPg0KICAgICAgICA8\na2V5PlBheWxvYWRUeXBlPC9rZXk+DQogICAgICAgIDxzdHJpbmc+Y29tLmFwcGxlLmNhbGRhdi5h\nY2NvdW50PC9zdHJpbmc+DQogICAgICAgIDxrZXk+UGF5bG9hZFVVSUQ8L2tleT4NCiAgICAgICAg\nPHN0cmluZz4wNWQ3OTBjMS03MjVlLTIxODUtMDM1YS0yODNiZGJkMDUxMWQ8L3N0cmluZz4NCiAg\nICAgICAgPGtleT5QYXlsb2FkVmVyc2lvbjwva2V5Pg0KICAgICAgICA8aW50ZWdlcj4xPC9pbnRl\nZ2VyPg0KICAgIDwvZGljdD4NCiAgICA8ZGljdD4NCiAgICAgICAgPGtleT5DYXJkREFWQWNjb3Vu\ndERlc2NyaXB0aW9uPC9rZXk+DQogICAgICAgIDxzdHJpbmc+dXNlcm5hbWVAaG9zdC0xNzItMTYt\nMS0xMS5hc2hsZXk4MnNiLnRsZCBTZWN1cmUgQ29udGFjdHMgU2V0dXA8L3N0cmluZz4NCiAgICAg\nICAgPGtleT5DYXJkREFWSG9zdE5hbWU8L2tleT4NCiAgICAgICAgPHN0cmluZz5ob3N0LTE3Mi0x\nNi0xLTExLmFzaGxleTgyc2IudGxkOjg0NDM8L3N0cmluZz4NCiAgICAgICAgPGtleT5DYXJkREFW\nVXNlU1NMPC9rZXk+DQogICAgICAgIDx0cnVlLz4NCiAgICAgICAgPGtleT5DYXJkREFWVXNlcm5h\nbWU8L2tleT4NCiAgICAgICAgPHN0cmluZz51c2VybmFtZTwvc3RyaW5nPg0KICAgICAgICA8a2V5\nPlBheWxvYWREZXNjcmlwdGlvbjwva2V5Pg0KICAgICAgICA8c3RyaW5nPnVzZXJuYW1lQGhvc3Qt\nMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQgU2VjdXJlIENvbnRhY3RzIFNldHVwPC9zdHJpbmc+\nDQogICAgICAgIDxrZXk+UGF5bG9hZERpc3BsYXlOYW1lPC9rZXk+DQogICAgICAgIDxzdHJpbmc+\nQ2FyZERBVjwvc3RyaW5nPg0KICAgICAgICA8a2V5PlBheWxvYWRJZGVudGlmaWVyPC9rZXk+DQog\nICAgICAgIDxzdHJpbmc+Y3BhbmVsLm1haWwub3JnLnVzZXJuYW1lLmhvc3QtMTcyLTE2LTEtMTEu\nYXNobGV5ODJzYi50bGQ8L3N0cmluZz4NCiAgICAgICAgPGtleT5QYXlsb2FkT3JnYW5pemF0aW9u\nPC9rZXk+DQogICAgICAgIDxzdHJpbmc+aG9zdC0xNzItMTYtMS0xMS5hc2hsZXk4MnNiLnRsZDwv\nc3RyaW5nPg0KICAgICAgICA8a2V5PlBheWxvYWRUeXBlPC9rZXk+DQogICAgICAgIDxzdHJpbmc+\nY29tLmFwcGxlLmNhcmRkYXYuYWNjb3VudDwvc3RyaW5nPg0KICAgICAgICA8a2V5PlBheWxvYWRV\nVUlEPC9rZXk+DQogICAgICAgIDxzdHJpbmc+Y2U0YTRiYjEtODQ3Yi1hYWQ0LWVkMTUtNzIyMDY2\nMzA5YzIyPC9zdHJpbmc+DQogICAgICAgIDxrZXk+UGF5bG9hZFZlcnNpb248L2tleT4NCiAgICAg\nICAgPGludGVnZXI+MTwvaW50ZWdlcj4NCiAgICA8L2RpY3Q+DQogICAgPGRpY3Q+DQogICAgICA8\na2V5PkVtYWlsQWNjb3VudERlc2NyaXB0aW9uPC9rZXk+DQogICAgICA8c3RyaW5nPnVzZXJuYW1l\nQGhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQ8L3N0cmluZz4NCiAgICAgIDxrZXk+RW1h\naWxBY2NvdW50TmFtZTwva2V5Pg0KICAgICAgPHN0cmluZz51c2VybmFtZUBob3N0LTE3Mi0xNi0x\nLTExLmFzaGxleTgyc2IudGxkPC9zdHJpbmc+DQogICAgICA8a2V5PkVtYWlsQWNjb3VudFR5cGU8\nL2tleT4NCiAgICAgIDxzdHJpbmc+RW1haWxUeXBlSU1BUDwvc3RyaW5nPg0KICAgICAgPGtleT5F\nbWFpbEFkZHJlc3M8L2tleT4NCiAgICAgIDxzdHJpbmc+dXNlcm5hbWVAaG9zdC0xNzItMTYtMS0x\nMS5hc2hsZXk4MnNiLnRsZDwvc3RyaW5nPg0KICAgICAgPGtleT5JbmNvbWluZ01haWxTZXJ2ZXJB\ndXRoZW50aWNhdGlvbjwva2V5Pg0KICAgICAgPHN0cmluZz5FbWFpbEF1dGhQYXNzd29yZDwvc3Ry\naW5nPg0KICAgICAgPGtleT5JbmNvbWluZ01haWxTZXJ2ZXJIb3N0TmFtZTwva2V5Pg0KICAgICAg\nPHN0cmluZz5ob3N0LTE3Mi0xNi0xLTExLmFzaGxleTgyc2IudGxkPC9zdHJpbmc+DQogICAgICA8\na2V5PkluY29taW5nTWFpbFNlcnZlclBvcnROdW1iZXI8L2tleT4NCiAgICAgIDxpbnRlZ2VyPjk5\nMzwvaW50ZWdlcj4NCiAgICAgIDxrZXk+SW5jb21pbmdNYWlsU2VydmVyVXNlU1NMPC9rZXk+DQog\nICAgICA8dHJ1ZS8+DQogICAgICA8a2V5PkluY29taW5nTWFpbFNlcnZlclVzZXJuYW1lPC9rZXk+\nDQogICAgICA8c3RyaW5nPnVzZXJuYW1lPC9zdHJpbmc+DQogICAgICA8a2V5Pk91dGdvaW5nTWFp\nbFNlcnZlckF1dGhlbnRpY2F0aW9uPC9rZXk+DQogICAgICA8c3RyaW5nPkVtYWlsQXV0aFBhc3N3\nb3JkPC9zdHJpbmc+DQogICAgICA8a2V5Pk91dGdvaW5nTWFpbFNlcnZlckhvc3ROYW1lPC9rZXk+\nDQogICAgICA8c3RyaW5nPmhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQ8L3N0cmluZz4N\nCiAgICAgIDxrZXk+T3V0Z29pbmdNYWlsU2VydmVyUG9ydE51bWJlcjwva2V5Pg0KICAgICAgPGlu\ndGVnZXI+NDY1PC9pbnRlZ2VyPg0KICAgICAgPGtleT5PdXRnb2luZ01haWxTZXJ2ZXJVc2VTU0w8\nL2tleT4NCiAgICAgIDx0cnVlLz4NCiAgICAgIDxrZXk+T3V0Z29pbmdNYWlsU2VydmVyVXNlcm5h\nbWU8L2tleT4NCiAgICAgIDxzdHJpbmc+dXNlcm5hbWU8L3N0cmluZz4NCiAgICAgIDxrZXk+T3V0\nZ29pbmdQYXNzd29yZFNhbWVBc0luY29taW5nUGFzc3dvcmQ8L2tleT4NCiAgICAgIDx0cnVlLz4N\nCiAgICAgIDxrZXk+UGF5bG9hZERlc2NyaXB0aW9uPC9rZXk+DQogICAgICA8c3RyaW5nPnVzZXJu\nYW1lQGhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQgU2VjdXJlIEVtYWlsIFNldHVwPC9z\ndHJpbmc+DQogICAgICA8a2V5PlBheWxvYWREaXNwbGF5TmFtZTwva2V5Pg0KICAgICAgPHN0cmlu\nZz51c2VybmFtZUBob3N0LTE3Mi0xNi0xLTExLmFzaGxleTgyc2IudGxkIFNlY3VyZSBFbWFpbCBT\nZXR1cDwvc3RyaW5nPg0KICAgICAgPGtleT5QYXlsb2FkSWRlbnRpZmllcjwva2V5Pg0KICAgICAg\nPHN0cmluZz5jcGFuZWwubWFpbC5vcmcudXNlcm5hbWUuaG9zdC0xNzItMTYtMS0xMS5hc2hsZXk4\nMnNiLnRsZDwvc3RyaW5nPg0KICAgICAgPGtleT5QYXlsb2FkT3JnYW5pemF0aW9uPC9rZXk+DQog\nICAgICA8c3RyaW5nPmhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQ8L3N0cmluZz4NCiAg\nICAgIDxrZXk+UGF5bG9hZFR5cGU8L2tleT4NCiAgICAgIDxzdHJpbmc+Y29tLmFwcGxlLm1haWwu\nbWFuYWdlZDwvc3RyaW5nPg0KICAgICAgPGtleT5QYXlsb2FkVVVJRDwva2V5Pg0KICAgICAgPHN0\ncmluZz5hNmIzZTAxMC0wMGMxLWIyZjAtYWU4Mi03ZmIzZjllODkzM2Y8L3N0cmluZz4NCiAgICAg\nIDxrZXk+UGF5bG9hZFZlcnNpb248L2tleT4NCiAgICAgIDxpbnRlZ2VyPjE8L2ludGVnZXI+DQog\nICAgICA8a2V5PlByZXZlbnRBcHBTaGVldDwva2V5Pg0KICAgICAgPGZhbHNlLz4NCiAgICAgIDxr\nZXk+UHJldmVudE1vdmU8L2tleT4NCiAgICAgIDxmYWxzZS8+DQogICAgICA8a2V5PlNNSU1FRW5h\nYmxlZDwva2V5Pg0KICAgICAgPGZhbHNlLz4NCiAgICAgIDxrZXk+SW5jb21pbmdNYWlsU2VydmVy\nSU1BUFBhdGhQcmVmaXg8L2tleT4NCiAgICAgIDxzdHJpbmc+SU5CT1g8L3N0cmluZz4NCiAgICA8\nL2RpY3Q+DQogIDwvYXJyYXk+DQogIDxrZXk+UGF5bG9hZERlc2NyaXB0aW9uPC9rZXk+DQogIDxz\ndHJpbmc+dXNlcm5hbWVAaG9zdC0xNzItMTYtMS0xMS5hc2hsZXk4MnNiLnRsZCBTZWN1cmUgRW1h\naWwgU2V0dXA8L3N0cmluZz4NCiAgPGtleT5QYXlsb2FkRGlzcGxheU5hbWU8L2tleT4NCiAgPHN0\ncmluZz51c2VybmFtZUBob3N0LTE3Mi0xNi0xLTExLmFzaGxleTgyc2IudGxkIFNlY3VyZSBFbWFp\nbCBTZXR1cDwvc3RyaW5nPg0KICA8a2V5PlBheWxvYWRJZGVudGlmaWVyPC9rZXk+DQogIDxzdHJp\nbmc+Y3BhbmVsLm1haWwub3JnLnVzZXJuYW1lLmhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50\nbGQtZW1haWw8L3N0cmluZz4NCiAgPGtleT5QYXlsb2FkT3JnYW5pemF0aW9uPC9rZXk+DQogIDxz\ndHJpbmc+Y3BhbmVsLm1haWwub3JnLnVzZXJuYW1lLmhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJz\nYi50bGQ8L3N0cmluZz4NCiAgPGtleT5QYXlsb2FkUmVtb3ZhbERpc2FsbG93ZWQ8L2tleT4NCiAg\nPGZhbHNlLz4NCiAgPGtleT5QYXlsb2FkVHlwZTwva2V5Pg0KICA8c3RyaW5nPkNvbmZpZ3VyYXRp\nb248L3N0cmluZz4NCiAgPGtleT5QYXlsb2FkVVVJRDwva2V5Pg0KICA8c3RyaW5nPjRmMzI4YTVm\nLWIzMzctODZmZS03Zjk4LTVhOWMyNzFlNzY0MTwvc3RyaW5nPg0KICA8a2V5PlBheWxvYWRWZXJz\naW9uPC9rZXk+DQogIDxpbnRlZ2VyPjE8L2ludGVnZXI+DQo8L2RpY3Q+DQo8L3BsaXN0Pg0KoIIE\nSTCCBEUwggMtoAMCAQICBQG7jhEyMA0GCSqGSIb3DQEBCwUAMF4xMjAwBgkqhkiG9w0BCQEWI3Nz\nbEBob3N0LTE3Mi0xNi0xLTExLmFzaGxleTgyc2IudGxkMSgwJgYDVQQDDB9ob3N0LTE3Mi0xNi0x\nLTExLmFzaGxleTgyc2IudGxkMB4XDTE5MTExOTEzMDk1OFoXDTIwMTExODEzMDk1OFowXjEyMDAG\nCSqGSIb3DQEJARYjc3NsQGhvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQxKDAmBgNVBAMM\nH2hvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw\nggEKAoIBAQDLTf43fqQJu57fAyGSBD+B/Zc3zVri44KCz/Oi9NlHCtmxET12+mE0TFkWGhjX+tzO\nfom+6Hj5KnGwr8K7qZoXq8zmiKGGvhvg11Ta6I3SJQL7VzU+wTBPXkAl+bWLBqoswzefA7A7jBZE\nv0c8W+wUAosjvmotUtiyeRsNbThTVBht7LwmHyCaAvHfIFkXkS96O6qqx0iZRlXZvahDjw6kiKOB\ne/kDpwl0YxMc3dEx2WCQyIZimtYOxNxglKKZ7UAnuKdy2we3AfOzhq3yKyDXsNyNrQghEn1aB1Ny\nY+/bYZYA/Mhlhk1jjMowEGsjLfJr1Kx6JhtBWzBPfUIkb4q7AgMBAAGjggEIMIIBBDAdBgNVHQ4E\nFgQUlzHaKABlXF/4KWQ7ZrNQij5iE/4wCQYDVR0TBAIwADCBjAYDVR0jBIGEMIGBgBSXMdooAGVc\nX/gpZDtms1CKPmIT/qFipGAwXjEyMDAGCSqGSIb3DQEJARYjc3NsQGhvc3QtMTcyLTE2LTEtMTEu\nYXNobGV5ODJzYi50bGQxKDAmBgNVBAMMH2hvc3QtMTcyLTE2LTEtMTEuYXNobGV5ODJzYi50bGSC\nBQG7jhEyMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAqBgNVHREEIzAhgh9ob3N0LTE3\nMi0xNi0xLTExLmFzaGxleTgyc2IudGxkMA0GCSqGSIb3DQEBCwUAA4IBAQCft6fX2NB0Lg3IM7UU\nw7eltKjsZOX3sCX/UQpwYdB8PcafoQ2Ddpb7H+CeyxW5tPk+qLpapnUWoIJBRahAQ+Xn3YWrJDfC\nFriWIdJH0Rk2Gwhydf7XM+yVm2HYBsAzfZWkF5EAjBJpgLN/28kAWdCv1p362nq79A/jrdKgpZdj\nz6fVb4aNMepJCcwIHivy7HN/PwmbXjqedwAMYsj/XEqw7aJX7+hI3VjFwkQxEbpyObVhcBhh+itt\n1O7t/MMWzg7mmJBnyTt+IbblYYEQoWvZXJgSGWT4U55mWF5arpjL9+NjFsbzvXl6TLEMzbVbpvxH\ntidgoiEpyBgzKFJ9p8TNMYICeTCCAnUCAQEwZzBeMTIwMAYJKoZIhvcNAQkBFiNzc2xAaG9zdC0x\nNzItMTYtMS0xMS5hc2hsZXk4MnNiLnRsZDEoMCYGA1UEAwwfaG9zdC0xNzItMTYtMS0xMS5hc2hs\nZXk4MnNiLnRsZAIFAbuOETIwDQYJYIZIAWUDBAIBBQCggeQwGAYJKoZIhvcNAQkDMQsGCSqGSIb3\nDQEHATAcBgkqhkiG9w0BCQUxDxcNMjAwODE0MjAwMjAwWjAvBgkqhkiG9w0BCQQxIgQguoXcvM7S\nh+TCpzAkazdEcoVI9NI91whPFvfJHZd9x4oweQYJKoZIhvcNAQkPMWwwajALBglghkgBZQMEASow\nCwYJYIZIAWUDBAEWMAsGCWCGSAFlAwQBAjAKBggqhkiG9w0DBzAOBggqhkiG9w0DAgICAIAwDQYI\nKoZIhvcNAwICAUAwBwYFKw4DAgcwDQYIKoZIhvcNAwICASgwDQYJKoZIhvcNAQEBBQAEggEACr8R\nPbw5CymW4Eep61SNsQzH54LXWbaS68mxF+Z8roOSLZTVYhBKP14bGJcUMhsS7c8zGYlOdwXWTA87\n4VQ0O4WIoWOsydxLVgHJ52ZDstN2iXsuW56Cm/Mk7Zow1MFdCJJ/ZX/oKOpnzm/t38kSvTXYyT/X\nLxGnTUYt+QbgUrqrxYZMbZeaAvGXkFTjTSi1kklZdnd7ndvashv5OhQ6zf6y831/c2M7mrn8vJKv\ne44Inb5NRBoK0MAc3f0vmAXrF087ayyNy6E1DqpdPWAGpCKYfIzWtIccrxKcguoIM4mWZ/Lp6mrZ\nI/2K6npCz9Wlm7iYASSsP3NMO8JWk7EWPA==\n"
    },
  • "metadata": {
    • "command": "generate_mobileconfig",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Repair misconfigured email settings

This function fixes a user's misconfigured email settings. This includes any misconfigured email file and directory ownership and permissions.

Authorizations:
BasicAuth
query Parameters
username
required
string
Example: username=username

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  normalize_user_email_configuration \
  username='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "normalize_user_email_configuration",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Repair Exim configuration file

This function scans the Exim configuration file for errors, and if it finds errors attempts to repair them.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  exim_configuration_check

Response samples

Content type
application/json
{
  • "data": {
    • "message": "cPanel was unable to automatically merge your Exim configuration with the new settings that shipped\nwith the build you have installed (11.38.0 (build 9999)) because you have a custom or broken configuration which\ncannot be automatically configured.\n Since this configuration update is not critical, we left your previous configuration intact until\nthe new configuration can be properly installed. In order to complete this configuration update, you will \nneed to manually merge your configuration with the new configuration settings.\n\n\nPlease follow the steps below to complete this update:\n\n\t1. <a href='javascript:select_exim_backup();'>Backup your existing configuration</a>\n\t2. <a href='javascript:select_exim_advanced();'>Notate any custom changes you have made in the ACL section in the 'Advanced Editor Tab'.</a>\n\t3. <a href='javascript:select_exim_reset();'>Choose 'Reset cPanel & WHM Exim configuration files, one option at a time, until the installed Exim configuration is valid' under the 'Reset Tab'.</a>\n\t4. <a href='javascript:select_exim_advanced();'>Reinstall your customizations in the 'Advanced Editor Tab'.</a>\n\n\nCurrent Config Version: 10.320000\nNew Config Version: 10.330000"
    },
  • "metadata": {
    • "command": "exim_configuration_check",
    • "reason": "Configuration Update Failed",
    • "result": 1,
    • "version": 1
    }
}

Return server mail queue contents

This function retrieves the contents of the server's mail queue.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_mail_queue

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "fetch_mail_queue",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove Exim configuration files after failed update

This function removes in-progress Exim configuration files after a failed update to Exim. When cPanel & WHM attempts to update an Exim configuration, the system creates dry run files to replace of the ordinary configuration files.

Note:

  • If the update fails, the system leaves these dry run files in place.
  • When the user accesses the Advanced Editor section of WHM's Exim Configuration Manager interface (Home >> Service Configuration >> Exim Configuration Manager), they access these dry run files instead of the actual configuration files.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_in_progress_exim_config_edit

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "remove_in_progress_exim_config_edit",
    • "reason": "Removed OK",
    • "result": 1,
    • "version": 1
    }
}

Validate Exim configuration

This function validates the system's current Exim configuration.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_current_installed_exim_config

Response samples

Content type
application/json
{
  • "data": {
    • "message": "<pre>Doing Dry Run\nDry Run ok\nEnabled system filter options: attachments| fail_spam_score_over_int|spam_rewrite\nEnabled ACL options in block ACL_MAIL_PRE_BLOCK: default_mail_pre\nEnabled ACL options in block ACL_RBL_BLOCK: primary_hostname_bl\n Enabled ACL options in block ACL_RECIPIENT_POST_BLOCK: default_recipient_post\nEnabled ACL options in block ACL_SPAM_SCAN_CHECK_BLOCK: default_spam_scan_check\nEnabled ACL options in block ACL_CHECK_MESSAGE_PRE_BLOCK: default_check_message_pre \nEnabled ACL options in block ACL_CONNECT_POST_BLOCK: default_connect_post \nEnabled ACL options in block ACL_CONNECT_BLOCK: ratelimit|spammerlist \nEnabled ACL options in block ACL_POST_RECP_VERIFY_BLOCK: dictionary_attack\nEnabled ACL options in block ACL_IDENTIFY_SENDER_BLOCK: default_identify_sender\nEnabled ACL options in block ACL_MAIL_BLOCK: requirehelo| requirehelonoforge|requirehelosyntax\nEnabled ACL options in block ACL_RATELIMIT_SPAM_BLOCK: ratelimit_spam_score_over_int\nEnabled ACL options in block ACL_CHECK_MESSAGE_POST_BLOCK: default_check_message_post\nEnabled ACL options in block ACL_POST_SPAM_SCAN_CHECK_BLOCK: mailproviders \nEnabled ACL options in block ACL_SPAM_SCAN_BLOCK: default_spam_scan \nEnabled ACL options in block ACL_RATELIMIT_BLOCK: 0tracksenders\nEnabled ACL options in block ACL_NOTQUIT_BLOCK: ratelimit\nEnabled ACL options in block ACL_RECP_VERIFY_BLOCK: default_recp_verify\nEnabled ACL options in block ACL_PRE_SPAM_SCAN: mailproviders\nEnabled ACL options in block ACL_SPAM_BLOCK: deny_spam_score_over_int\nEnabled ACL options in block ACL_EXISCAN_BLOCK: default_exiscan\nEnabled ACL options in block ACL_RECIPIENT_BLOCK: default_recipient\nEnabled ACL options in block ACL_MAIL_POST_BLOCK: default_mail_post\nThe system detected spam handling in acls and will now disable Apache SpamAssassin in routers and transports!\nThe Apache SpamAssassin method remains unchanged.\nConfigured options list is:\nACL: acl_smtp_connect is active\nACL: acl_smtp_data is active\nACL: acl_smtp_mail is active\nACL: acl_smtp_notquit is active\nACL: acl_smtp_rcpt is active\nProvided options list is: daemon_smtp_ports| tls_on_connect_ports|system_filter_user|system_filter_group|tls_require_ciphers|hostlist loopback|hostlist senderverifybypass_hosts|hostlist skipsmtpcheck_hosts|hostlist spammeripblocks|hostlist backupmx_hosts|hostlist trustedmailhosts|hostlist relay_hosts| domainlist user_domains|remote_max_parallel|smtp_receive_timeout| ignore_bounce_errors_after|rfc1413_query_timeout|timeout_frozen_after|auto_thaw| callout_domain_negative_expire|callout_negative_expire|acl_smtp_connect| acl_smtp_data|acl_smtp_mail|acl_smtp_notquit|acl_smtp_rcpt|perl_at_start| daemon_smtp_ports|tls_on_connect_ports|system_filter_user|system_filter_ group|tls_require_ciphers|spamd_address\nExim Insert Regex is: virtual_userdelivery| virtual_aliases|lookuphost|virtual_user|address_pipe|virtual_sa_user|localuser\nExim Replace Regex is: virtual_sa_user|sa_localuser|virtual_sa_userdelivery| local_sa_delivery|central_filter|central_user_filter|democheck|fail_remote_domains| fixed_login|fixed_plain|has_alias_but_no_mailbox_discarded_to_prevent_loop|literal| local_delivery|local_delivery_spam|localuser|localuser_spam|lookuphost|remote_smtp| secure_login|secure_plain|userforward|virtual_aliases|virtual_aliases_nostar| virtual_user|virtual_user_spam|virtual_userdelivery|virtual_userdelivery_spam\nExim Match Insert Regex is: quota_directory|maildir_format\nExim version 4.76 #1 built 16- Aug-2011 11:41:07\nCopyright (c) University of Cambridge, 1995 - 2007\nBerkeley DB: Sleepycat Software: Berkeley DB 4.3.29: (July 12, 2010)\nSupport for: crypteq iconv() IPv6 PAM Perl OpenSSL Content_Scanning DKIM Old_Demime Experimental_SPF Experimental_SRS\nLookups (built-in): lsearch wildlsearch nwildlsearch iplsearch dbm dbmnz passwd\nAuthenticators: cram_md5 dovecot plaintext spa\nRouters: accept dnslookup ipliteral manualroute queryprogram redirect\nTransports: appendfile/maildir autoreply pipe smtp\nSize of off_t: 8\n\n</pre>"
    },
  • "metadata": {
    • "command": "validate_current_installed_exim_config",
    • "reason": "Your configuration is currently valid.",
    • "result": 1,
    • "version": 1
    }
}

Validate Exim configure file syntax

This function evaluates and validates an Exim configuration file's syntax.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.
Authorizations:
BasicAuth
query Parameters
cfg_text
string <HTML>
Example: cfg_text=RAW_CONFIGURATION_TEXT

The Exim configuration file's raw text.

Note:

If you do not use this parameter, the function will analyze Exim's current configuration.

section
string
Example: section=acl

The Exim configuration file's section to check.

Note:

If you use this parameter, pass only the desired section to validate as the cfg_text value.

Responses

Response Schema: application/json
object or object

An object containing a valid or invalid Exim configuration information.

object

Request samples 

whmapi1 --output=jsonpretty \
  validate_exim_configuration_syntax

Response samples

Content type
application/json
Example
{
  • "command": "validate_exim_configuration_syntax",
  • "data": {
    • "broken_cfg_html": "RAW_CONFIGURATION_TEXT",
    • "broken_cfg_text": "==>RAW_CONFIGURATION_TEXT<==\n",
    • "error_line": 1,
    • "error_msg": "This is an error message."
    },
  • "output": {
    • "raw": "\n"
    },
  • "reason": "OK",
  • "result": 1,
  • "version": 1
}

Return server SNI support status

This function checks whether the server supports SNI (Server Name Indication).

Note:

  • Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled.
  • Functions that disable Mail SNI fail and make no changes.
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  is_sni_supported

Response samples

Content type
application/json
{
  • "data": {
    • "sni": 1
    },
  • "metadata": {
    • "command": "is_sni_supported",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain's SNI mail services status

This function retrieves the status of the domain's SNI mail services.

Note:

Functions that disable Mail SNI fail and make no changes.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Example: domain=example.com

The account's domain.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  mail_sni_status \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "enabled": 1
    },
  • "metadata": {
    • "command": "mail_sni_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Rebuild mail SNI configuration files

This function rebuilds the mail SNI configuration files.

Authorizations:
BasicAuth
query Parameters
reload_dovecot
integer
Default: 0
Possible Values: 0 1
Example: reload_dovecot=1

Whether to reload the Dovecot service after the system rebuilds the configuration files.

  • 1 - Reload Dovecot.
  • 0 - Do not reload Dovecot.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  rebuild_mail_sni_config

Response samples

Content type
application/json
{
  • "data": {
    • "configs_built": [
      • "/etc/dovecot/sni.conf"
      ],
    • "success": 1
    },
  • "metadata": {
    • "command": "rebuild_mail_sni_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Spam Management

Mail / Spam Management

Add block on emails from specific countries

This function blocks email from specific countries.

Authorizations:
BasicAuth
query Parameters
country_code
required
string
Examples:
  • country_code=country_code-1=AA country_code-2=AB country_code-3=AC - Multiple country codes.
  • country_code=AA - A single country code.

The country to block. The ISO 3166-1 alpha-2 code two-letter country code.

Warning:

Do not block the ZZ country code if the server uses a NAT configuration.

Note:

  • To search all available country codes, read the ISO's Full list of Country Codes documentation.
  • To block multiple countries, duplicate or increment the parameter name. For example: country_code-1, country_code-2, and country_code-3.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  block_incoming_email_from_country \
  country_code='AA'

Response samples

Content type
application/json
{
  • "data": {
    • "updated": 1
    },
  • "metadata": {
    • "command": "block_incoming_email_from_country",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add block on emails from specific domains

This function blocks email from specific domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example.com domain-1=example1.com domain-2=example2.com - Multiple domains.
  • domain=domain=example.com domain=example1.com domain=example2.com - Multiple domains.
  • domain=example.com - A single domain.

The domain to block.

Note:

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  block_incoming_email_from_domain \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "updated": 1
    },
  • "metadata": {
    • "command": "block_incoming_email_from_domain",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return blocked email countries list

This function lists which countries cannot send email to the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_blocked_incoming_email_countries

Response samples

Content type
application/json
{
  • "data": {
    • "countries": [
      • {
        • "country_code": "AD"
        }
      ]
    },
  • "metadata": {
    • "command": "list_blocked_incoming_email_countries",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return blocked email domains list

This function lists which domains cannot send email to the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_blocked_incoming_email_domains

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • {
        • "domain": "example.com"
        }
      ]
    },
  • "metadata": {
    • "command": "list_blocked_incoming_email_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove block on emails from specific countries

This function unblocks email from specific countries.

Authorizations:
BasicAuth
query Parameters
country_code
string
Examples:
  • country_code=country_code=US&country_code=AD - To unblock multiple country codes.
  • country_code=country_code=US&country_code-1=AD&country_code-2=ES - To unblock multiple country codes using index parameters.
  • country_code=US - To unblock one country code.

The country to unblock. A valid ISO 3166-1 alpha-2 code two-letter country code.

Note:

  • To search all available country codes, read the ISO's Full list of Country Codes documentation.
  • To unblock multiple countries, duplicate or increment the parameter name. For example, to unblock three countries, you could:
    • Use the country_code parameter multiple times.
    • Use the country_code, country_code-1, and country_code-2 parameters.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  unblock_incoming_email_from_country

Response samples

Content type
application/json
{
  • "data": {
    • "updated": 1
    },
  • "metadata": {
    • "command": "unblock_incoming_email_from_country",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove block on emails from specific domains

This function unblocks email from specific domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example.com domain-1=example1.com domain-2=example2.com - Multiple domains.
  • domain=domain=example.com domain=example1.com domain=example2.com - Multiple domains.
  • domain=example.com - A single domain.

The domain to unblock.

Note:

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  unblock_incoming_email_from_domain \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "updated": 1
    },
  • "metadata": {
    • "command": "unblock_incoming_email_from_domain",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Apache SpamAssassin™ configuration

This function configures your Apache SpamAssassin™ options.

Important:

When you disable the Spam Filter role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
allowedips
string
Example: allowedips=127.0.0.1,192.168.0.1

A comma-separated list of IP addresses to authorize to access the spamd daemon.

Note:

  • If you do not specify a value, the spamd daemon allows connections from any IP address.
  • If you set a value for this parameter, it must include 127.0.0.1 in the list of values so that the chkservd daemon can access the spamd daemon.
maxchildren
integer >= 1
Example: maxchildren=5

The maximum number of children per spamd process.

maxconnperchild
integer >= 1
Example: maxconnperchild=200

The maximum number of connections that the spamd daemon allows per child process.

pidfile
string
Example: pidfile=/var/run/spamd.pid

The process ID's file path.

Warning:

This parameter changes the spamd daemon's process ID filepath. On systems that use the systemd daemon, you must update the PIDFile parameter in the spamd.service definition. If you do not update the PIDFile parameter, the spamd daemon will fail to function because the PID path and the PIDFile parameter will not match.

timeoutchild
integer >= 0
Example: timeoutchild=300

The maximum amount of time that a child process waits before it abandons a TCP connection.

Note:

If the value of this parameter is 0, child processes will not abandon TCP connections.

timeouttcp
integer >= 0
Example: timeouttcp=30

The maximum amount of time that the spamd daemon waits before it abandons a TCP connection.

Note:

If the value of this parameter is 0, spamd will not abandon TCP connections.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  save_spamd_config

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "save_spamd_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Spam Protection (Greylisting)

Mail / Spam Protection (Greylisting)

Remove IP address from Greylisting trusted hosts

This function deletes an IP address from the Greylisting Trusted Hosts list.

Authorizations:
BasicAuth
query Parameters
ip
required
string
Examples:
  • ip=192.168.0.1/16 - CIDR Format IPv4
  • ip=2001:db8::/32 - CIDR Format IPv6
  • ip=ip-1=192.168.0.1&ip-2=192.168.0.2&ip-3=192.168.0.3 - Multiple IP addresses.
  • ip=192.168.0.1 - A single IP address.
  • ip=192.0.2.0 - Single IPv4 Address
  • ip=2001:db8::1 - Single IPv6 Address

The record's IP address, or a range of IP addresses.

Note:

To add multiple IP addresses, increment the parameter name (for example, ip-1, ip-2, ip-3).

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_cpgreylist_trusted_host \
  ip='192.168.0.1'

Response samples

Content type
application/json
{
  • "data": {
    • "ips_failed": {
      • "5.5": "Invalid IP address or range: “5.5”"
      },
    • "ips_removed": [
      • "192.168.0.1",
      • "2001:db8::1"
      ]
    },
  • "metadata": {
    • "command": "delete_cpgreylist_trusted_host",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add IP address to Greylisting trusted hosts

This function adds an IP address to the Greylisting Trusted Hosts list.

Authorizations:
BasicAuth
query Parameters
comment
string <= 255 characters
Example: comment=NoComment

A comment.

ip
required
string
Examples:
  • ip=ip-1=192.168.0.1&ip-2=192.168.0.2&ip-3=192.168.0.3 - To add multiple IP addresses.
  • ip=192.168.0.1 - To add a single IP address.

The record's IP address, or a range of IP addresses.

Note:

To add multiple IP addresses, increment the parameter name. For example, ip-1, ip-2, and ip-3.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_cpgreylist_trusted_host \
  ip='192.168.0.1'

Response samples

Content type
application/json
{
  • "data": {
    • "comment": "NoComment",
    • "ips_added": [
      • {
        • "comment": "Fascinating",
        • "create_time": "2015-02-17T10:08:26.000Z",
        • "host_ip": "192.168.0.1",
        • "id": 42
        }
      ],
    • "ips_failed": {
      • "comment": "Sorry, 192.168 is not a valid IP address."
      }
    },
  • "metadata": {
    • "command": "create_cpgreylist_trusted_host",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting trust status of server netblock

This function returns the Greylisting trusted status of the server's netblock.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_is_server_netblock_trusted

Response samples

Content type
application/json
{
  • "data": {
    • "ip_blocks": {
      • "10.0.0.0-10.255.255.255": 1,
      • "199.0.0.0-199.3.255.255": 1,
      • "48.0.0.0-48.255.255.255": 1
      }
    },
  • "metadata": {
    • "command": "cpgreylist_is_server_netblock_trusted",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting IP addresses of mail providers

This function lists Greylisting's IP addresses for the specified mail provider.

Authorizations:
BasicAuth
query Parameters
provider
required
string
Examples:
  • provider=provider-0=example-0 provider-1=example-1 provider-2=example-2 - List multiple mail provider entries.
  • provider=cpanel - List a single mail provider entry.

The mail provider.

Note:

  • To list entries for multiple mail providers, increment the parameter name. For example, provider-0, provider-1, and provider-2.
  • Call WHM API 1's cpgreylist_load_common_mail_providers_config function to return a list of valid provider keys.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_list_entries_for_common_mail_provider \
  provider='cpanel'

Response samples

Content type
application/json
{
  • "data": {
    • "providers": {
      • "cpanel": {
        • "ips": [
          • {
            • "create_time": "2015-07-28T08:16:52",
            • "host_ip": "208.115.214.0-208.115.214.255",
            • "is_trusted": 1,
            • "provider_id": 7
            },
          • {
            • "create_time": "2015-07-28T08:16:52",
            • "host_ip": "74.63.202.0-74.63.202.255",
            • "is_trusted": 1,
            • "provider_id": 7
            }
          ]
        }
      },
    • "providers_failed": {
      • "dpanel": "Unknown mail provider: dpanel"
      }
    },
  • "metadata": {
    • "command": "cpgreylist_list_entries_for_common_mail_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting mail providers

This function returns Greylisting's list of common mail service providers.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_load_common_mail_providers_config

Response samples

Content type
application/json
{
  • "data": {
    • "autotrust_new_common_mail_providers": 1,
    • "common_mail_providers": {
      • "cpanel": {
        • "autoupdate": 1,
        • "display_name": "cPanel",
        • "is_trusted": 1
        },
      • "sectigo": {
        • "autoupdate": 1,
        • "display_name": "Comodo/Sectigo",
        • "is_trusted": 1
        }
      }
    },
  • "metadata": {
    • "command": "cpgreylist_load_common_mail_providers_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Greylisting new mail provider handling

This function sets whether Greylisting trusts new entries to cPanel's common mail providers list.

Authorizations:
BasicAuth
query Parameters
autotrust_new_common_mail_providers
integer
Default: 1
Possible Values: 0 1
Example: autotrust_new_common_mail_providers=1

Whether Greylisting automatically trusts new mail providers that cPanel adds to the common mail providers list.

  • 1 — Automatically trust new mail providers cPanel adds to the common mail providers list.
  • 0 — Do not automatically trust new mail providers cPanel adds to the common mail providers list.
PROVIDERKEY
integer
Possible Values: 0 1
Example: PROVIDERKEY=0

Whether Greylisting automatically trusts new IP addresses that cPanel adds to this mail provider.

  • 1 — Automatically trust new IP addresses cPanel adds to this mail provider.
  • 0 — Do not automatically trust new IP addresses cPanel adds to this mail provider.

If you do not specify this parameter, the system will not change Greylisting settings for any existing provider.

Note:

The parameter's name is the provider's key name. Example key and value:

  • google=0

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_save_common_mail_providers_config

Response samples

Content type
application/json
{
  • "data": {
    • "autotrust_new_common_mail_providers": 1,
    • "common_mail_providers": {
      • "cpanel": {
        • "autoupdate": 1,
        • "display_name": "cPanel",
        • "is_trusted": 1
        },
      • "sectigo": {
        • "autoupdate": 1,
        • "display_name": "Comodo/Sectigo",
        • "is_trusted": 1
        }
      }
    },
  • "metadata": {
    • "command": "cpgreylist_load_common_mail_providers_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting status

This function returns the status of Greylisting.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_status

Response samples

Content type
application/json
{
  • "data": {
    • "is_enabled": 1,
    • "is_exim_enabled": 1,
    • "service": "cPGreyList"
    },
  • "metadata": {
    • "command": "cpgreylist_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add mail provider to Greylisting trusted hosts

This function marks the IP addresses for the specified mail provider as trusted. Greylisting will not defer emails from trusted IP addresses.

Authorizations:
BasicAuth
query Parameters
provider
required
string
Examples:
  • provider=provider-1=cpanel&provider-2=google - Trust multiple mail providers.
  • provider=cpanel - Trust a single mail provider.

The mail providers’ names.

Call the cpgreylist_load_common_mail_providers_config API function to retrieve the system’s recognized provider names.

Note:

To trust multiple mail providers, increment the parameter name (for example: provider-0, provider-1, and provider-2).

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_trust_entries_for_common_mail_provider \
  provider='cpanel'

Response samples

Content type
application/json
{
  • "data": {
    • "providers_failed": {
      • "property1": "This failed because it rained.",
      • "property2": "This failed because it rained."
      },
    • "providers_trusted": {
      • "property1": {
        • "ips_trusted": 21
        },
      • "property2": {
        • "ips_trusted": 21
        }
      }
    },
  • "metadata": {
    • "command": "cpgreylist_trust_entries_for_common_mail_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable Greylisting

This function disables Greylisting.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_cpgreylist

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "disable_cpgreylist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add mail provider to Greylisting non-trusted hosts

This function marks the IP addresses for the specified mail provider as not trusted. Greylisting defers emails from non-trusted IP addresses.

Authorizations:
BasicAuth
query Parameters
provider
required
string
Examples:
  • provider=provider-1=10 provider-2=33 provider-3=15 - Trust multiple mail providers
  • provider=1 - Trust a single mail provider

The mail provider.

Note:

To trust multiple mail providers, increment the parameter name. For example, provider-0, provider-1, provider-2.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  cpgreylist_untrust_entries_for_common_mail_provider \
  provider='1'

Response samples

Content type
application/json
{
  • "data": {
    • "providers_failed": {
      • "provider_key1": {
        • "ips_untrusted": 21
        },
      • "provider_key2": {
        • "ips_untrusted": 21
        }
      },
    • "providers_untrusted": {
      • "provider_key1": "Unknown mail provider.",
      • "provider_key2": "Unknown mail provider."
      }
    },
  • "metadata": {
    • "command": "cpgreylist_untrust_entries_for_common_mail_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Greylisting settings

This function modifies the server's Greylisting configuration settings.

Important:

When you call this function, you must include at least one of the following parameters:

  • spf_bypass
  • child_timeout_secs
  • record_exp_time_mins
  • initial_block_time_mins
  • max_child_procs
  • purge_interval_mins
  • must_try_time_mins
Authorizations:
BasicAuth
query Parameters
child_timeout_secs
integer >= 1
Example: child_timeout_secs=5

The maximum of seconds that Greylisting waits for a child process to timeout.

Note:

This parameter affects the function of the cPGreyList daemon. Do not change this value unless it is absolutely necessary.

initial_block_time_mins
integer [ 1 .. 240 ]
Example: initial_block_time_mins=10

The number of minutes during which Greylisting defers email from an unknown triplet. The maximum value for this parameter is four hours (240 minutes).

max_child_procs
integer >= 1
Example: max_child_procs=5

The maximum number of child processes.

Notes:

This parameter affects the function of the cPGreyList daemon. Do not change this value unless it is absolutely necessary.

must_try_time_mins
integer [ 1 .. 1440 ]
Example: must_try_time_mins=240

The number of minutes during which Greylisting accepts a re-sent email from an unknown triplet. The maximum value for this parameter is one day (1440 minutes).

purge_interval_mins
integer >= 1
Example: purge_interval_mins=60

The number of minutes before Greylisting deletes the records in the Greylisting database.

Note:

This parameter affects the function of the cPGreyList daemon. Do not change this value unless it is absolutely necessary.

record_exp_time_mins
integer [ 1 .. 43200 ]
Example: record_exp_time_mins=4320

The number of minutes before Greylisting deletes the triplet record and treats a re-sent email as coming from a new, unknown triplet. The maximum value for this parameter is 30 days (43200 minutes).

spf_bypass
integer
Possible Values: 1 0
Example: spf_bypass=1

Whether emails with SPF bypass Greylisting.

  • 1 — Enabled.
  • 0 — Disabled.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  save_cpgreylist_config

Response samples

Content type
application/json
{
  • "data": {
    • "cpgreylist_config": {
      • "child_timeout_secs": 5,
      • "initial_block_time_mins": 10,
      • "is_enabled": 1,
      • "is_exim_enabled": 1,
      • "max_child_procs": 5,
      • "must_try_time_mins": 240,
      • "purge_interval_mins": 60,
      • "record_exp_time_mins": 4320,
      • "spf_bypass": 1
      }
    },
  • "metadata": {
    • "command": "save_cpgreylist_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting settings

This function returns Greylisting's current settings.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  load_cpgreylist_config

Response samples

Content type
application/json
{
  • "data": {
    • "cpgreylist_config": {
      • "child_timeout_secs": 5,
      • "initial_block_time_mins": 10,
      • "is_enabled": 1,
      • "is_exim_enabled": 1,
      • "max_child_procs": 5,
      • "must_try_time_mins": 240,
      • "purge_interval_mins": 60,
      • "record_exp_time_mins": 4320,
      • "spf_bypass": 1
      }
    },
  • "metadata": {
    • "command": "load_cpgreylist_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable Greylisting

This function enables Greylisting.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_cpgreylist

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "enable_cpgreylist",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting deferred incoming email triplets

This function lists Greylisting's deferred triplets. Greylisting identifies incoming email by triplets.

A triplet is a collection of three pieces of data:

  • the IP address
  • the sender's address
  • the recipient's address
Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  read_cpgreylist_deferred_entries

Response samples

Content type
application/json
{
  • "data": {
    • "greylist_deferred_entries": [
      • {
        • "accepted_count": 0,
        • "block_exp_time": "2015-03-23T12:09:32.000Z",
        • "create_time": "2015-03-23T11:59:32.000Z",
        • "deferred_count": 1,
        • "from_addr": "[email protected]",
        • "id": 45,
        • "must_retry_by": "2015-03-23T15:59:32.000Z",
        • "record_exp_time": "2015-03-26T11:59:32.000Z",
        • "sender_ip": "97.215.255.29",
        • "to_addr": "[email protected]"
        }
      ],
    • "limit": 20,
    • "offset": 20,
    • "server_timezone": "CDT",
    • "server_tzoffset": 60,
    • "total_rows": 3
    },
  • "metadata": {
    • "command": "read_cpgreylist_deferred_entries",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Greylisting trusted hosts

This function retrieves the entries on the Greylisting Trusted Hosts list.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  read_cpgreylist_trusted_hosts

Response samples

Content type
application/json
{
  • "data": {
    • "greylist_trusted_hosts": [
      • {
        • "comment": "Example",
        • "create_time": "2015-03-24T10:22:38.000Z",
        • "host_ip": "192.0.2.0",
        • "id": 19
        }
      ]
    },
  • "metadata": {
    • "command": "read_cpgreylist_trusted_hosts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

NGINX Manager

The NGINX Manager module for WHM API 1.

Delete the user's NGINX cache.

This function clears a user's NGINX cache

Authorizations:
BasicAuth
query Parameters
user
Array of strings <username> [ items <username > ]
Default: ""
Example: user=unclebob&user=auntsue

A list of users whose cache you want to clear.

Note:

If you do not pass this parameter, this function clears the cache for all users.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  nginxmanager_clear_cache

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "nginxmanager_clear_cache",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return user NGINX caching configurations.

This function returns a user's NGINX cache configuration.

Authorizations:
BasicAuth
query Parameters
merge
integer
Value: 1
Example: merge=1

Combine default, system, and user NGINX configurations when returning configuration data.

Note:

  • 1 - Return the configuration with default, system, and user values combined.
user
Array of strings <username> [ items <username > ]
Default: ""
Example: user=unclebob&user=auntsue

A list of users whose cache configuration you want to retrieve.

Note:

If you do not pass this parameter, this function retrieves the cache configuration for all users.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  nginxmanager_get_cache_config_users

Response samples

Content type
application/json
{
  • "data": {
    • "users": [
      • {
        • "config": {
          • "enabled": true,
          • "inactive_time": "60m",
          • "levels": "1:2",
          • "logging": false,
          • "proxy_cache_background_update": "on",
          • "proxy_cache_lock": "on",
          • "proxy_cache_min_uses": 1,
          • "proxy_cache_revalidate": "on",
          • "proxy_cache_use_stale": "error timeout http_429 http_500 http_502 http_503 http_504",
          • "x_cache_header": false,
          • "zone_size": "10m"
          },
        • "merged": 0,
        • "owner": "root",
        • "user": "cptest1"
        },
      • {
        • "config": {
          • "enabled": true,
          • "inactive_time": "60m",
          • "levels": "1:2",
          • "logging": false,
          • "proxy_cache_background_update": "on",
          • "proxy_cache_lock": "on",
          • "proxy_cache_min_uses": 1,
          • "proxy_cache_revalidate": "on",
          • "proxy_cache_use_stale": "error timeout http_429 http_500 http_502 http_503 http_504",
          • "x_cache_header": false,
          • "zone_size": "10m"
          },
        • "merged": 0,
        • "owner": "root",
        • "user": "cptest2"
        }
      ]
    },
  • "metadata": {
    • "command": "nginxmanager_set_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update NGINX caching status.

This function enables or disables NGINX caching.

Authorizations:
BasicAuth
query Parameters
enabled
required
integer
Possible Values: 1 0
Example: enabled=1

Whether to enable to disable caching.

Note:

  • 1 - Enables caching.
  • 0 - Disables caching.
user
Array of strings <username> [ items <username > ]
Default: ""
Example: user=unclebob&user=auntsue

A list of users whose caching you want to enable or disable.

Note:

If you do not pass this parameter, this function sets the caching status for all users on the system.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  nginxmanager_set_cache_config \
  enabled='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "nginxmanager_set_cache_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return NGINX caching configurations.

This function returns the system NGINX cache configuration.

Authorizations:
BasicAuth
query Parameters
merge
integer
Value: 1
Example: merge=1

Whether to combine the default and system NGINX configurations when returning configuration data.

Note:

  • 1 - Return the configuration with default and system values combined.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  nginxmanager_get_cache_config_system

Response samples

Content type
application/json
{
  • "data": {
    • "default": {
      • "enabled": 1,
      • "inactive_time": "60m",
      • "levels": "1:2",
      • "logging": 0,
      • "proxy_cache_background_update": "on",
      • "proxy_cache_lock": "on",
      • "proxy_cache_min_uses": 1,
      • "proxy_cache_revalidate": "on",
      • "proxy_cache_use_stale": "error timeout http_429 http_500 http_502 http_503 http_504",
      • "x_cache_header": 0,
      • "zone_size": "10m"
      },
    • "system": {
      • "enabled": true,
      • "inactive_time": "60m",
      • "levels": "1:2",
      • "logging": false,
      • "proxy_cache_background_update": "on",
      • "proxy_cache_lock": "on",
      • "proxy_cache_min_uses": 1,
      • "proxy_cache_revalidate": "on",
      • "proxy_cache_use_stale": "error timeout http_429 http_500 http_502 http_503 http_504",
      • "x_cache_header": 0,
      • "zone_size": "10m"
      }
    },
  • "metadata": {
    • "command": "nginxmanager_set_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update NGINX configuration.

This function rebuilds the NGINX user configuration.

Authorizations:
BasicAuth
query Parameters
user
Array of strings <username> [ items <username > ]
Default: ""
Example: user=unclebob&user=auntsue

A list of users whose configuration you want to rebuild.

Note:

If you do not pass this parameter, this function rebuilds the configuration for all users on the system.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  nginxmanager_rebuild_cache_config

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "nginxmanager_rebuild_cache_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore NGINX configuration to default values.

This function resets a user to the NGINX system default.

Authorizations:
BasicAuth
query Parameters
user
Array of strings <username> [ items <username > ]
Default: ""
Example: user=unclebob&user=auntsue

A list of users to reset to the NGINX system default.

Note:

If you do not pass this parameter, this function resets the configuration to the default for all users on the system.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  nginxmanager_reset_users_cache_config

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "nginxmanager_reset_users_cache_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

RemoteStorage

RemoteStorage

Account Enhancement Limit

Resellers / Account Enhancement Limit

Return account enhancement limits

This function returns a reseller's account enhancement limits.

Authorizations:
BasicAuth
query Parameters
account
required
string <username>
Example: account=username

The reseller's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_enhancement_limits \
  account='username'

Response samples

Content type
application/json
{
  • "data": {
    • "limits": {
      • "enhancement_id1": {
        • "limit": 15,
        • "limited": 1,
        • "usage": 15
        },
      • "enhancement_id2": {
        • "limit": 15,
        • "limited": 1,
        • "usage": 15
        }
      }
    },
  • "metadata": {
    • "command": "list_enhancement_limits",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update account enhancement limit

This function sets account enhancement limits for a reseller account.

Authorizations:
BasicAuth
query Parameters
account
required
string <username>
Example: account=username

The reseller's username.

id
required
string
Example: id=sample-enhancement-id

The account enhancement's identifier.

Note:

  • You must use an account enhancement ID that a 3rd-party plugin defines.
  • To return a list of valid account enhancement IDs, run the WHM API 1 list_account_enhancements function.
limit
integer
Example: limit=15

The account enhancement limit amount. This parameter is only required if the limited parameter is 1.

limited
required
integer
Possible Values: 1 0
Example: limited=1

Whether the Account Enhancement assignment limit is unlimited.

  • 0 - The assignment is unlimited.
  • 1 - The assignment is limited.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_enhancement_limit \
  account='username' \
  id='sample-enhancement-id' \
  limited='1' \
  limit='15'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_enhancement_limit",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Account Limits

Resellers / Account Limits

Update reseller's hosting plan limits

This function limits the packages that a reseller assigns to cPanel accounts.

Authorizations:
BasicAuth
query Parameters
allowed
integer
Possible Values: 0 1
Example: allowed=1

Whether the reseller can access the package hosting plan.

  • 1 — Enable access.
  • 0 — Disable access

Note:

If you use this parameter, you must also include the package parameter.

no_limit
integer
Default: 0
Possible Values: 0 1
Example: no_limit=0

Whether to grant the reseller unlimited package use.

  • 1 — Grant the reseller unlimited package use.
  • 0 — Use package limits.
number
integer >= 1
Example: number=5

The maximum number of accounts to which the reseller can assign the package hosting plan.

Note:

  • If you use this parameter, you must also include the package parameter.
  • If you set a value for this parameter and set the allowed parameter to 0, the reseller cannot use the hosting plan.
package
string
Example: package=package1

A hosting plan (package), to modify the reseller's access settings for it.

Note:

Use this parameter with the number or allowed parameters.

user
required
string <username>
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setresellerpackagelimit \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setresellerpackagelimit",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update reseller's bandwidth and disk quotas

This function sets a reseller's bandwidth and disk quotas.

Authorizations:
BasicAuth
query Parameters
account_limit
integer >= 1
Example: account_limit=10

The reseller's maximum total number of accounts.

Important:

The system only enforces this maximum if you set the enable_account_limit value to 1.

bandwidth_limit
integer <megabytes> >= 0
Example: bandwidth_limit=1073741824

The reseller's total bandwidth limit.

Important:

The system only enforces this limit if you set the enable_resource_limits value to 1.

diskspace_limit
integer <megabytes> >= 0
Example: diskspace_limit=1073741824

The reseller's total disk space usage limit.

Important:

The system only enforces this limit if you set the enable_resource_limits value to 1.

enable_account_limit
integer
Default: 0
Possible Values: 1 0
Example: enable_account_limit=0

Whether to limit the reseller's total number of accounts.

  • 1 — Limit.
  • 0 — Do not limit.

Note:

Use this parameter with the account_limit parameter.

enable_overselling
integer
Possible Values: 1 0
Example: enable_overselling=1

Whether the reseller can oversell accounts.

  • 1 — The reseller can oversell accounts.
  • 0 — The reseller cannot oversell accounts.

Important:

The system only enforces this limit if you set the enable_resource_limits value to 1.

enable_overselling_bandwidth
integer
Possible Values: 1 0
Example: enable_overselling_bandwidth=1

Whether the reseller can oversell bandwidth.

  • 1 — The reseller can oversell bandwidth.
  • 0 — The reseller cannot oversell bandwidth.

Important:

The system only enforces this limit if you set the enable_resource_limits and the enable_overselling values to 1.

enable_overselling_diskspace
integer
Possible Values: 1 0
Example: enable_overselling_diskspace=1

Whether the reseller can oversell disk space.

  • 1 — The reseller can oversell disk space.
  • 0 — The reseller cannot oversell disk space.

Important:

The system only enforces this limit if you set the enable_resource_limits and the enable_oversellng values to 1.

enable_package_limit_numbers
integer
Possible Values: 1 0
Example: enable_package_limit_numbers=0

Whether to apply package limit numbers to the reseller.

  • 1 — Enable package limit numbers.
  • 0 — Disable package limit numbers.
enable_package_limits
integer
Possible Values: 1 0
Example: enable_package_limits=0

Whether to apply package limits to the reseller.

  • 1 — Enable package limits.
  • 0 — Disable package limits.
enable_resource_limits
integer
Default: 0
Possible Values: 1 0
Example: enable_resource_limits=1

Whether to limit the reseller's resources.

  • 1 — Limit resources.
  • 0 — Do not limit resources.

Note:

Use this parameter with the bandwidthlimit, diskspace_limit, enable_overselling, enable_overselling_bandwidth, enable_overselling_diskspace, enable_overselling, enable_package_limits, and enable_package_limit_numbers parameters.

user
required
string <username>
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setresellerlimits \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setresellerlimits",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Account Permissions

Resellers / Account Permissions

Create or update reseller privilege settings

This function creates or modifies an Access Control List (ACL).

Note:

For each acl-* parameter, any value adds that privilege to the ACL list and no value removes that privilege from the ACL list.

Warning:

We strongly recommend that WHM users create and edit ACLs and ACL privileges through WHM's Edit Reseller Nameservers and Privileges interface ( WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges ).

Authorizations:
BasicAuth
query Parameters
acl-acct-summary
integer
Value: 1
Example: acl-acct-summary=1

Whether to allow the reseller to view an account summary.

acl-add-pkg
integer
Value: 1
Example: acl-add-pkg=1

Whether to allow the reseller to add and remove hosting plans (packages).

acl-add-pkg-ip
integer
Value: 1
Example: acl-add-pkg-ip=1

Whether to allow the reseller to create packages with a dedicated IP address.

acl-add-pkg-shell
integer
Value: 1
Example: acl-add-pkg-shell=1

Whether to allow the reseller to create packages with shell access.

acl-all
integer
Value: 1
Example: acl-all=1

Whether to grant the reseller all ACL privileges.

Warning:

A value of 1 grants root-level privileges to the reseller.

acl-allow-addoncreate
integer
Value: 1
Example: acl-allow-addoncreate=1

Whether to allow the reseller to create packages with addon domains.

acl-allow-parkedcreate
integer
Value: 1
Example: acl-allow-parkedcreate=1

Whether to allow the reseller to create packages with parked domains (aliases).

acl-allow-unlimited-bw-pkgs
integer
Value: 1
Example: acl-allow-unlimited-bw-pkgs=1

Whether to allow the reseller to create packages with unlimited bandwidth.

acl-allow-unlimited-disk-pkgs
integer
Value: 1
Example: acl-allow-unlimited-disk-pkgs=1

Whether to allow the reseller to create packages with unlimited disk space.

acl-allow-unlimited-pkgs
integer
Value: 1
Example: acl-allow-unlimited-pkgs=1

Whether to allow the reseller to create packages with unlimited features.

acl-basic-system-info
integer
Value: 1
Example: acl-basic-system-info=1

Whether to allow the reseller to retrieve basic system information.

acl-basic-whm-functions
integer
Value: 1
Example: acl-basic-whm-functions=1

Whether to allow the reseller to access basic cPanel & WHM options.

acl-clustering
integer
Value: 1
Example: acl-clustering=1

Whether to allow the reseller to use DNS clusters.

acl-cors-proxy-get
integer
Value: 1
Example: acl-cors-proxy-get=1

Whether to allow the reseller to perform Cross-Origin Resource Sharing (CORS) HTTP requests.

acl-cpanel-api
integer
Value: 1
Example: acl-cpanel-api=1

Whether to allow the reseller to execute cPanel API 1, cPanel API 2 and UAPI functions via WHM.

acl-cpanel-integration
integer
Value: 1
Example: acl-cpanel-integration=1

Whether to allow the reseller to manage how their server and its services connect to other servers and services.

acl-create-acct
integer
Value: 1
Example: acl-create-acct=1

Whether to allow the reseller to create accounts.

acl-create-dns
integer
Value: 1
Example: acl-create-dns=1

Whether to allow the reseller to add DNS zones.

acl-create-user-session
integer
Value: 1
Example: acl-create-user-session=1

Whether to allow the reseller to create a temporary session user for a specified service.

Note:

This privilege allows an API token user to bypass any restrictions that you set on the API token. For more information, read our Manage API Tokens documentation.

acl-demo-setup
integer
Value: 1
Example: acl-demo-setup=1

Whether to allow the reseller to enable demo mode for accounts.

acl-digest-auth
integer
Value: 1
Example: acl-digest-auth=1

Whether to allow the reseller to manage Digest Authentication support.

acl-disallow-shell
integer
Value: 1
Example: acl-disallow-shell=1

Whether to allow the reseller to create accounts with shell access.

acl-edit-account
integer
Value: 1
Example: acl-edit-account=1

Whether to allow the reseller to edit accounts.

acl-edit-dns
integer
Value: 1
Example: acl-edit-dns=1

Whether to allow the reseller to edit DNS zones.

acl-edit-mx
integer
Value: 1
Example: acl-edit-mx=1

Whether to allow the reseller to edit MX entries.

acl-edit-pkg
integer
Value: 1
Example: acl-edit-pkg=1

Whether to allow the reseller to edit hosting plans (packages).

acl-generate-email-config
integer
Value: 1
Example: acl-generate-email-config=1

Whether to allow the reseller to generate a mobile configuration profile for an email account.

acl-kill-acct
integer
Value: 1
Example: acl-kill-acct=1

Whether to allow the reseller to terminate accounts.

acl-kill-dns
integer
Value: 1
Example: acl-kill-dns=1

Whether to allow the reseller to remove DNS zones.

acl-limit-bandwidth
integer
Value: 1
Example: acl-limit-bandwidth=1

Whether to allow the reseller to modify bandwidth limits (quotas).

Warning:

If you do not use resource limits, a value of 1 allows resellers to circumvent package limits for disk space.

acl-list-accts
integer
Value: 1
Example: acl-list-accts=1

Whether to allow the reseller to view the list of accounts.

acl-list-pkgs
integer
Value: 1
Example: acl-list-pkgs=1

Whether to allow the reseller to view existing hosting plans (packages).

acl-locale-edit
integer
Value: 1
Example: acl-locale-edit=1

Whether to allow the reseller to create and modify locales on the server.

acl-mailcheck
integer
Value: 1
Example: acl-mailcheck=1

Whether to allow the reseller to troubleshoot mail delivery.

acl-manage-api-tokens
integer
Value: 1
Example: acl-manage-api-tokens=1

Whether to allow the reseller to manage API tokens.

Note:

This privilege allows an API token user to bypass any restrictions that you set on the API token. For more information, read our Manage API Tokens documentation.

acl-manage-dns-records
integer
Value: 1
Example: acl-manage-dns-records=1

Whether to allow the reseller to manage DNS records.

acl-manage-oidc
integer
Value: 1
Example: acl-manage-oidc=1

Whether to allow the reseller to manage external authentication for their accounts.

acl-manage-styles
integer
Value: 1
Example: acl-manage-styles=1

Whether to allow the reseller to manage their server's cPanel styles.

acl-mysql-info
integer
Value: 1
Example: acl-mysql-info=1

Whether to allow the reseller to retrieve MySQL® database and user data.

acl-nameserver-config
integer
Value: 1
Example: acl-nameserver-config=1

Whether to allow the reseller to manage nameservers.

acl-news
integer
Value: 1
Example: acl-news=1

Whether to allow the reseller to modify the server's news.

acl-park-dns
integer
Value: 1
Example: acl-park-dns=1

Whether to allow the reseller to park DNS zones.

acl-passwd
integer
Value: 1
Example: acl-passwd=1

Whether to allow the reseller to change passwords.

Note:

This privilege allows an API token user to change account passwords and log in with a new password. For more information, read our Manage API Tokens documentation.

acl-quota
integer
Value: 1
Example: acl-quota=1

Whether to allow the reseller to modify quotas.

Warning:

If you do not use resource limits, a value of 1 allows resellers to circumvent package limits for disk space.

acl-rearrange-accts
integer
Value: 1
Example: acl-rearrange-accts=1

Whether to allow the reseller to rearrange accounts.

acl-resftp
integer
Value: 1
Example: acl-resftp=1

Whether to allow the reseller to resync FTP passwords.

acl-restart
integer
Value: 1
Example: acl-restart=1

Whether to allow the reseller to restart services.

acl-show-bandwidth
integer
Value: 1
Example: acl-show-bandwidth=1

Whether to allow the reseller to view account bandwidth usage.

acl-ssl
integer
Value: 1
Example: acl-ssl=1

Whether to allow the reseller to perform SSL site management.

acl-ssl-buy
integer
Value: 1
Example: acl-ssl-buy=1

Whether to allow the reseller to purchase SSL certificates.

acl-ssl-gencrt
integer
Value: 1
Example: acl-ssl-gencrt=1

Whether to allow the reseller to generate SSL certificates.

acl-ssl-info
integer
Value: 1
Example: acl-ssl-info=1

Whether to allow the reseller to view their server's SSL information.

acl-stats
integer
Value: 1
Example: acl-stats=1

Whether to allow the reseller to view server information.

acl-status
integer
Value: 1
Example: acl-status=1

Whether to allow the reseller to view the server's status.

acl-suspend-acct
integer
Value: 1
Example: acl-suspend-acct=1

Whether to allow the reseller to suspend or unsuspend accounts.

acl-thirdparty
integer
Value: 1
Example: acl-thirdparty=1

Whether to allow the reseller to manage third-party services.

acl-track-email
integer
Value: 1
Example: acl-track-email=1

Whether to allow the reseller to view reports about email message delivery attempts from their account.

acl-upgrade-account
integer
Value: 1
Example: acl-upgrade-account=1

Whether to allow the reseller to upgrade or downgrade accounts.

acl-viewglobalpackages
integer
Value: 1
Example: acl-viewglobalpackages=1

Whether to allow the reseller to use all global packages. For more information, read our reseller packages documentation.

acllist
string
Example: acllist=my_acl_list

The ACL to assign to the reseller.

Warning:

Functions should either use this parameter, or a combination of the acl-* parameters below. Do not include both in a single function.

reseller
required
string <username>
Example: reseller=username

The reseller's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty setacls reseller='username' acl-acct-summary=1 acl-basic-system-info=1 acl-basic-whm-functions=1 acl-cors-proxy-get=1 acl-cpanel-api=1 acl-cpanel-integration=1 acl-create-user-session=1 acl-digest-auth=1 acl-generate-email-config=1 acl-list-pkgs=1 acl-manage-api-tokens=1 acl-manage-dns-records=1 acl-manage-oidc=1 acl-manage-styles=1 acl-mysql-info=1 acl-ns-config=1 acl-public-contact=1 acl-ssl-info=1 acl-track-email=1

Response samples

Content type
application/json
{
  • "data": {
    • "acl": [
      • "all"
      ]
    },
  • "metadata": {
    • "command": "setacls",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all privilege lists and settings

This function lists the server's Access Control Lists (ACLs) and each list's privileges.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listacls

Response samples

Content type
application/json
{
  • "data": {
    • "acl": [
      • {
        • "name": "acl1",
        • "privileges": {
          • "acct-summary": 1,
          • "add-pkg": 1,
          • "add-pkg-ip": 1,
          • "add-pkg-shell": 1,
          • "all": 1,
          • "allow-addoncreate": 1,
          • "allow-emaillimits-pkgs": 1,
          • "allow-parkedcreate": 1,
          • "allow-shell": 1,
          • "allow-unlimited-bw-pkgs": 1,
          • "allow-unlimited-disk-pkgs": 1,
          • "allow-unlimited-pkgs": 1,
          • "basic-system-info": 1,
          • "basic-whm-functions": 1,
          • "clustering": 1,
          • "cors-proxy-get": 1,
          • "cpanel-api": 1,
          • "cpanel-integration": 1,
          • "create-acct": 1,
          • "create-dns": 1,
          • "create-user-session": 1,
          • "demo-setup": 1,
          • "digest-auth": 1,
          • "edit-account": 1,
          • "edit-dns": 1,
          • "edit-mx": 1,
          • "edit-pkg": 1,
          • "frontpage": 1,
          • "generate-email-config": 1,
          • "kill-acct": 1,
          • "kill-dns": 1,
          • "limit-bandwidth": 1,
          • "list-accts": 1,
          • "list-pkgs": 1,
          • "locale-edit": 1,
          • "mailcheck": 1,
          • "manage-api-tokens": 1,
          • "manage-dns-records": 1,
          • "manage-oidc": 1,
          • "manage-styles": 1,
          • "mysql-info": 1,
          • "news": 1,
          • "ns-config": 1,
          • "park-dns": 1,
          • "passwd": 1,
          • "quota": 1,
          • "rearrange-accts": 1,
          • "resftp": 1,
          • "restart": 1,
          • "show-bandwidth": 1,
          • "ssl": 1,
          • "ssl-buy": 1,
          • "ssl-gencrt": 1,
          • "ssl-info": 1,
          • "stats": 1,
          • "status": 1,
          • "suspend-acct": 1,
          • "thirdparty": 1,
          • "track-email": 1,
          • "upgrade-account": 1,
          • "viewglobalpackages": 1
          }
        }
      ]
    },
  • "metadata": {
    • "command": "listacls",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create or update privilege list and settings

This function creates or modifies an Access Control List (ACL).

Note:

For each acl-* parameter, a value of 1 adds that privilege to the ACL list and a value of 0 removes that privilege from the ACL list.

Warning:

We strongly recommend that WHM users create and edit ACLs and ACL privileges through WHM's Edit Reseller Nameservers and Privileges interface ( WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges ).

Authorizations:
BasicAuth
query Parameters
acl-acct-summary
integer
Default: 0
Possible Values: 0 1
Example: acl-acct-summary=1

Whether to allow the reseller to view an account summary.

acl-add-pkg
integer
Default: 0
Possible Values: 0 1
Example: acl-add-pkg=1

Whether to allow the reseller to add and remove hosting plans (packages).

acl-add-pkg-ip
integer
Default: 0
Possible Values: 0 1
Example: acl-add-pkg-ip=1

Whether to allow the reseller to create packages with a dedicated IP address.

acl-add-pkg-shell
integer
Default: 0
Possible Values: 0 1
Example: acl-add-pkg-shell=1

Whether to allow the reseller to create packages with shell access.

acl-all
integer
Default: 0
Possible Values: 0 1
Example: acl-all=1

Whether to grant the reseller all privileges.

Warning:

A value of 1 grants root-level privileges to the reseller.

acl-allow-addoncreate
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-addoncreate=1

Whether to allow the reseller to create packages with addon domains.

acl-allow-emaillimits-pkgs
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-emaillimits-pkgs=1

Whether to allow the reseller to create packages with custom email quotas.

acl-allow-parkedcreate
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-parkedcreate=1

Whether to allow the reseller to create packages with parked domains (aliases).

acl-allow-shell
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-shell=1

Whether to allow the reseller to create accounts with shell access.

acl-allow-unlimited-bw-pkgs
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-unlimited-bw-pkgs=1

Whether to allow the reseller to create packages with unlimited bandwidth.

acl-allow-unlimited-disk-pkgs
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-unlimited-disk-pkgs=1

Whether to allow the reseller to create packages with unlimited disk space.

acl-allow-unlimited-pkgs
integer
Default: 0
Possible Values: 0 1
Example: acl-allow-unlimited-pkgs=1

Whether to allow the reseller to create packages with unlimited features.

acl-basic-system-info
integer
Default: 0
Possible Values: 0 1
Example: acl-basic-system-info=1

Whether to allow the reseller to retrieve basic system information.

acl-basic-whm-functions
integer
Default: 0
Possible Values: 0 1
Example: acl-basic-whm-functions=1

Whether to allow the reseller to access basic cPanel & WHM options.

acl-clustering
integer
Default: 0
Possible Values: 0 1
Example: acl-clustering=1

Whether to allow the reseller to use DNS clusters.

acl-cors-proxy-get
integer
Default: 0
Possible Values: 0 1
Example: acl-cors-proxy-get=1

Whether to allow the reseller to perform Cross-Origin Resource Sharing (CORS) HTTP requests.

acl-cpanel-api
integer
Default: 0
Possible Values: 0 1
Example: acl-cpanel-api=1

Whether to allow the reseller to execute cPanel API 1, cPanel API 2 and UAPI functions via WHM.

acl-cpanel-integration
integer
Default: 0
Possible Values: 0 1
Example: acl-cpanel-integration=1

Whether to allow the reseller to manage how their server and its services connect to other servers and services.

acl-create-acct
integer
Default: 0
Possible Values: 0 1
Example: acl-create-acct=1

Whether to allow the reseller to create accounts.

acl-create-dns
integer
Default: 0
Possible Values: 0 1
Example: acl-create-dns=1

Whether to allow the reseller to add DNS zones.

acl-create-user-session
integer
Default: 0
Possible Values: 0 1
Example: acl-create-user-session=1

Whether to allow the reseller to create a temporary user session for a specified service.

Notes:

This privilege allows an API token user to bypass any restrictions that you set on the API token. For more information, read our Manage API Tokens documentation.

acl-demo-setup
integer
Default: 0
Possible Values: 0 1
Example: acl-demo-setup=1

Whether to allow the reseller to enable demo mode for accounts.

acl-digest-auth
integer
Default: 0
Possible Values: 0 1
Example: acl-digest-auth=1

Whether to allow the reseller to manage Digest Authentication support.

acl-edit-account
integer
Default: 0
Possible Values: 0 1
Example: acl-edit-account=1

Whether to allow the reseller to edit accounts.

acl-edit-dns
integer
Default: 0
Possible Values: 0 1
Example: acl-edit-dns=1

Whether to allow the reseller to edit DNS zones.

acl-edit-mx
integer
Default: 0
Possible Values: 0 1
Example: acl-edit-mx=1

Whether to allow the reseller to edit MX entries.

acl-edit-pkg
integer
Default: 0
Possible Values: 0 1
Example: acl-edit-pkg=1

Whether to allow the reseller to edit hosting plans (packages).

acl-generate-email-config
integer
Default: 0
Possible Values: 0 1
Example: acl-generate-email-config=1

Whether to allow the reseller to generate a mobile configuration profile for an email account.

acl-kill-acct
integer
Default: 0
Possible Values: 0 1
Example: acl-kill-acct=1

Whether to allow the reseller to terminate accounts.

acl-kill-dns
integer
Default: 0
Possible Values: 0 1
Example: acl-kill-dns=1

Whether to allow the reseller to remove DNS zones.

acl-limit-bandwidth
integer
Default: 0
Possible Values: 0 1
Example: acl-limit-bandwidth=1

Whether to allow the reseller to modify bandwidth limits (quotas).

Warning:

If you do not use resource limits, a value of 1 allows resellers to circumvent package limits for disk space.

acl-list-accts
integer
Default: 0
Possible Values: 0 1
Example: acl-list-accts=1

Whether to allow the reseller to view the list of accounts.

acl-list-pkgs
integer
Default: 0
Possible Values: 0 1
Example: acl-list-pkgs=1

Whether to allow the reseller to view existing hosting plans (packages).

acl-locale-edit
integer
Default: 0
Possible Values: 0 1
Example: acl-locale-edit=1

Whether to allow the reseller to create and modify locales on the server.

acl-mailcheck
integer
Default: 0
Possible Values: 0 1
Example: acl-mailcheck=1

Whether to allow the reseller to troubleshoot mail delivery.

acl-manage-api-tokens
integer
Default: 0
Possible Values: 0 1
Example: acl-manage-api-tokens=1

Whether to allow the reseller to manage API tokens.

Notes:

This privilege allows an API token user to bypass any restrictions that you set on the API token. For more information, read our Manage API Tokens documentation.

acl-manage-dns-records
integer
Default: 0
Possible Values: 0 1
Example: acl-manage-dns-records=1

Whether to allow the reseller to manage DNS records.

acl-manage-oidc
integer
Default: 0
Possible Values: 0 1
Example: acl-manage-oidc=1

Whether to allow the reseller to manage external authentication for their accounts.

acl-manage-styles
integer
Default: 0
Possible Values: 0 1
Example: acl-manage-styles=1

Whether to allow the reseller to manage their server's cPanel styles.

acl-mysql-info
integer
Default: 0
Possible Values: 0 1
Example: acl-mysql-info=1

Whether to allow the reseller to retrieve MySQL® database and user data.

acl-news
integer
Default: 0
Possible Values: 0 1
Example: acl-news=1

Whether to allow the reseller to modify the server's news.

acl-ns-config
integer
Default: 0
Possible Values: 0 1
Example: acl-ns-config=1

Whether to allow the reseller to manage nameservers.

acl-park-dns
integer
Default: 0
Possible Values: 0 1
Example: acl-park-dns=1

Whether to allow the reseller to park DNS zones.

acl-passwd
integer
Default: 0
Possible Values: 0 1
Example: acl-passwd=1

Whether to allow the reseller to change passwords.

Note:

This privilege allows an API token user to change account passwords and log in with a new password. For more information, read our Manage API Tokens documentation.

acl-quota
integer
Default: 0
Possible Values: 0 1
Example: acl-quota=1

Whether to allow the reseller to modify quotas.

Warning:

If you do not use resource limits, this privilege allows resellers to circumvent package limits for disk space.

acl-rearrange-accts
integer
Default: 0
Possible Values: 0 1
Example: acl-rearrange-accts=1

Whether to allow the reseller to rearrange accounts.

acl-resftp
integer
Default: 0
Possible Values: 0 1
Example: acl-resftp=1

Whether to allow the reseller to resync FTP passwords.

acl-restart
integer
Default: 0
Possible Values: 0 1
Example: acl-restart=1

Whether to allow the reseller to restart services.

acl-show-bandwidth
integer
Default: 0
Possible Values: 0 1
Example: acl-show-bandwidth=1

Whether to allow the reseller to view account bandwidth usage.

acl-ssl
integer
Default: 0
Possible Values: 0 1
Example: acl-ssl=1

Whether to allow the reseller to perform SSL site management.

acl-ssl-buy
integer
Default: 0
Possible Values: 0 1
Example: acl-ssl-buy=1

Whether to allow the reseller to purchase SSL certificates.

acl-ssl-gencrt
integer
Default: 0
Possible Values: 0 1
Example: acl-ssl-gencrt=1

Whether to allow the reseller to generate SSL certificates.

acl-ssl-info
integer
Default: 0
Possible Values: 0 1
Example: acl-ssl-info=1

Whether to allow the reseller to view their server's SSL information.

acl-stats
integer
Default: 0
Possible Values: 0 1
Example: acl-stats=1

Whether to allow the reseller to view server information.

acl-status
integer
Default: 0
Possible Values: 0 1
Example: acl-status=1

Whether to allow the reseller to view the server's status.

acl-suspend-acct
integer
Default: 0
Possible Values: 0 1
Example: acl-suspend-acct=1

Whether to allow the reseller to suspend or unsuspend accounts.

acl-thirdparty
integer
Default: 0
Possible Values: 0 1
Example: acl-thirdparty=1

Whether to allow the reseller to manage third-party services.

acl-track-email
integer
Default: 0
Possible Values: 0 1
Example: acl-track-email=1

Whether to allow the reseller to view reports about email message delivery attempts from their account.

acl-upgrade-account
integer
Default: 0
Possible Values: 0 1
Example: acl-upgrade-account=1

Whether to allow the reseller to upgrade or downgrade accounts.

acl-viewglobalpackages
integer
Default: 0
Possible Values: 0 1
Example: acl-viewglobalpackages=1

Whether to allow the reseller to use all global packages. For more information, read our reseller packages documentation.

acllist
required
string
Example: acllist=my_acl_list

The ACL to assign to the reseller.

Note:

To modify an existing ACL, set this value to that ACL's name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  saveacllist \
  acllist='my_acl_list'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "saveacllist",
    • "reason": "ACL List my_acl_list saved.",
    • "result": 1,
    • "version": 1
    }
}

Account Settings

Resellers / Account Settings

Update current user's public contact information

This function sets an account's public contact information.

Authorizations:
BasicAuth
query Parameters
name
string
Example: name=Bob's Hosting

The public contact name of the reseller. If you do not use this parameter, the system retains the current setting.

url
string
Example: url=https://bobshosting.net

The public contact URL. If you do not use this parameter, the system retains the current setting.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_public_contact

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_public_contact",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's public contact information

This function retrieves an account's public contact information.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_public_contact

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "get_public_contact",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return reseller's owned accounts' information

This function lists a reseller's total accounts, suspended accounts, and account creation limit.

Authorizations:
BasicAuth
query Parameters
user
string <username>
Example: user=username

A reseller's username, to query that reseller. If you do not specify a value, the function lists information for the authenticated account.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  acctcounts

Response samples

Content type
application/json
{
  • "data": {
    • "reseller": {
      • "active": 9,
      • "limit": 25,
      • "suspended": 5,
      • "user": "root"
      }
    },
  • "metadata": {
    • "command": "acctcounts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return reseller's available IP addresses

This function lists a reseller's available IP addresses.

Authorizations:
BasicAuth
query Parameters
user
string <username>
Example: user=username

A reseller's username, to query only that reseller.

Note:

If you do not specify a value, the function lists available IP addresses for the root user.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  getresellerips

Response samples

Content type
application/json
{
  • "data": {
    • "all": 1,
    • "ip": [
      • "192.168.0.20"
      ]
    },
  • "metadata": {
    • "command": "getresellerips",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all resellers

This function lists the reseller accounts on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listresellers

Response samples

Content type
application/json
{
  • "data": {
    • "reseller": [
      • "bob"
      ]
    },
  • "metadata": {
    • "command": "listresellers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update reseller's main IP address

This function assigns a main IP address to a reseller's account.

Note:

To assign additional IP addresses to a reseller's account, call the WHM API 1 setresellerips function.

Authorizations:
BasicAuth
query Parameters
ip
required
string <ipv4>
Example: ip=192.168.0.20

The IP address to assign to the reseller's account as the main shared IP address.

user
required
string
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setresellermainip \
  user='username' \
  ip='192.168.0.20'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setresellermainip",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return reseller's information

This function lists data about a reseller's accounts.

Authorizations:
BasicAuth
query Parameters
filter_deleted
integer
Default: 0
Possible Values: 0 1
Example: filter_deleted=0

Do not display the reseller's deleted cPanel accounts in the function's acct return. This parameter modifies the data output in the acct return.

  • 1 — Do not display.
  • 0 — Display.
filter_suspended
integer
Default: 0
Possible Values: 0 1
Example: filter_suspended=0

Do not display the reseller's suspended cPanel accounts in the function's acct return. This parameter modifies the data output in the acct return.

  • 1 — Do not display.
  • 0 — Display.
month
integer [ 1 .. 12 ]
Example: month=2

The month to query, in numeric format.

This parameter defaults to the current month.

user
required
string <username>
Example: user=username

The reseller's username.

year
integer
Example: year=2019

The year to query, in numeric format.

This parameter defaults to the current year.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  resellerstats \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "reseller": {
      • "acct": [
        • {
          • "bandwidthlimit": "500",
          • "bandwidthused": 0,
          • "deleted": 0,
          • "diskquota": "1100.00",
          • "diskused": "1.57",
          • "domain": "example1.com",
          • "package": "default",
          • "suspended": 0,
          • "user": "example1"
          }
        ],
      • "bandwidthlimit": 0,
      • "bwoverselling": 0,
      • "diskoverselling": 0,
      • "diskquota": 0,
      • "diskused": 5.69,
      • "month": 2,
      • "totalbwalloc": "500",
      • "totalbwused": 0,
      • "totaldiskalloc": "1100",
      • "user": "username",
      • "year": 2019
      }
    },
  • "metadata": {
    • "command": "resellerstats",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add IP addresses to reseller

This function adds IP addresses to a reseller's account.

Note:

To assign a main IP address to a reseller's account, call the WHM API 1 setresellermainip function.

For more information, read our Manage Reseller's IP Delegation documentation.

Authorizations:
BasicAuth
query Parameters
delegate
integer
Default: 0
Value: 1
Example: delegate=1

Whether to allocate the reseller a dedicated IP address.

  • 1 — Restrict the reseller's account to its dedicated IP address.
  • 0 — Allow the user to dedicate any available IP address to an owned account.
ips
string <ipv4>
Example: ips=192.168.0.20

The IP addresses to allocate to the reseller's account.

Note:

  • If you do not use this parameter, the function clears the reseller's IP address list.
  • Use a comma-separated list to allocate multiple IP addresses.
user
required
string <username>
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  setresellerips \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "all": 1,
    • "ip": [
      • "192.168.0.20"
      ]
    },
  • "metadata": {
    • "command": "setresellerips",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update reseller's assigned nameservers

This function assigns nameservers to a reseller's account.

Authorizations:
BasicAuth
query Parameters
nameservers
string
Examples:
  • nameservers=ns1.example.com,ns2.example.com - Multiple nameservers
  • nameservers=ns1.example.com - A single nameserver

A comma-separated list of the nameserver domains to assign to the reseller's account.

Note:

If you do not use this parameter, the function resets the reseller's nameservers to use the server default.

user
required
string <username>
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setresellernameservers \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setresellernameservers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Reseller Account Management

Resellers / Account Management

Suspend reseller

This function suspends a reseller account.

Authorizations:
BasicAuth
query Parameters
disallow
integer
Default: 0
Possible Values: 0 1
Example: disallow=0

Whether to allow only the root user to unsuspend the account.

  • 1 — Only the root user can unsuspend the account.
  • 0 — The root user or the account's owner can unsuspend the account.
reason
string
Example: reason=Nonpayment

The reason for the reseller's suspension.

Note:

We strongly recommend that you always include a reason for suspension.

reseller-only
integer
Default: 0
Possible Values: 0 1
Example: reseller-only=0

Whether to suspend only the reseller account.

  • 1 — The function only suspends the reseller account. The function will not suspend the accounts that the reseller account owns.
  • 0 — The function suspends the reseller account and the accounts that it owns.
user
required
string <username>
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  suspendreseller \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "suspendreseller",
    • "output": {
      • "raw": "string"
      },
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable cPanel account's reseller status

This function grants reseller status to an account.

Note:

This function grants reseller status to an existing account. You cannot create a new account with this function.

Authorizations:
BasicAuth
query Parameters
makeowner
integer
Default: 0
Possible Values: 0 1
Example: makeowner=0

Whether to set the account to own itself.

  • 1 — Make the account own itself.
  • 0 — Keep the account's current owner.
user
required
string <username>
Example: user=username

The account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  setupreseller \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "setupreseller",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disables cPanel account's reseller status

This function revokes reseller status from an account.

Authorizations:
BasicAuth
query Parameters
user
required
string <username>
Example: user=username

The reseller account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  unsetupreseller \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "unsetupreseller",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete reseller and reseller's cPanel accounts

This function deletes a reseller and all of the reseller's cPanel accounts.

Warning:

  • You cannot recover deleted accounts. Use this function with extreme caution.
  • This function deletes the reseller account and all of the accounts that the reseller owns.
  • To remove reseller privileges from an account but not delete the reseller's account or any accounts that the reseller owns, use the WHM API 1 unsetupreseller function.
Authorizations:
BasicAuth
query Parameters
terminatereseller
required
integer
Possible Values: 1 0
Example: terminatereseller=1

Whether to terminate the reseller's main account.

  • 1 — Terminate.
  • 0 — Do not terminate.
user
required
string <username>
Example: user=username

The reseller account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  terminatereseller \
  user='username' \
  terminatereseller='1'

Response samples

Content type
application/json
{
  • "data": {
    • "acct": [
      • {
        • "output": {
          • "raw": "Running pre removal script (/usr/local/cpanel/scripts/prekillacct)......DoneCollecting\nDomain Name and IP...User: example Domain: example.com\n...DoneLocking account and setting shell to nologin...Locking\npassword for user example. passwd: Success ...DoneKilling\nall processes owned by user......DoneRemoving\nSessions.........DoneRemoving Suspended Info.........DoneCleaning\nVirtfs.........DoneRemoving Web Logs......DoneRemoving\nBandwidth Files......DoneRemoving Email Sending\nLimits Cache......DoneRemoving DKIM keys......DoneRemoving\nCrontab......DoneRemoving HTTP Virtual Hosts...Removed\nthe following non-SSL virtual hosts: example.com\nRemoved the following SSL virtual hosts: ...DoneRemoving\nftp Virtual Hosts......Done Removing user''''s\nweb content directory symlinks......DoneRemoving\nMySQL databases and users......DoneRemoving PostgreSQL\ndatabases and users......DoneRemoving User & Group.......Success...Done\nRemoving DNS Entries...example.com => deleted\nfrom hostname. ...Done Removing Email Setup...Removing\n/etc/valiases/example.com ...Done Removing mailman\nlists......Done Updating Databases......Done Removing\nbandwidth limits......Done Removing Counter Data......Done\nAdding IP back to the IP address pool...System\nhas 3 free ips. ...Done Removing user''''s cPanel\nDatabases & Updating......Done Reloading Services......Done\nRemoving mail and service configs... ...Done Removing\nLogaholic Webstats...Id: TQ:TaskQueue:129 ...Done\nSending Contacts......Done Updating internal databases...Updating\nftp passwords for example Purging ftp user example\nFtp password files updated. Ftp vhost passwords\nsynced ...Done Running post removal scripts (/usr/local/cpanel/scripts/legacypostkillacct,\n/usr/local/cpanel/scripts/postkillacct)......Done\nAccount Removal Complete!!!...example account\nremoved...Done\n"
          },
        • "reason": "username account removed",
        • "result": 1,
        • "user": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "terminatereseller",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Unsuspend reseller

This function unsuspends a reseller account.

Authorizations:
BasicAuth
query Parameters
reseller-only
integer
Default: 0
Possible Values: 0 1
Example: reseller-only=0

Whether to unsuspend only the reseller account.

  • 1 — The function only unsuspends the reseller account. The function will not unsuspend the accounts that the reseller account owns.
  • 0 — The function unsuspends the reseller account and the accounts that it owns.
user
required
string
Example: user=username

The reseller's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  unsuspendreseller \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "unsuspendreseller",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

WHM Access

Security / WHM Access

Clear all CIDR restrictions to login to cPanel & WHM with the root password.

This function removes all restrictions to root login to cPanel & WHM login based on IP.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  allow_all_whm_root_access

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "allow_all_whm_root_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restrict Access to WHM by CIDR list.

This function restricts root login to cPanel & WHM based on a list of CIDR addresses.

Note:

This API manipulates /var/cpanel/authorized_whm_root_ips. We HIGHLY recommend you not modify this file directly. Improper formatting of the file can lead to loss of all access to cPanel & WHM using the root password.

Use of this API replaces any previous restrictions so be sure to include previous CIDR patterns when adding new ones.

As this API only restricts logins, please be aware that existing root logins are not terminated when these restrictions are asserted.

This API DOES NOT restrict root resellers.

Authorizations:
BasicAuth
query Parameters
cidr
required
string <cidr>
Examples:
  • cidr=10.2.0.0/16&cidr=10.6.5.0/24&cidr=10.1.6.7 - Multiple CIDR Addresses.
  • cidr=10.2.0.0/16 - A single CIDR Address

The IPs you wish to restrict in CIDR format.

Note:

You can pass this parameter multiple times.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restrict_whm_root_access \
  cidr=10.2.0.0/16 \
  cidr=10.6.5.0/24 \
  cidr=10.1.6.7

Response samples

Content type
application/json
{
  • "data": {
    • "cidr": [
      • "10.2.0.0/16",
      • "10.6.5.0/24",
      • "10.1.6.7"
      ]
    },
  • "metadata": {
    • "command": "restrict_whm_root_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Configuration Clusters

Server Administration / Configuration Clusters

Add configuration cluster server

This function adds a server to a configuration cluster. The function's return data appears in the metadata section of its output.

We recommend that you run this function as a POST request with SSL enabled:

  • The length of the remote access key may cause problems if you run the function with the GET method (for example, a URL in your browser).
  • You risk security problems if you enter a remote access key through the GET method.

Important:

  • Run this function as a root-level user on the server that you wish to use as the parent server.
  • If you log in to a configuration cluster server that is not the parent server, nothing will indicate that the server is part of a configuration cluster. You can only view and modify this information from the parent server.
Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0

A truncated version of the server's remote access key.

name
required
string
Example: name=example.com

The remote configuration cluster server's name.

user
required
string
Example: user=root

The username for the server's root-level account.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  add_configclusterserver \
  name='example.com' \
  user='root' \
  key='d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "add_configclusterserver",
    • "name": "example.com",
    • "reason": "OK",
    • "result": 1,
    • "signature": "d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0",
    • "user": "root",
    • "version": 1
    }
}

Delete server from configuration cluster

This function removes a server from a configuration cluster. The function's return data appears in the metadata section of its output.

Important:

If you log in to a configuration cluster server that is not the parent server, nothing will indicate that the server is part of a configuration cluster. You can only view and modify this information from the parent server.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=example.com

The hostname or IP address of a remote configuration cluster server.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_configclusterserver \
  name='example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "delete_configclusterserver",
    • "name": "example.com",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all configuration cluster servers

This function lists the servers in the server's configuration cluster.

Warning:

  • WHM's Remote Access Key feature is deprecated. We strongly recommend that you use API tokens instead.

  • If you log in to a configuration cluster server that is not the parent server, nothing will indicate that the server is part of a configuration cluster. You can only view and modify this information from the parent server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Configuration cluster signatures and users for each server.

object

Request samples 

whmapi1 --output=jsonpretty \
  list_configclusterservers

Response samples

Content type
application/json
{
  • "data": {
    • "example1.com": {
      • "signature": "d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0",
      • "user": "root"
      },
    • "example2.com": {
      • "signature": "d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d1",
      • "user": "root"
      }
    },
  • "metadata": {
    • "command": "list_configclusterservers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update configuration cluster server credentials

This function updates the username or remote access key for a cluster server.

Important:

  • If you log in to a configuration cluster server that is not the parent server, nothing will indicate that the server is part of a configuration cluster. You can only view and modify this information from the master server.

  • We recommend that you run this function as a POST request with SSL enabled:

    • The length of the remote access key may cause problems if you run the function with the GET method (for example, a URL in your browser).
    • You risk security problems if you enter a remote access key through the GET method.
Authorizations:
BasicAuth
query Parameters
key
string
Example: key=d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0

The new remote access key. If you do not specify a value, the function does not update the remote access key.

name
required
string
Example: name=example.com

The remote configuration cluster server's name or IP address.

user
string
Example: user=root

The server's root-level account username. If you do not specify a value, the function does not update the username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_configclusterserver \
  name='example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_configclusterserver",
    • "name": "example.com",
    • "reason": "OK",
    • "result": 1,
    • "signature": "d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0:d0",
    • "user": "root",
    • "version": 1
    }
}

Update configuration file from backup

This function restores a configuration backup from a file. If the backup file does not contain any changes, the system does not write to the configuration file.

Authorizations:
BasicAuth
query Parameters
module
required
string
Example: module=Main

The configuration module's name.

Important:

This parameter is case-sensitive. You must enter the parameter in the correct case format; otherwise, the function will fail.

path
required
string
Example: path=/var/cpanel/cpanel.config

The absolute path to configuration file.

Note: If this parameter contains JSON or equals-sign key and value pairs, they must appear in new lines.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  restore_config_from_file \
  module='Main' \
  path='/var/cpanel/cpanel.config'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_config_from_file",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update configuration file from backup via POST

This function restores a configuration backup file via HTTP POST method. If the backup file does not contain any changes, the system does not write to the configuration file.

Note:

The format for this command line example differs from our standard format because the function only accepts an HTTP POST request. For more information about how to call this request method, read Mozilla's POST documentation.

Authorizations:
BasicAuth
Request Body schema: multipart/form-data
file
required
string <binary>

The configuration file data, in multipart/form-data format.

Note:

When you call this function on the command line, you must provide the configuration file's filepath. For example, you would use the 'file=@/var/cpanel/cpanel.config' parameter structure to call this function.

module
required
string
Possible Values: "Basic" "Main"

The configuration module's name.

Important:

This parameter is case-sensitive. You must enter the parameter in the correct case format; otherwise, the function will fail.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --input=json --output=jsonpretty \
  restore_config_from_upload

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "restore_config_from_upload",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Configurations

Server Administration / Configurations

Return Leika configuration

This function returns a cPanel account's Leika configuration data. Leika is an internal module that cPanel & WHM uses to track access to features.

Note:

If you do not provide an item parameter, this returns the entire configuration.

Authorizations:
BasicAuth
query Parameters
item
string
Examples:
  • item=cpanel.key1 - Return the `key1` configuration key for the `cpanel` feature.
  • item=webmail.key3.subkey1 - Return the nested `key3.subkey1` configuration key for the `webmail` feature.

The feature(s) for which to return configuration keys.

Note:

  • Pass multiple item parameters to return multiple features' configuration keys.
  • If an item parameter returns an undefined key value, the configuration value does not exist or is set to null.

Responses

Response Schema: application/json
object

An object that contains configuration keys and their values.

object

Request samples 

whmapi1 --output=jsonpretty \
  leika_get_config \
  item=cpanel.key1 \
  item=webmail.key3.subkey1

Response samples

Content type
application/json
{
  • "data": {
    • "cpanel.key1": "enabled",
    • "webmail.key3": "JSON object"
    },
  • "metadata": {
    • "command": "leika_get_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Tweak Settings option

This function sets an option's value in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings). The system stores the keys and values that this function updates in the /var/cpanel/cpanel.config file.

Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=proxysubdomains

The cpanel.config setting name that corresponds to the desired setting in WHM's Tweak Settings interface (WHM >>Home >> Server Configuration >> Tweak Settings).

module
string
Default: "Main"
Possible Values: "Apache" "Basic" "Mail" "Main"
Example: module=Main

The Tweak Settings interface section.

Note:

The possible section names are:

  • Apache
  • Basic
  • Mail
  • Main
value
string
Example: value=0

The value to assign to the setting. If you include this parameter in the call but do not set a value, the value defaults to an empty value.

Note:

For more information about the requirements for values in the cpanel.config file settings, read our cpanel.config file documentation.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_tweaksetting \
  key='proxysubdomains'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_tweaksetting",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Tweak Settings option's value

This function retrieves values from the /var/cpanel/cpanel.config file and the server's Exim configuration.

Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=defaultmailaction

The Tweak Settings option.

module
string
Default: "Main"
Possible Values: "Apache" "Basic" "Mail" "Main"
Example: module=Main

One of the following Tweak Settings module names:

  • Apache
  • Basic
  • Mail
  • Main

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_tweaksetting \
  key='defaultmailaction'

Response samples

Content type
application/json
{
  • "data": {
    • "tweaksetting": {
      • "key": "defaultmailaction",
      • "value": "localuser"
      }
    },
  • "metadata": {
    • "command": "get_tweaksetting",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Connected Applications

Server Administration / Connected Applications

List application connection information

Retrieve the connection information for all the connected applications that have been granted access to this server. This data may include any number of properties, but its primary purpose is to associate API tokens and public/private key pairs and similar resources with a specific connected application.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_connected_applications

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "list_connected_applications",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Save application connection information.

Save or update connection data about a specific connected application.

Authorizations:
BasicAuth
Request Body schema: application/json
object

Data associated with the connected application. There are predefined elements related to specific security scenarios, but additional data may be stored here as well.

name
string

The name of the connected application.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "save_connected_application",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Fetch application connection information

Retrieve the connection information related to a application that has been granted access to this server. This data may include any number of properties, but its primary purpose is to associate API tokens and public/private key pairs and similar resources with a specific connected application.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=application-1

The name of the connected application.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_connected_application \
  name='application-1'

Response samples

Content type
application/json
{
  • "data": {
    • "data": {
      • "jwt": {},
      • "private_key": "FEF6253E6A122532430D",
      • "privileges_granted": [
        • "list-accts",
        • "list-resellers",
        • "create-user-session",
        • "acct-summary",
        • "connected-applications"
        ],
      • "public_key": "AAF6253E6A1225324305623EE",
      • "token_name": "Application 1 API Token",
      • "property1": null,
      • "property2": null
      },
    • "name": "application-1"
    },
  • "metadata": {
    • "command": "fetch_connected_application",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove application connection information

Remove the connected application from the server. This only removes the connection information from the configuration file. It does not clean up any allocated resources, such as API tokens and public/private keys. Any tokens or keys need to be removed from the system separately.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=application-1

The name of the connected application.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_connected_application \
  name='application-1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "remove_connected_application",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Connections

Server Administration / Connections

Return TCP IPv4 sockets data

This function returns data about the system's transmission control protocol (TCP) IPv4 sockets.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_tcp4_sockets

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "dport": 443,
        • "dst": "10.0.0.2",
        • "inode": 27171,
        • "rqueue": 0,
        • "sport": 2087,
        • "src": "10.0.0.1",
        • "state": 10,
        • "uid": 102,
        • "wqueue": 45
        }
      ]
    },
  • "metadata": {
    • "command": "get_tcp4_sockets",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return TCP IPv6 sockets data

This function returns data about the system's transmission control protocol (TCP) IPv6 sockets.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_tcp6_sockets

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "dport": 443,
        • "dst": "2001:0db8:0:0:1:0:0:1",
        • "inode": 27171,
        • "rqueue": 0,
        • "sport": 2087,
        • "src": "2001:0db8:0:0:1:0:0:2",
        • "state": 10,
        • "uid": 102,
        • "wqueue": 45
        }
      ]
    },
  • "metadata": {
    • "command": "get_tcp6_sockets",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return UDP IPv4 sockets data

This function returns data about the system's user datagram protocol (UDP) IPv4 sockets.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_udp4_sockets

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "dport": 443,
        • "dst": "10.0.0.2",
        • "inode": 27171,
        • "rqueue": 0,
        • "sport": 53,
        • "src": "10.0.0.1",
        • "state": 10,
        • "uid": 25,
        • "wqueue": 45
        }
      ]
    },
  • "metadata": {
    • "command": "get_udp4_sockets",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return UDP IPv6 sockets data

This function returns data about the system's user datagram protocol (UDP) IPv6 sockets.

Important:

This function may perform slower on a CentOS 6 system with a large number of UDP sockets.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_udp6_sockets

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "dport": 443,
        • "dst": "2001:0db8:0:0:1:0:0:2",
        • "inode": 27171,
        • "rqueue": 0,
        • "sport": 53,
        • "src": "2001:0db8:0:0:1:0:0:1",
        • "state": 10,
        • "uid": 25,
        • "wqueue": 45
        }
      ]
    },
  • "metadata": {
    • "command": "get_udp6_sockets",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

cPanel Analytics

The cPanel Analytics module for WHM API 1.

Enable analytics data gathering

This function enables or disables Interface Analytics.

Authorizations:
BasicAuth
query Parameters
enabled
required
integer
Possible Values: 0 1
Example: enabled=1

Whether to enable Interface Analytics.

  • 1 — Enable.
  • 0 — Disable.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  participate_in_analytics \
  enabled='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "participate_in_analytics",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

License Management

The Server Administration module for WHM API 1.

Return cPanel Store or Market checkout URL

This function returns the checkout URL to use for a cPanel Store or cPanel Market provider purchase.

Authorizations:
BasicAuth
query Parameters
login_token
required
string
Example: login_token=1a676e6f-99fc-11e6-9ab6-e60a769b73bc

The login token to access the cPanel Store.

provider
required
string
Example: provider=cPStore

The cPanel Store or cPanel Market provider's name.

upgrade
integer
Default: 0
Possible Values: 0 1
Example: upgrade=1

Whether the cPanel Store or cPanel Market provider should treat this request as an upgrade.

  • 1 — An upgrade.
  • 0 — Not an upgrade.
url_after_checkout
required
string <url>
Example: url_after_checkout=http://hostname.example.com

The location to which the cPanel Store or cPanel Market provider directs the user after the checkout process finishes.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  purchase_a_license \
  provider='cPStore' \
  url_after_checkout='http://hostname.example.com' \
  login_token='1a676e6f-99fc-11e6-9ab6-e60a769b73bc'

Response samples

Content type
application/json
{}

Return server's cPanel license status

This function verifies the system's license status with WebPros International, LLC's licensing servers. To do this, the function runs the /usr/local/cpanel/cpkeyclt script.

For more information about this script and potential license problems, read our Installation Guide - Troubleshoot Your Installation documentation.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  run_cpkeyclt

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "run_cpkeyclt",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Notifications

Server Administration / Notifications

Return app's event contact importance setting

This function retrieves the importance level of an application event for WHM's Contact Manager interface (Home >> Server Contacts >> Contact Manager).

Note:

The system will create a notification setting for the application's events if one does not already exist.

Authorizations:
BasicAuth
query Parameters
app
required
string
Example: app=Check

The application module's name.

event
required
string
Example: event=SecurityAdvisorStateChange

The event's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_application_contact_event_importance \
  app='Check' \
  event='SecurityAdvisorStateChange'

Response samples

Content type
application/json
{
  • "data": {
    • "importance": 0,
    • "name": "Disabled"
    },
  • "metadata": {
    • "command": "get_application_contact_event_importance",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Contact Manager event importance settings

This function lists the importance of all application events in WHM's Contact Manager interface (WHM >> Home >> Server Contacts >> Contact Manager).

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_all_contact_importances

Response samples

Content type
application/json
{
  • "data": {
    • "importances": [
      • {
        • "app": "wwwacct",
        • "event": "*",
        • "importance": 0,
        • "name": "High"
        }
      ]
    },
  • "metadata": {
    • "command": "get_all_contact_importances",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return app contact importance setting

This function retrieves the importance level of an application's events for WHM's Contact Manager interface (WHM >> Home >> Server Contacts >> Contact Manager).

Note:

The system creates a notification setting for the application's events if one does not already exist.

Authorizations:
BasicAuth
query Parameters
app
required
string
Example: app=Check

The cPanel & WHM application module's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_application_contact_importance \
  app='Check'

Response samples

Content type
application/json
{
  • "data": {
    • "importance": 0,
    • "name": "Disabled"
    },
  • "metadata": {
    • "command": "get_application_contact_importance",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update app's event contact importance setting

This function sets the importance level of an application event for WHM's Contact Manager interface (WHM >> Home >> Server Contacts >> Contact Manager).

For a list of available modules, use the WHM API 1 get_all_contact_importances function.

Note:

The system creates a notification setting for the application's events if one does not already exist.

Authorizations:
BasicAuth
query Parameters
app
required
string
Example: app=Check

The cPanel & WHM application module's name.

event
required
string
Example: event=SecurityAdvisorStateChange

The event's name.

importance
required
string
Possible Values: "High" "Medium" "Low" "Disabled"
Example: importance=Disabled

The importance level at which to send the notification.

  • High
  • Medium
  • Low
  • Disabled

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_application_contact_event_importance \
  app='Check' \
  event='SecurityAdvisorStateChange' \
  importance='Disabled'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_application_contact_event_importance",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update app contact importance setting

This function sets the importance level of an application's events for WHM's Contact Manager interface (WHM >> Home >> Server Contacts >> Contact Manager).

For a list of available modules, use the WHM API 1 get_all_contact_importances function.

Note:

The system creates a notification setting for the application's events if one does not already exist.

Authorizations:
BasicAuth
query Parameters
app
required
string
Example: app=Check

The cPanel & WHM application module's name.

importance
required
string
Possible Values: "High" "Medium" "Low" "Disabled"
Example: importance=Disabled

The importance level at which to send the notification.

  • High
  • Medium
  • Low
  • Disabled

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_application_contact_importance \
  app='Check' \
  importance='Disabled'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_application_contact_importance",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Send notification URL via POST

This function uses the specified URL to send a test message through the POST method of HTTP as form data. The function automatically generates a message title and body and includes a unique string in the test message. When the test message returns, the system searches for the ID string and returns it.

If the function does not detect the correct ID string in the returned message, the function fails.

The test's success or failure depends on various conditions. For example:

  • Valid access token.
  • Network configuration.
  • Service outages.
  • External server rate limit.
Authorizations:
BasicAuth
query Parameters
url
required
string
Example: url=https%3A%2F%2Fwww.example.com%2Fevents.cgi%3Fapikey%3D12345%26user%3Dusername*password%3D12345luggage

The URL and query string to send in uuencoded format. The system automatically sends the parameter's hostname, subject, and body with the relevant data from the alert.

Note:

  • To send additional parameters, include those keys after the URL. For example, to send the apikey parameter with a value of XXXXX, append ?apikey=XXXXX to the URL.
  • To add additional parameters and values, separate those additional values with the ampersand character (&) instead of the question mark character (?). For example, to include a state parameter of Texas and a status parameter of CRITICAL, append ?apikey=XXXXX&state=Texas&status=CRITICAL to the URL.
  • If you enter a secure URL (https://), that site's certificate must be valid.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  send_test_posturl \
  url='https%3A%2F%2Fwww.example.com%2Fevents.cgi%3Fapikey%3D12345%26user%3Dusername*password%3D12345luggage'

Response samples

Content type
application/json
{
  • "data": {
    • "message_id": "554d2cbd-efe61da3cacb"
    },
  • "metadata": {
    • "command": "send_test_posturl",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update WHM contact email address

This function updates the contact email address in the wwwacct.conf file. For more information, read our Installation Guide - Customize Your Installation documentation.

Authorizations:
BasicAuth
query Parameters
contact_email
required
string

The contact email address to add as the wwwacct.conf file's CONTACTEMAIL setting.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_contact_email \
  contact_email='[email protected]'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_contact_email",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Send Pushbullet™ test with access token

This function uses the specified access token to send a test Pushbullet™ note. The function automatically generates a message title and body, and it includes a unique string in the test message. When the test message returns, the system searches for the ID string and returns it.

If the function does not detect the correct ID string in the returned message, the function fails. You can also review the user's Pushbullet channel history to confirm that the server sent and received the message.

The test's success or failure depends on various conditions. For example:

  • Valid access token.
  • Network configuration.
  • Service outages.
  • External server rate limit.
Authorizations:
BasicAuth
query Parameters
access_token
required
string
Example: access_token=a1b2c3d4e5f6g7h8i9j0

The Pushbullet token to use.

Note:

  • To access your Pushbullet token, navigate to Pushbullet's My Account page. It will appear under the Access Token heading.
  • This is confidential information that your server sends via a secure channel.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  send_test_pushbullet_note \
  access_token='a1b2c3d4e5f6g7h8i9j0'

Response samples

Content type
application/json
{
  • "data": {
    • "message_id": "554d2cbd-efe61da3cacb",
    • "payload": {
      • "active": true,
      • "body": "This message confirms that \"hostname.example.com\" (192.168.0.20) can send a message to you via Pushbullet.\n\nThis message was sent on Monday, May 18, 2015 at 7:12:20 PM UTC.",
      • "created": 1431976341.38872,
      • "direction": "self",
      • "dismissed": false,
      • "iden": "ujw5ScArtjUsjAeRXXMLGS",
      • "modifiedx": 1431976341.39182,
      • "receiver_email": "[email protected]",
      • "receiver_email_normalized": "[email protected]",
      • "receiver_iden": "ujw5ScArtjU",
      • "sender_email": "[email protected]",
      • "sender_email_normalized": "[email protected]",
      • "sender_iden": "ujw5ScArtjU",
      • "sender_name": "Firstname Lastname",
      • "title": "Test message (ID: 555a3994-173a4a271062d)",
      • "type": "note"
      }
    },
  • "metadata": {
    • "command": "send_test_pushbullet_note",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate stored ICQ username and password

This function calls WHM API 1's verify_oscar_access function with your specified ICQ accounts. You can specify ICQ accounts in the Contact Information section of WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup).

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_icq_access

Response samples

Content type
application/json
{
  • "data": {
    • "message_id": "554d2cbd-efe61da3cacb"
    },
  • "metadata": {
    • "command": "verify_icq_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate ICQ username and password

This function tests the ICQ credentials that the system uses for notifications. The system generates a unique string and includes it in the test message.

You can also review the user's ICQ message history to confirm that the server sent and received the message.

The test's success or failure depends on the following conditions:

  • Valid username and password combination.
  • Network configuration.
  • Service outages.
  • External server rate limit.

Warning:

AOL discontinued support for AIM in December 2017. This function only tests ICQ credentials, not AIM credentials.

Authorizations:
BasicAuth
query Parameters
password
required
string
Example: password=12345luggage

The ICQ account's password.

Note:

You cannot use this function to test an AIM account.

username
required
string
Example: username=username

The ICQ account.

Notes:

  • If the username value consists entirely of numbers, the system assumes that it is an ICQ account. Otherwise, the system treats the account as an AOL account.
  • You cannot use this function to test an AIM account.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_oscar_access \
  username='username' \
  password='12345luggage'

Response samples

Content type
application/json
{
  • "data": {
    • "message_id": "554d2cbd-efe61da3cacb"
    },
  • "metadata": {
    • "command": "verify_oscar_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Send Pushbullet™ access verification

This function calls the WHM API 1 send_test_pushbullet_note function with the system's specified Pushbullet™ accounts. You can specify Pushbullet accounts in the Contact Information section of WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup).

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_pushbullet_access

Response samples

Content type
application/json
{
  • "data": {
    • "results": [
      • {
        • "access_token": "123456789012345678901234567890",
        • "result": {
          • "message_id": "554d2cbd-efe61da3cacb",
          • "payload": {
            • "active": "true,",
            • "body": "This message confirms that ??hostname.example.com?? (192.168.0.20) can send a\nmessage to you via Pushbullet.\n\nThis message was sent on Tuesday, March 17, 2020 at 3:09:20 PM UTC.",
            • "created": "1584457760.74319,",
            • "direction": "self",
            • "dismissed": "false,",
            • "iden": "ABCDEFGHIJKLABCDEFGHIJKL",
            • "modified": "1584457760.74993,",
            • "receiver_email": "[email protected]",
            • "receiver_email_normalized": "[email protected]",
            • "receiver_iden": "ABCDEFGHIJKL",
            • "sender_email": "[email protected]",
            • "sender_email_normalized": "[email protected]",
            • "sender_iden": "ABCDEFGHIJKL",
            • "sender_name": "Firstname Lastname",
            • "title": "Test message (ID: J2SY)",
            • "type": "note"
            }
          }
        }
      ]
    },
  • "metadata": {
    • "command": "verify_pushbullet_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Send notification URL via POST verification

This function calls the WHM API 1 send_test_posturl function for your specified POST notification URLs. Users can specify POST notification URLs in the Contact Information section of WHM's Basic WebHost Manager Setup interface (WHM >> Home >> Server Configuration >> Basic WebHost Manager Setup).

Note:

If the Contact Information section of WHM's Basic WebHost Manager Setup interface (Home >> Server Configuration >> Basic WebHost Manager Setup) contains multiple POST URLs, the function will return an array that contains the results for each URL.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_posturl_access

Response samples

Content type
application/json
{
  • "data": {
    • "results": [
      • {
        • "result": {
          • "message_id": "88M7",
          • "payload": {
            • "content": "<!doctype html>\n<html>\n<head>\n <title>Example Domain</title>\n\n <meta charset=\"utf-8\" />\n <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n <style type=\"text/css\">\n body {\n background-color: #f0f0f2;\n margin: 0;\n padding: 0;\n font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n }\n div {\n width: 600px;\n margin: 5em auto;\n padding: 2em;\n background-color: #fdfdff;\n border-radius: 0.5em;\n box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n }\n a:link, a:visited {\n color: #38488f;\n text-decoration: none;\n }\n @media (max-width: 700px) {\n div {\n margin: 0 auto;\n width: auto;\n }\n }\n </style>\n</head>\n\n<body>\n<div>\n <h1>Example Domain</h1>\n <p>This domain is for use in illustrative examples in documents. You may use this\n domain in literature without prior coordination or asking for permission.</p>\n <p><a href=\"https://www.iana.org/domains/example\">More information...</a></p>\n</div>\n</body>\n</html>\n",
            • "headers": {
              • "connection": "keep-alive",
              • "content-length": "743",
              • "content-type": "application/json; charset=utf-8",
              • "date": "Tue, 05 May 2020 19:10:13 GMT",
              • "e-tag": "z'W/\\\"2e7-Klmw/9Djp5E2M7VZdH2LwFWXX6s\\\"\"",
              • "server": "nginx",
              • "set-cookie": "sails.sid=s%3Arpjt9JrVXDIYMxpjyUqLuCtcUxSwbEWX.6ldYuWKV2zqn%2BhmsUlAi7PtsIEd9RXI32y6gjg0gwJA; Path=/; HttpOnly",
              • "vary": "Accept-Encoding"
              },
            • "protocol": "HTTP/1",
            • "reason": "OK",
            • "status": "200",
            • "success": 1,
            • "url": "http://www.example.com"
            }
          },
        • "url": "https://postman-echo.com/post"
        }
      ]
    },
  • "metadata": {
    • "command": "verify_posturl_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Verify Slack® Webhook connection

This function verifies the connection to a Slack® WebHook. You can specify Slack accounts in the Contact Information section of WHM's Basic WebHost Manager Setup interface ( Home >> Server Configuration >> Basic WebHost Manager Setup ).

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  verify_slack_access

Response samples

Content type
application/json
{
  • "data": {
    • "results": [
      • {
        • "result": {
          • "message_id": null,
          • "payload": {
            • "content": null,
            • "headers": {
              • "access-control-allow-origin": null,
              • "content-type": null,
              • "date": null,
              • "referrer-policy": null,
              • "server": null,
              • "strict-transport-security": null,
              • "transfer-encoding": null,
              • "vary": null,
              • "x-frame-options": null,
              • "x-slack-backend": null,
              • "x-via": null
              },
            • "protocol": null,
            • "reason": null,
            • "status": null,
            • "success": null,
            • "url": null
            }
          },
        • "url": null
        }
      ]
    },
  • "metadata": {
    • "command": "verify_slack_access",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Security

The Security module for WHM API 1.

Return Security Advisor results

This function returns the cPanel Security Advisor's security scan data. It advises you of how to resolve any security issues that it finds.

Note:

For more information, read the cPanel Security Advisor documentation at the WebPros International, LLC GitHub® repository.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_security_advice

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "advice": {
          • "key": "SSH_direct_root_login_permitted",
          • "suggestion": "Manually edit /etc/ssh/sshd_config and change PermitRootLogin to “without-password” or “no”, then restart SSH …",
          • "summary": "SSH direct root logins are permitted.",
          • "type": "ADVISE_BAD"
          },
        • "module": "Cpanel::Security::Advisor::Assessors::SSH",
        • "type": "mod_advice"
        },
      • {
        • "advice": {
          • "key": "SSH_is_current",
          • "suggestion": null,
          • "summary": "Current SSH version is up to date: 11.22p33-44",
          • "type": "ADVISE_GOOD"
          },
        • "module": "Cpanel::Security::Advisor::Assessors::SSH",
        • "type": "mod_advice"
        },
      • {
        • "message": "Anvil not found at /usr/local/cpanel/Cpanel/Security/Advisor/Assessors/ACME.pm line 6.",
        • "module": "Cpanel::Security::Advisor::Assessors::ACME",
        • "type": "mod_load"
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_security_advice",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Server Nodes

Server Administration / Server Nodes

Return linked remote server node settings

This function returns details about a linked remote server node.

Authorizations:
BasicAuth
query Parameters
alias
required
string
Example: alias=example

The name of a linked remote server node.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_linked_server_node \
  alias='example'

Response samples

Content type
application/json
{
  • "data": {
    • "enabled_services": [
      • "apache_php_fpm"
      ],
    • "hostname": "example.com",
    • "last_check": 1556576165,
    • "system_settings": {
      • "Mail": {
        • "globalspamassassin": 0
        }
      },
    • "tls_verified": 1,
    • "username": "root",
    • "version": "11.86.0.0",
    • "worker_capabilities": {
      • "Mail": { }
      }
    },
  • "metadata": {
    • "command": "get_linked_server_node",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return linked server node status

This function returns the status of a linked remote server node. It returns the linked remote server's status with the WHM API 1 version and get_current_profile functions.

Authorizations:
BasicAuth
query Parameters
api_token
required
string
Example: api_token=23ZX8RA1FTE1IVJRL90MB5CREDS4UE2H

The required API token to make API calls to the remote server node.

Note:

The API token must have root-level access on the remote server node.

hostname
required
string
Example: hostname=example.com

The remote server node's hostname or IP address.

Note:

If you use an IP address, you must use the skip_tls_verification=1 parameter.

skip_tls_verification
integer
Default: 0
Possible Values: 0 1
Example: skip_tls_verification=1

Whether to skip SSL/TLS verification. The system performs this action when it queries the remote server node.

  • 1 - Skip SSL/TLS verification.
  • 0 - Do not skip SSL/TLS verification.
username
required
string
Example: username=root

The username required to make API calls to the remote server node.

Note:

The username must have root-level access on the remote server node.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_server_node_status \
  api_token='23ZX8RA1FTE1IVJRL90MB5CREDS4UE2H' \
  hostname='example.com' \
  username='root'

Response samples

Content type
application/json
{
  • "data": {
    • "enabled_services": [
      • "apache_php_fpm"
      ],
    • "remote_node_linkages": [
      • {
        • "alias": "MailNode",
        • "enabled_services": [
          • "apache_php_fpm",
          • "cpanellogd",
          • "cpdavd",
          • "cpgreylistd",
          • "cphulkd",
          • "cpsrvd",
          • "crond",
          • "dnsadmin",
          • "exim",
          • "imap",
          • "ipaliases",
          • "lmtp",
          • "mailman",
          • "mysql",
          • "named",
          • "nscd",
          • "pop",
          • "queueprocd",
          • "rsyslogd",
          • "spamd",
          • "sshd",
          • "tailwatchd"
          ],
        • "hostname": "mailnode.example.com",
        • "last_check": 1583934071,
        • "system_settings": {
          • "Mail": {
            • "globalspamassassin": "1"
            }
          },
        • "tls_verified": 0,
        • "username": "root",
        • "version": "11.90.0.0",
        • "worker_capabilities": {
          • "Mail": { }
          }
        }
      ],
    • "system_settings": {
      • "Mail": {
        • "globalspamassassin": 1
        }
      },
    • "tls_verified": 1,
    • "version": "11.90.0.0"
    },
  • "metadata": {
    • "command": "get_server_node_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all linked server nodes

This function returns a list of all remote server nodes linked to the server. It also provides details about each remote server node.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_linked_server_nodes

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "alias": "example",
        • "enabled_services": [
          • "apache_php_fpm",
          • "cpanellogd",
          • "cpdavd",
          • "cpgreylistd",
          • "cpsrvd",
          • "crond",
          • "dnsadmin",
          • "exim",
          • "ftpd",
          • "imap",
          • "ipaliases",
          • "lmtp",
          • "mailman",
          • "mysql",
          • "named",
          • "nscd",
          • "pop",
          • "postgresql",
          • "queueprocd",
          • "rsyslogd",
          • "spamd",
          • "sshd",
          • "tailwatchd"
          ],
        • "hostname": "example.com",
        • "last_check": 1556576165,
        • "tls_verified": 1,
        • "username": "root",
        • "version": "11.90.0.0",
        • "worker_capabilities": {
          • "Mail": { }
          }
        }
      ]
    },
  • "metadata": {
    • "command": "list_linked_server_nodes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel accounts with server name and type

This function returns the system's cPanel accounts and the linked cPanel & WHM server on which they exist.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_user_child_nodes

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "alias": "MailServer1",
        • "type": "Mail",
        • "user": "username1"
        }
      ]
    },
  • "metadata": {
    • "command": "list_user_child_nodes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update linked server node settings

This function updates a linked remote cPanel server node.

Important:

This function requires the use of an API token. For more information, read our Guide to API Authentication - API Tokens in WHM documentation.

Authorizations:
BasicAuth
query Parameters
alias
required
string
Example: alias=example

The name of a linked remote cPanel server node.

api_token
string
Example: api_token=23ZX8RA1FTE1IVJRL90MB5CREDS4UE2H

The API token required to make API calls to the remote cPanel server node.

This value defaults to the existing API token.

Note:

The API token must have root-level access on the remote cPanel server node.

hostname
string
Example: hostname=example.com

A new remote cPanel server node's hostname. The system will update your remote cPanel server node's hostname to this value.

This value defaults to the existing hostname.

Note:

This parameter does not accept an IP address.

skip_tls_verification
integer
Default: 1
Possible Values: 0 1
Example: skip_tls_verification=0

Whether to skip SSL/TLS verification. The system performs this action when it queries the remote cPanel server node.

Note:

If the remote cPanel server is SSL/TLS verified, you cannot skip verification.

username
string
Example: username=root

The username required to make API calls to the remote cPanel server node.

This value defaults to the existing username.

Note:

The username must have root-level access on the remote cPanel server node.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_linked_server_node \
  alias='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_linked_server_node",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Repair distributed accounts with data loss

This function converts cPanel accounts that use a given child node to use the local server instead.

Unlike the WHM API 1 modifyacct API call, this API does not transfer users’ data from the child node as part of the conversion. This API is useful for emergency repairs if, for example, a child node goes permanently offline while accounts still use it.

Warning:

Because this API does not transfer users’ data from the child node, all converted users will lose data. You should only call this API as a last resort.

Authorizations:
BasicAuth
query Parameters
node_alias
required
string
Example: node_alias=mailalias

The child node’s alias (friendly name). This is the value passed in the WHM API 1 link_server_node_with_api_token function’s alias parameter.

user
required
Array of strings
Example: user=username&user=username1

The usernames of the distributed cPanel accounts to convert.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  force_dedistribution_from_node \
  node_alias='mailalias' \
  user='username' user='username1'

Response samples

Content type
application/json
{
  • "data": {
    • "log": [
      • {
        • "contents": "Converting “username1” …",
        • "indent": 0,
        • "type": "success"
        }
      ],
    • "user_info": [
      • {
        • "username": "username1"
        }
      ]
    },
  • "metadata": {
    • "command": "force_dedistribution_from_node",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Server Profiles

Server Administration / Server Profiles

Return whether server role is enabled

This function checks whether a specific server role is currently enabled for the server.

For more information about server roles, read our How to Use Server Profiles documentation.

Authorizations:
BasicAuth
query Parameters
role
required
string
Possible Values: "CalendarContact" "DNS" "FileStorage" "FTP" "MailLocal" "MailReceive" "MailRelay" "MailSend" "MySQL" "MySQLClient" "Postgres" "PostgresClient" "SpamFilter" "WebDisk" "Webmail" "WebServer"
Example: role=FTP

The role to check. The role must be one of the following case-sensitive values:

  • CalendarContact - Allows users to access CalDAV and CardDAV services and features.

  • DNS - Allows users to create and edit Domain Name System (DNS) zone files. This role doesn’t convert your server to a cPanel DNSOnly™ server.

  • FileStorage - Allows users to access cPanel’s File Manager and Git™ Version Control features. When a profile disables this role, you can’t enable the Shell Access setting when you create a new cPanel account.

  • FTP - Allows users to manage their account’s files with an FTP client.

  • MailLocal - Allows the control of local mail delivery and related features.

  • MailReceive - Allows users to receive mail from external sources.

  • MailRelay - Allows the server’s Message Transfer Agent (MTA) to forward mail from one remote host to another.

  • MailSend - Allows users to send mail and control the features necessary for sending mail.

  • MySQL - Allows users to create and manage MySQL® or MariaDB databases.

  • MySQLClient - This role checks whether the MySQL/MariaDB client access exists locally or remotely. You cannot directly enable or disable this role. The system enables or disables this role depending on the MySQL configuration.

  • Postgres - Allows users to create and manage PostgreSQL databases if cPanel & WHM manages the server’s PostgreSQL.

  • PostgresClient - This role checks whether the PostgreSQL client access exists locally.

  • SpamFilter - Allows users to use Apache SpamAssassin™ to identify, sort, and delete unsolicited mail.

  • WebDisk - Allows users to manage their account’s files with a WebDAV client.

  • Webmail - Allows users to access webmail services and features.

  • WebServer - Allows users to create and manage websites for their domains.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  is_role_enabled \
  role='FTP'

Response samples

Content type
application/json
{
  • "data": {
    • "enabled": 1
    },
  • "metadata": {
    • "command": "is_role_enabled",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available server profiles

This function returns a list of available server profiles.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_available_profiles

Response samples

Content type
application/json
{
  • "data": {
    • "profiles": [
      • {
        • "code": "STANDARD",
        • "description": "The Standard Node profile provides all services and access to every cPanel feature.",
        • "enabled_roles": [
          • {
            • "description": "Calendars and Contacts provides CalDAV and CardDAV services.",
            • "module": "CalendarContact",
            • "name": "Calendars and Contacts"
            },
          • {
            • "description": "DNS allows users to create and edit Domain Name System zone files.",
            • "module": "DNS",
            • "name": "DNS"
            },
          • {
            • "description": "FTP allows users to manage the files associated with their site with an FTP client.",
            • "module": "FTP",
            • "name": "FTP"
            },
          • {
            • "description": "File Storage allows users to access the File Manager and Git™ Version Control features.",
            • "module": "FileStorage",
            • "name": "File Storage"
            },
          • {
            • "description": "Receive Mail allows users to receive email, as well as create and manage their email accounts.",
            • "module": "MailReceive",
            • "name": "Receive Mail"
            },
          • {
            • "description": "Send Mail allows users to send email.",
            • "module": "MailSend",
            • "name": "Send Mail"
            },
          • {
            • "description": "Local Mail allows the system to process email.",
            • "module": "MailLocal",
            • "name": "Local Mail"
            },
          • {
            • "description": "MySQL®/MariaDB allows users to create and manage MySQL/MariaDB databases.",
            • "module": "MySQL",
            • "name": "MySQL/MariaDB"
            },
          • {
            • "description": "PostgreSQL allows users to create and manage PostgreSQL databases.",
            • "module": "Postgres",
            • "name": "PostgreSQL"
            },
          • {
            • "description": "Spam Filter allows users to use Apache SpamAssassin™ to identify, sort, and delete unsolicited mail.",
            • "module": "SpamFilter",
            • "name": "Spam Filter"
            },
          • {
            • "description": "Webmail provides access to webmail services.",
            • "module": "Webmail",
            • "name": "Webmail"
            },
          • {
            • "description": "Web Disk allows users to manage and manipulate files on the server with multiple types of devices.",
            • "module": "WebDisk",
            • "name": "Web Disk"
            },
          • {
            • "description": "Web Server allows users to create and manage websites for their domains.",
            • "module": "WebServer",
            • "name": "Web Server"
            }
          ],
        • "experimental": 0
        }
      ]
    },
  • "metadata": {
    • "command": "get_available_profiles",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return server's node profile

This function returns details about the server's current cPanel & WHM server profile.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_current_profile

Response samples

Content type
application/json
{
  • "data": {
    • "code": "MAILNODE",
    • "description": "This profile provides only services and cPanel features that allow the system to serve mail.",
    • "disabled_roles": [
      • {
        • "description": "FTP allows users to manage the files associated with their site with an FTP client.",
        • "module": "FTP",
        • "name": "FTP"
        },
      • {
        • "description": "File Storage allows users to access the File Manager and Git™ Version Control features.",
        • "module": "FileStorage",
        • "name": "File Storage"
        },
      • {
        • "description": "MySQL®/MariaDB allows users to create and manage MySQL/MariaDB databases.",
        • "module": "MySQL",
        • "name": "MySQL/MariaDB"
        },
      • {
        • "description": "PostgreSQL allows users to create and manage PostgreSQL databases.",
        • "module": "Postgres",
        • "name": "PostgreSQL"
        },
      • {
        • "description": "Web Disk allows users to manage and manipulate files on the server with multiple types of devices.",
        • "module": "WebDisk",
        • "name": "Web Disk"
        },
      • {
        • "description": "Web Server allows users to create and manage websites for their domains.",
        • "module": "WebServer",
        • "name": "Web Server"
        }
      ],
    • "enabled_roles": [
      • {
        • "description": "Calendars and Contacts provides CalDAV and CardDAV services.",
        • "module": "CalendarContact",
        • "name": "Calendars and Contacts"
        },
      • {
        • "description": "Receive Mail allows users to receive email, as well as create and manage their email accounts.",
        • "module": "MailReceive",
        • "name": "Receive Mail"
        },
      • {
        • "description": "Send Mail allows users to send email.",
        • "module": "MailSend",
        • "name": "Send Mail"
        },
      • {
        • "description": "Local Mail allows the system to process email.",
        • "module": "MailLocal",
        • "name": "Local Mail"
        },
      • {
        • "description": "Webmail provides access to webmail services.",
        • "module": "Webmail",
        • "name": "Webmail"
        }
      ],
    • "experimental": 1,
    • "name": "Mail",
    • "optional_roles": [
      • {
        • "description": "DNS allows users to create and edit Domain Name System zone files.",
        • "module": "DNS",
        • "name": "DNS"
        },
      • {
        • "description": "Spam Filter allows users to use Apache SpamAssassin™ to identify, sort, and delete unsolicited mail.",
        • "module": "SpamFilter",
        • "name": "Spam Filter"
        }
      ]
    },
  • "metadata": {
    • "command": "get_current_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update server node profile

This function activates a server profile.

Note:

  • If a server profile enables a service, the system will also enable service monitoring. To disable a service's monitoring, use WHM's Service Manager interface (WHM >> Home >> Service Configuration >> Service Manager).
  • For a list of the server's available profiles, use the get_available_profiles function.
Authorizations:
BasicAuth
query Parameters
code
required
string
Possible Values: "STANDARD" "DATABASENODE" "MAILNODE" "DNSNODE"
Example: code=MAILNODE

The code value of the server profile.

  • STANDARD — The Standard profile.
  • DATABASENODE — The Database profile.
  • MAILNODE — The Mail profile.
  • DNSNODE — The DNS profile.
object
Example: optional={"DNS":0,"SpamFilter":1}

The optional roles to enable or disable with the profile, in JSON format. You must URI-encode this value.

Note:

  • As an example, if you wished to enable SpamFilter and disable DNS, the JSON object would be:

    { "SpamFilter": 1, "DNS": 0 }.

  • This parameter does not enable optional roles for profiles that do not possess any optional roles.

  • If you do not pass this parameter, the system disables a profile's optional roles, if any exist.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_profile_activation \
  code='MAILNODE'

Response samples

Content type
application/json
{
  • "data": {
    • "log_id": "17053.10418168.1533478604"
    },
  • "metadata": {
    • "command": "start_profile_activation",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Services

Server Administration / Services

Return service configuration key

This function returns a specific configuration key for a service.

Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=mail_process_size

The configuration key's name.

service
required
string
Example: service=dovecot

The service's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_service_config_key \
  service='dovecot' \
  key='mail_process_size'

Response samples

Content type
application/json
{
  • "data": {
    • "key name": "512",
    • "mail_process_size": null
    },
  • "metadata": {
    • "command": "get_service_config_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update service configuration key

This function configures global properties for specific services listed in the /var/cpanel/conf directory.

Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=mail_process_size

The configuration key's name.

  • This parameter uses the key names listed in the /var/cpanel/conf/{service}/main file, where {service} is the service's name from the service parameter.
  • This function does not support subkeys.
service
required
string
Example: service=dovecot

The service's name.

  • A list of service names exists in the /var/cpanel/conf directory.
required
string or integer
Example: value=512

The new value for the configuration key.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_service_config_key \
  service='dovecot' \
  key='mail_process_size' \
  value='512'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_service_config_key",
    • "reason": "Succeeded",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel account service proxying

This function lets you configure a cPanel account's service proxying.

Note:

  • If the cPanel account is a distributed account, and you call this function on the account’s parent node, the system will propagate the new service proxying to the child node.
  • If the Web Server role is active on the server, this function rebuilds the user's web virtual hosts (vhosts) and restarts the web server.
  • If the system cannot rebuild the user's vhosts, the API call will still succeed. However, the function returns a failure warning in the metadata.
  • To remove an account's service proxying, use the WHM API 1 unset_all_service_proxy_backends function.
Authorizations:
BasicAuth
query Parameters
string or string

The hostname or IP address to assign as the server that handles the account's service proxy requests.

This parameter defaults to the existing service proxy configuration, if one exists.

service_group
string
Value: "Mail"
Examples:
  • service_group=service-group-0=Mail&service-group-1=Mail&service-group-3=Mail - Add multiple service backend groups.
  • service_group=Mail - Add a single service backend group.

The name of a service group for which to assign a proxy backend. The corresponding service_group_backend value will be the service group's new proxy backend.

This parameter defaults to the existing setting, if one exists.

Note:

  • When you call this parameter, you must include a corresponding service_group_backend value.
  • To add multiple service_group values, increment the parameter name. For example, service_group-1, service_group-2, and service_group-3.
string or string
Examples:
  • service_group_backend=service_group_backend-1=mail.example1.com&service_group_backend-2=mail.example2.com&service_group_backend-3=mail.example3.com - Add multiple service group backend servers.
  • service_group_backend=mail.example.com - Add a single service group backend server.

The hostname or IP address of the server to assign as the corresponding service_group value's proxy backend server.

This parameter defaults to the existing setting, if one exists.

Note:

  • When you call this parameter, you must include a corresponding service_group value.
  • To add multiple service_group_backend values, increment the parameter name. For example, service_group_backend-1, service_group_backend-2, and service_group_backend-3.
username
required
string <username>
Example: username=example

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_service_proxy_backends \
  username='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_service_proxy_backends",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return service status

This function reports which services (daemons) are enabled, installed, and monitored on your server.

Authorizations:
BasicAuth
query Parameters
service
string
Example: service=crond

The service for which to view the status.

Notes

If you do not specify this parameter, the function will return the status for all of your server's services.

Available Services:

  • apache_php_fpm
  • clamd
  • cpanel-dovecot-solr
  • cpanel_php_fpm
  • cpanellogd
  • cpdavd
  • cpgreylistd
  • cphulkd
  • cpsrvd
  • crond
  • dnsadmin
  • exim
  • exim-altport
  • ftpd
  • httpd
  • imap
  • ipaliases
  • lmtp
  • mailman
  • mysql
  • named
  • nscd
  • p0f
  • pop
  • postgresql
  • queueprocd
  • rsyslogd
  • spamd
  • sshd
  • syslogd
  • tailwatchd

For more information about these services, read our Service Manager documentation.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  servicestatus

Response samples

Content type
application/json
{
  • "data": {
    • "service": [
      • {
        • "display_name": "Cron Daemon",
        • "enabled": 1,
        • "installed": 1,
        • "monitored": 1,
        • "name": "crond",
        • "running": 1
        }
      ]
    },
  • "metadata": {
    • "command": "servicestatus",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable monitoring for all services

This function enables monitoring for all enabled services.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  enable_monitor_all_enabled_services

Response samples

Content type
application/json
{
  • "data": {
    • "services": [
      • {
        • "monitored": 1,
        • "service": "cphulkd"
        }
      ]
    },
  • "metadata": {
    • "command": "enable_monitor_all_enabled_services",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable or disable a service and its monitoring

This function enables or disables a service and its monitoring.

Note:

If the user only possesses the clustering Access Control List (ACL), then this function can only act on the named service.

Authorizations:
BasicAuth
query Parameters
enabled
integer
Possible Values: 0 1
Example: enabled=1

Whether to enable the service.

  • 1 — Enable.
  • 0 — Disable.

If you do not use this parameter, the function will not change the enabled status of the service.

Warning:

Do not use this function to disable the cpsrvd service.

exim-altportnum
string
Default: 26
Example: exim-altportnum=26, 5000, 6000

A port or list of comma-separated ports on which Exim will listen for inbound connections.

Note:

The function only uses this parameter if you set exim-altport as the service parameter's value.

monitored
integer
Possible Values: 0 1
Example: monitored=1

Whether to monitor the service in WHM's Service Status interface (WHM >> Home >> Server Status >> Service Status).

  • 1 — Monitor.
  • 0 — Do not monitor.

If you do not use this parameter, the function will not change the monitoring status of the service.

service
required
string
Possible Values: "apache_php_fpm" "cpanel-dovecot-solr" "cpanel_php_fpm" "cpanellogd" "cpdavd" "cphulkd" "cpsrvd" "crond" "dnsadmin" "exim" "exim-altport" "ftpd" "httpd" "imap" "ipaliases" "lmtp" "mailman" "mysql" "named" "nscd" "p0f" "pop" "postgresql" "queueprocd" "rsyslogd" "spamd" "sshd"
Example: service=mysql

The service to configure. For more information about each service, read our Service Manager documentation.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  configureservice \
  service='mysql'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "configureservice",
    • "reason": "Enabled monitoring for mysql.",
    • "result": 1,
    • "version": 1
    }
}

Restart service

This function restarts a service, or daemon, on a server.

Note:

If the user only possesses the clustering Access Control List (ACL) then this function can only act on the named service.

Authorizations:
BasicAuth
query Parameters
queue_task
integer
Default: 0
Possible Values: 0 1
Example: queue_task=0

Whether to queue this task.

  • 1 — Queue.
  • 0 — Do not queue.

Note:

This parameter affects the output return.

service
required
string
Example: service=exim

The service to restart. For a list of possible values, read our Access Control List (ACL) documentation.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  restartservice \
  service='exim'

Response samples

Content type
application/json
{
  • "data": {
    • "output": "Waiting for httpd to restart..............finished.\\n\\nhttpd (/usr/local/apache/bin/httpd -k start -DSSL) running as root with PID 21379\\nhttpd (/usr/local/apache/bin/httpd -k start -DSSL) running as root with PID 21385\\n\\nhttpd started ok\\n",
    • "service": "exim"
    },
  • "metadata": {
    • "command": "restartservice",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update background process stopper

This function configures the server's background process killer.

Authorizations:
BasicAuth
query Parameters
processes_to_kill
required
string
Examples:
  • processes_to_kill=eggdrop-0, eggdrop-1, eggdrop-2 - Kill multiple processes.
  • processes_to_kill=eggdrop - Kill a single process.

A process to kill in the /usr/local/cpanel/etc/sym directory.

Note:

To enable the background killer for multiple processes, duplicate or increment the parameter name.

For example, processes_to_kill, processes_to_kill-0, and processes_to_kill-1.

trusted_users
string
Example: trusted_users=user

Unaffected users. If you do not specify a value, the function affects all of the users on the server.

Note:

To trust multiple users, duplicate or increment the parameter name.

For example, trusted_users, trusted_users-0, and trusted_users-1.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  configurebackgroundprocesskiller \
  processes_to_kill='eggdrop'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "configurebackgroundprocesskiller",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove cPanel account service proxying

This function removes a cPanel account's service proxying.

Note:

  • If the cPanel account is a distributed account, this function will also unset all service proxying for the cPanel account on the child node.
  • If the Web Server role is active on the server, this function rebuilds the cPanel user's web virtual hosts (vhosts) and restarts the web server.
  • If the system cannot rebuild the cPanel user's vhosts, the API call will still succeed. However, the function returns a failure warning in the metadata.
  • To set a service proxying for a cPanel account, use the WHM API 1 set_service_proxy_backends function.
Authorizations:
BasicAuth
query Parameters
username
required
string <username>
Example: username=username

The cPanel account's username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  unset_all_service_proxy_backends \
  username='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "unset_all_service_proxy_backends",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return a cPanel account’s service proxying setup

This function reports a cPanel account's service proxying configuration.

Authorizations:
BasicAuth
query Parameters
username
required
string <username>
Example: username=example

The cPanel account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_service_proxy_backends \
  username='example'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "backend": "example.com",
        • "service_group": "Mail"
        }
      ]
    },
  • "metadata": {
    • "command": "get_service_proxy_backends",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return service configuration settings

This function returns a service's configuration settings.

Authorizations:
BasicAuth
query Parameters
service
required
string
Value: "dovecot"
Example: service=dovecot

The service's name.

  • dovecot — The Dovecot service.

Note:

For a fresh install, the data returned for the Dovecot service will only contain the list of protocols. It will not be until the mailserver configuration is saved that the return data for Dovecot will look like what is shown in the example.

Responses

Response Schema: application/json
object

A list of the configuration key's settings.

object

Request samples 

whmapi1 --output=jsonpretty \
  get_service_config \
  service='dovecot'

Response samples

Content type
application/json
{
  • "data": {
    • "auth_cache_negative_ttl": 3600,
    • "auth_cache_size": "1M",
    • "auth_cache_ttl": 3600,
    • "auth_policy_hash_nonce": 91057590,
    • "compress_messages": 0,
    • "config_vsz_limit": 2048,
    • "auth_allow_cleartext": "yes",
    • "expire_trash": 0,
    • "expire_spam": 0,
    • "hulk_auth_passwd": "FAMONex4Bn9Hv1BO",
    • "include_trash_in_quota": 0,
    • "incoming_reached_quota": "bounce",
    • "ipv6": "on",
    • "lmtp_process_limit": 500,
    • "lmtp_process_min_avail": 0,
    • "lmtp_user_concurrency_limit": 4,
    • "login_max_processes_count": 50,
    • "login_process_per_connection": "no",
    • "login_process_size": 128,
    • "login_processes_count": 2,
    • "mail_process_size": 512,
    • "mdbox_rotate_interval": 0,
    • "mdbox_rotate_size": "10M",
    • "protocol_imap": {
      • "mail_max_userip_connections": 20,
      • "map_idle_notify_interval": 24
      },
    • "protocol_pop3": {
      • "mail_max_userip_connections": 3
      },
    • "protocols": "imap pop3",
    • "ssl_cipher_list": "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384",
    • "ssl_min_protocol": "TLSv1.2"
    },
  • "metadata": {
    • "command": "get_service_config",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

System Information

The Server Administration module for WHM API 1.

Return whether system needs reboot

This function determines if your system requires a reboot to apply quotas, software package updates, or kernel updates.

Important:

This function cannot detect whether your system needs a reboot if you use cPanel & WHM inside of a Linux Container (LXC).

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

An object that contains reasons why the system requires a reboot.

object
needs_reboot
integer
Possible Values: 0 1

Whether the system requires a reboot.

  • 1 — System requires a reboot.
  • 0 — System does not require a reboot.

Request samples 

whmapi1 --output=jsonpretty \
  system_needs_reboot

Response samples

Content type
application/json
{
  • "details": {
    • "kernel": {
      • "boot_version": "3.10.0-514.10.2.e17.x86_64",
      • "running_version": "3.10.0-514.10.2.e17.x86_64"
      },
    • "quota": 1,
    • "updates": {
      • "glibc": "2.17-157.el7_3.1"
      }
    },
  • "metadata": {
    • "command": "system_needs_reboot",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    },
  • "needs_reboot": 1
}

Return system load average

This function retrieves the system's load average.

Note:

The values the function returns represent a percentage of the CPU's processor capacity.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  systemloadavg

Response samples

Content type
application/json
{
  • "data": {
    • "fifteen": 0.19,
    • "five": 0.18,
    • "one": 0.17
    },
  • "metadata": {
    • "command": "systemloadavg",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update server's primary virtual host

This function sets the primary domain hosted on an IP address and web server port. The primary domain refers to the virtual host that the server returns when a visitor directly accesses the IP address.

For example, if both example1.com and example2.com are name-based virtual hosts on IP address 192.168.0.1, the primary virtual host appears when the visitor accesses the http://192.168.0.1/ location.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
servername
required
string <domain>
Example: servername=hostname.example.com

The ServerName value in Apache's VirtualHost section to set as primary for the IP address and port type.

type
string
Default: "std"
Possible Values: "std" "ssl"
Example: type=std

The type of virtual host to set as primary.

  • std — Set the primary domain for the HTTP port. Typically, port 80.
  • ssl — Set the primary domain for the HTTPS port. Typically, port 443.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_primary_servername \
  servername='hostname.example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_primary_servername",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update server's hostname

This function changes the server's hostname.

Warning:

  • Do not select a hostname that begins with www or a number, or a hostname that ends with a hyphen (-) character.
  • You must use a fully-qualified domain name (FQDN) that contains two periods (for example, hostname.example.com).
  • Do not choose a hostname that a cPanel account on your server will use.
  • Do not choose a potential service subdomain (proxy subdomain) as a hostname (for example, cpanel.example.com or whm.example.com).

Important:

If you update your hostname, the system blocks user access to cPanel's Calendars and Contacts interface (cPanel >> Home >> Email >> Calendars and Contacts).

The system restores access to this interface after the hostname update finishes. For more information, read our Interface Lock Scripts documentation.

Note:

Whenever you change the server's hostname, you must use one of the following methods:

Authorizations:
BasicAuth
query Parameters
hostname
required
string <hostname>
Example: hostname=hostname.example.com

The server's new hostname.

Important:

The server's hostname should never be identical to the domain name. For example, if the domain is example.com, you could use a hostname such as server1.example.com, but not example.com.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  sethostname \
  hostname='hostname.example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "sethostname",
    • "output": {
      • "messages": "Updating cPanel license...Done. Update succeeded.",
      • "warnings": "The hostname was already set to hostname.example.com, syncing configuration only."
      },
    • "reason": "Stopping cPHulkd during hostname change\nService “cphulkd” is already stopped.<br />\n<br />\n<span class='cpanel_output_color_bold'>Startup Log</span><br />\n <span class='cpanel_output_indent'></span><span class='cpanel_output_color_bold cpanel_output_ color_bright_yellow cpanel_output_color_on_grey6'>Warning: Journal has been rotated since unit was started. Log output is incomplete or unavailable.</span><br />\n<br />\n<span class= 'cpanel_output_color_bold okmsg'>cphulkd stopped successfully.</span><br />\nStopping MySQL during hostname change\nChanging hostname in kernel to hostname.example.com\nAltered hostname in /etc/sysconfig/network\nUpdating cPHulkd\nStarting cPHulkd\n(XID qju5cf) The “cphulkd” service is not configured.\nRestarting Exim\nWaiting for “exim” to restart ………waiting for “exim” to initialize ………finished.<br />\n<br />\n<span class='cpanel_output_color_bold'>Service Status</span><br />\n<span class='cpanel_output_indent'></span>exim (/usr/sbin/exim -ps -bd -q1h -oP /var/spool/exim/exim-daemon.pid) is running as mailnull with PID 16943 (systemd+/proc check method).<br />\n<br />\n<span class='cpanel_output_color_bold'>Startup Log</span><br />\n <span class='cpanel_output_indent'></span>Jul 29 15:03:14 hostname.example.com systemd[1]: Starting Exim is a Mail Transport Agent, which is the program that moves mail from one machine to another....<br />\n<span class='cpanel_output_indent'></span>Jul 29 15:03:14 hostname. example.com systemd[1]: Can&#39;t open PID file /var/spool/exim/exim-daemon.pid (yet?) after start: No such file or directory<br />\n<span class='cpanel_output_indent'></span>Jul 29 15:03:14 hostname.example.com systemd[1]: Started Exim is a Mail Transport Agent, which is the program that moves mail from one machine to another..<br />\n<br />\n<span class='cpanel_output_ color_bold'>Log Messages</span><br />\n<span class='cpanel_output_indent'></span>2020-07-29 15:03:14 exim 4.93 daemon started: pid=16943, -q1h, listening for SMTP on port 25 (IPv6 and IPv4) port 587 (IPv6 and IPv4) and for SMTPS on port 465 (IPv6 and IPv4)<br />\n<span class='cpanel_ output_indent'></span>2020-07-29 14:57:20 exim 4.93 daemon started: pid=16089, -q1h, listening for SMTP on port 25 (IPv6 and IPv4) port 587 (IPv6 and IPv4) and for SMTPS on port 465 (IPv6 and IPv4)<br />\n<br />\n<span class='cpanel_output_color_bold okmsg'>exim restarted successfully.</span><br />\nUpdating Apache configuration\nUpdating cPanel license...Done. Update succeeded.\nA DNS record already exists for “hostname.example.com”.\nThe system has queued the hostname changes for the DAV services.\nUsers cannot access the DAV features that use these services until\nthe system has finished updates to the hostname. After the system adjusts a\nspecific user’s database, it restores their access to the DAV services.\n\nYou will receive a notification when the system completes the update for all users.\nWaiting for “mysql” to start ……waiting for “mysql” to initialize ………finished.<br />\n<br />\n<span class='cpanel_output_color_bold'>Service Status</span><br />\n<span class='cpanel_output_indent'></span>mysqld (/usr/sbin/mysqld --daemonize --pid-file= /var/run/mysqld/mysqld.pid) is running as mysql with PID 16886 (systemd+/proc check method). <br />\n<br />\n<span class='cpanel_output_color_bold'>Startup Log</span><br />\n<span class= 'cpanel_output_indent'></span>Jul 29 15:03:10 hostname.example.com systemd[1]: Starting MySQL Server...<br />\n<span class='cpanel_output_indent'></span>Jul 29 15:03:11 hostname.example.com systemd[1]: Started MySQL Server.<br />\n<br />\n<span class='cpanel_output_color_bold'>Log Messages</span><br />\n<span class='cpanel_output_indent'></span>2020-07-29T20:03:11.894935Z 0 [Note] /usr/sbin/mysqld: ready for connections.<br />\n<span class='cpanel_output_indent'> </span>2020-07-29T20:03:09.442015Z 0 [Note] /usr/sbin/mysqld: Shutdown complete<br />\n<span class='cpanel_output_indent'></span>2020-07-29T19:57:17.010586Z 0 [Note] /usr/sbin/mysqld: ready for connections.<br />\n<br />\n<span class='cpanel_output_color_bold okmsg'>mysql started successfully.</span><br />",
    • "result": 1,
    • "version": 1
    }
}

Return server's hostname

This function retrieves the server's hostname.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  gethostname

Response samples

Content type
application/json
{
  • "data": {
    • "hostname": "hostname.example.com"
    },
  • "metadata": {
    • "command": "gethostname",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return server's drive partition information

This function retrieves the server's drive partition information.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  getdiskusage

Response samples

Content type
application/json
{
  • "data": {
    • "partition": [
      • {
        • "available": 377856,
        • "device": "/dev/vda1",
        • "disk": "vda1",
        • "filesystem": "/",
        • "inodes_available": 20575847,
        • "inodes_ipercentage": 2,
        • "inodes_total": 20970944,
        • "inodes_used": 395097,
        • "mount": "/boot",
        • "percentage": 20,
        • "total": 495844,
        • "used": 92388
        }
      ]
    },
  • "metadata": {
    • "command": "getdiskusage",
    • "reason": "Successfully retrieved disk usage",
    • "result": 1,
    • "version": 1
    }
}

Restart server

This function reboots the server.

Authorizations:
BasicAuth
query Parameters
force
integer
Default: 0
Possible Values: 0 1
Example: force=0

Whether to use a forceful reboot.

  • 1 - Use a forceful reboot.
  • 0 - Do not use a forceful reboot.

Warning:

A forceful reboot may result in data loss if active processes exist on the server.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  reboot

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "reboot",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Updates

Server Administration / Updates

Return third-party software versions

This function lists the versions of third-party software that ship with cPanel & WHM.

Authorizations:
BasicAuth
query Parameters
packages
integer
Default: 0
Possible Values: 0 1
Example: packages=1

Whether to list the server's installed RPMs in the function's cpanel_packages, ea_4_packages, and os_packages arrays.

  • 1 - List.
  • 0 - Do not list.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  installed_versions

Response samples

Content type
application/json
{
  • "data": {
    • "apache": "2.4.12",
    • "apache_php_default_version": 0,
    • "apache_php_versions": [
      • 0
      ],
    • "bind": "9.9.4-29",
    • "clamav": "0.99.2-1",
    • "cpanel_and_whm": "11.64.0.9999",
    • "cpanel_packages": [
      • "cpanel-ace-editor-1.2.6-1.cp1166.noarch",
      • "cpanel-yui-2.9.0-5.cp1136.noarch"
      ],
    • "cpanel_php": "7.2.7-4",
    • "cron": 0,
    • "cronie": "1.4.11-23",
    • "dovecot": "2.2.31 (65cde28)",
    • "ea_4_packages": [ ],
    • "easyapache": "4",
    • "exim": "4.89-2",
    • "linux_kernel": "3.10.0-327.18.2.el7.x86_64",
    • "mailman": "2.1.23-9",
    • "mariadb": 0,
    • "mariadb_build": 0,
    • "munin": 0,
    • "mysql": "5.7.61",
    • "mysql_build": "5.7.61-1",
    • "nscd": "2.17-222",
    • "openssh-server": "7.4p1-21",
    • "operating_system_name": "centos",
    • "operating_system_version": "7.2",
    • "os_packages": [
      • "ImageMagick-6.7.8.9-15.el7_2.x86_64",
      • "zsh-5.0.2-14.el7.x86_64"
      ],
    • "p0f": "3.09b-1",
    • "postgresql": 0,
    • "postgresql_build": 0,
    • "powerdns": 0,
    • "proftpd": 0,
    • "pureftpd": "1.0.45",
    • "roundcube": "1.2.4-1",
    • "rsyslog": "8.24.0-16",
    • "spamd": "3.4.2",
    • "squirrelmail": 0
    },
  • "metadata": {
    • "command": "installed_versions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update software update behavior

This function modifies a server's /etc/cpupdate.conf file. This file controls how the server handles software updates and upgrades.

Important:

You must have the root level Access Control List (ACL) privilege to execute this function.

Authorizations:
BasicAuth
query Parameters
string or string or string
Example: CPANEL=RELEASE

The cPanel & WHM installation's release tier, or a valid version number.

If you do not use this parameter, the system retains the current setting.

  • A valid cPanel & WHM version number.

  • STABLE - This version has received considerable public exposure, testing, and verification.

  • RELEASE - This version is feature-complete and well-tested. It contains all intended features and functionality.

  • CURRENT - This version is tested and verified, but it may not contain all of the proposed functionality of a release. This tier is similar to the "release candidate" tier that other publication schemes use.

  • EDGE - This version only has rudimentary testing. The features are subject to further modification. This version usually lacks official public documentation.

  • LTS - Some hosting providers do not wish to upgrade cPanel & WHM to newer major versions. This is a single cPanel & WHM version for the year-long period in which WebPros International, LLC supports it.

    If you do not set this parameter, the system retains the current setting.

New installations default to RELEASE.

string or string
Example: RPMUP=daily

The frequency with which the server updates the operating system distribution's packages each time that the /usr/local/cpanel/scripts/upcp script runs.

If you do not set this parameter, the system retains the current setting.

  • daily - Update the system packages daily.
  • manual - Update the system packages manually.
  • never - If you specify never, the server administrator must run the /usr/local/cpanel/scripts/update-packages script when they update the server's packages.
string or string
Example: SARULESUP=daily

The frequency with which the server updates Apache SpamAssassin's™ rules when the /usr/local/cpanel/scripts/upcp script runs.

If you do not set this parameter, the system retains the current setting.

  • daily - Update Apache SpamAssassin rules daily.
  • manual - Update Apache SpamAssassin rules manually.
  • never - If you specify never, the server administrator must run the /usr/local/cpanel/scripts/update-packages script when they update Apache SpamAssassin's rules.
STAGING_DIR
string
Example: STAGING_DIR=/usr/local/cpanel

The absolute directory path to the staging directory for updates.

If you do not set this parameter, the system retains the current setting.

string or string
Example: UPDATES=daily

When the system will check for updates.

If you do not set this parameter, the system retains the current setting.

  • daily - Update cPanel & WHM automatically through a cron job once every 24 hours.
  • manual - Update cPanel & WHM manually.
  • never - Do not update cPanel & WHM.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  update_updateconf

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "update_updateconf",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Save EULA acceptance

This function records acceptance of cPanel & WHM's legal terms. To do this, the function creates a touchfile in the /var/cpanel/activate/ directory.

Important:

Server owners must accept these agreements before they use cPanel & WHM.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  accept_eula

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "accept_eula",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel & WHM release tier

This function sets a cPanel & WHM server to a specified support tier.

Authorizations:
BasicAuth
query Parameters
tier
required
string
Possible Values: "edge" "current" "release" "stable" "lts"
Example: tier=current

The support tier to use.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_tier \
  tier='current'

Response samples

Content type
application/json
{
  • "data": {
    • "tier": "current"
    },
  • "metadata": {
    • "command": "set_tier",
    • "reason": "Update tier successfully changed to current",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel & WHM available versions

This function lists of each available version of cPanel & WHM, and each version's latest maintenance release. This function also lists the cPanel & WHM version for each release tier.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

A list of the latest available version of cPanel & WHM.

object

Request samples 

whmapi1 --output=jsonpretty \
  get_available_tiers

Response samples

Content type
application/json
{
  • "data": {
    • "11.30": "11.30.8.0",
    • "11.32": "11.32.7.3",
    • "11.34": "11.34.2.8",
    • "11.36": "11.36.2.12",
    • "11.38": "11.38.2.23",
    • "11.40": "11.40.1.22",
    • "11.42": "11.42.1.31",
    • "11.44": "11.44.3.5",
    • "11.46": "11.46.4.0",
    • "11.48": "11.48.5.3",
    • "11.50": "11.50.6.2",
    • "11.52": "11.52.6.6",
    • "11.54": "11.54.0.36",
    • "11.56": "11.56.0.52",
    • "11.58": "11.58.0.52",
    • "11.60": "11.60.0.48",
    • "11.62": "11.62.0.48",
    • "11.64": "11.64.0.42",
    • "11.66": "11.66.0.35",
    • "11.68": "11.68.0.39",
    • "11.70": "11.70.0.69",
    • "11.72": "11.72.0.12",
    • "11.74": "11.74.0.12",
    • "11.76": "11.76.0.22",
    • "11.78": "11.78.0.49",
    • "11.80": "11.80.0.24",
    • "11.82": "11.82.0.19",
    • "11.84": "11.84.0.22",
    • "11.86": "11.86.0.24",
    • "11.88": "11.88.0.13",
    • "11.90": "11.90.0.3",
    • "current": "11.90.0.3",
    • "edge": "11.90.0.3",
    • "lts": "11.86.0.24",
    • "release": "11.88.0.13",
    • "stable": "11.88.0.13"
    },
  • "metadata": {
    • "command": "get_available_tiers",
    • "reason": "Got tiers list",
    • "result": 1,
    • "version": 1
    }
}

Update cPanel & WHM update frequency

This function sets the frequency of cPanel & WHM updates.

Authorizations:
BasicAuth
query Parameters
updates
required
string
Possible Values: "daily" "manual" "never"
Example: updates=daily

The frequency with which to run cPanel & WHM updates on a server.

  • daily — Run updates daily.
  • manual — Run updates manually.
  • never — Never run updates.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  set_cpanel_updates \
  updates='daily'

Response samples

Content type
application/json
{
  • "data": {
    • "updates": "daily"
    },
  • "metadata": {
    • "command": "set_cpanel_updates",
    • "reason": "Cpanel update frequency set to daily",
    • "result": 1,
    • "version": 1
    }
}

Return Long Term Support status for all versions

This function parses the /etc/cpanel/TIERS.json file and returns whether a branch qualifies for Long-Term Support (LTS). For more information about LTS, read our cPanel Long-Term Support documentation.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_lts_wexpire

Response samples

Content type
application/json
{
  • "data": {
    • "branch": {
      • "11.78.0": [
        • {
          • "build": "11.78.0.49",
          • "is_main": 1
          }
        ],
      • "11.80.0": [
        • {
          • "build": "11.80.0.24",
          • "is_main": 1
          }
        ],
      • "11.82.0": [
        • {
          • "build": "11.82.0.19",
          • "is_main": 1
          }
        ],
      • "11.84.0": [
        • {
          • "build": "11.84.0.22",
          • "is_main": 1
          }
        ],
      • "11.86.0": [
        • {
          • "build": "11.86.0.25",
          • "is_main": 1
          }
        ],
      • "11.88.0": [
        • {
          • "build": "11.88.0.14",
          • "is_main": 1
          }
        ],
      • "11.90.0": [
        • {
          • "build": "11.90.0.5",
          • "is_main": 1
          }
        ]
      },
    • "flags": {
      • "is_main": 1
      },
    • "tiers": {
      • "11.78": [
        • {
          • "build": "11.78.0.49",
          • "expires": "1588636799",
          • "is_lts": 1,
          • "is_main": 1
          }
        ],
      • "11.80": [
        • {
          • "build": "11.80.0.24",
          • "is_main": 1
          }
        ],
      • "11.82": [
        • {
          • "build": "11.82.0.19",
          • "is_main": 1
          }
        ],
      • "11.84": [
        • {
          • "build": "11.84.0.22",
          • "is_main": 1
          }
        ],
      • "11.86": [
        • {
          • "build": "11.86.0.25",
          • "expires": "1617148801",
          • "is_lts": 1,
          • "is_main": 1,
          • "named": [
            • "lts"
            ]
          }
        ],
      • "11.88": [
        • {
          • "build": "11.88.0.13",
          • "is_main": 0,
          • "named": [
            • "stable"
            ]
          },
        • {
          • "build": "11.88.0.14",
          • "is_main": 1
          }
        ],
      • "11.90": [
        • {
          • "build": "11.90.0.5",
          • "is_main": 1,
          • "named": [
            • "current",
            • "edge",
            • "release"
            ]
          }
        ]
      }
    },
  • "metadata": {
    • "command": "get_lts_wexpire",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return if server uses the default update version

This function checks whether your server uses the latest version of cPanel & WHM for your release tier.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_update_availability

Response samples

Content type
application/json
{
  • "data": {
    • "current_version": "88.0.12",
    • "newest_version": "88.0.12",
    • "tier": "current",
    • "update_available": 0
    },
  • "metadata": {
    • "command": "get_update_availability",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return Long Term Support expiration status

This function determines whether a branch's Long-Term Support (LTS) version expires within three months. For more information about LTS, read our cPanel Long-Term Support documentation.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_current_lts_expiration_status

Response samples

Content type
application/json
{
  • "data": {
    • "expiration": 1585612801,
    • "expires_in_next_three_months": 0,
    • "full_version": "11.88.1.11"
    },
  • "metadata": {
    • "command": "get_current_lts_expiration_status",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start cPanel & WHM update

This function starts an update of cPanel & WHM.

Authorizations:
BasicAuth
query Parameters
mode
string or null
Default: null
Possible Values: "force" "sync"
Example: mode=force

The cPanel & WHM update’s mode of operation.

  • null — Only reinstall cPanel & WHM if a newer version is available.
  • force — Force a reinstall of cPanel & WHM, even if the system is up to date.
  • sync — Update the currently-installed version of cPanel & WHM instead of downloading a newer version. This ensures the current version installed has the correct files.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 start_cpanel_update

Response samples

Content type
application/json
{
  • "data": {
    • "is_new": 1,
    • "log_path": "/var/cpanel/updatelogs/update.1604521159.log",
    • "pid": 23456
    },
  • "metadata": {
    • "command": "start_cpanel_update",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update Feature Showcase

This function lists and manages items in the Feature Showcase.

Note:

  • This function's output changes, depending on which value you pass to the action parameter.
  • The example in this document displays the function's return when the action parameter value is info.
Authorizations:
BasicAuth
query Parameters
action
required
string
Possible Values: "info" "list" "enable" "disable"
Example: action=info

The function's action.

  • info — List full details for all available features.
  • list — List the feature IDs for all available features.
  • enable — Enable the feature or features called in the features parameter.
  • disable — Disable the feature or features called in the features parameter.
features
string
Example: features=features_example1

The feature's ID.

Note:

You must use this parameter if you pass the enable or disable value for the action parameter.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  manage_features \
  action='info'

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "manage_features",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel & WHM version

This function returns the cPanel & WHM version that a server runs.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  version

Response samples

Content type
application/json
{
  • "data": {
    • "version": "11.88.0.9999"
    },
  • "metadata": {
    • "command": "version",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

ServicesCluster

ServicesCluster

Auto-Generated Certificates

SSL Certificates / Auto-Generated Certificates

Disable AutoSSL for domain

This function disables AutoSSL for an account's specified domains.

Authorizations:
BasicAuth
query Parameters
domain
required
Array of strings <domain> [ items <domain > ]
Examples:
  • domain=example.com&domain=example1.com&domain=example2.com - Disable AutoSSL for multiple domains.
  • domain=example.com - Disable AutoSSL for a single domain.

Disable AutoSSL for this domain.

Note:

To disable AutoSSL for multiple domains, increment the parameter name. For example, domain=example.com, domain-1=example1.com, and domain-2=example.com.

username
required
string <username>
Example: username=example

The cPanel user's account.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  add_autossl_user_excluded_domains \
  username='example' \
  domain='example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "add_autossl_user_excluded_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable AutoSSL

This function disables the AutoSSL feature.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  disable_autossl

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "disable_autossl",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return AutoSSL check script cron entry

This function returns the cron entry for the autossl_check.pl AutoSSL certificate check script.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_check_schedule

Response samples

Content type
application/json
{
  • "data": {
    • "cron": [
      • "54 1 * * *"
      ],
    • "next_time": "2016-06-09T06:00:00.000Z"
    },
  • "metadata": {
    • "command": "get_autossl_check_schedule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return AutoSSL log files

This function lists the AutoSSL feature's log files.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_logs_catalog

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "in_progress": 1,
        • "provider": "cPanel",
        • "start_time": "2016-06-09T14:25:37.000Z",
        • "username": "username"
        }
      ]
    },
  • "metadata": {
    • "command": "get_autossl_logs_catalog",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return AutoSSL log file's contents

This function returns the contents of an AutoSSL log file.

Authorizations:
BasicAuth
query Parameters
start_time
required
string <ISO-8601 Date Time>
Example: start_time=2016-06-09T14:25:37Z

When the system created the log file.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_log \
  start_time='2016-06-09T14:25:37Z'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "contents": "This system has AutoSSL set to use cPanel (powered by Sectigo).",
        • "indent": 0,
        • "partial": 0,
        • "pid": 29189,
        • "timestamp": "2016-06-09T14:25:37Z",
        • "type": "out"
        }
      ]
    },
  • "metadata": {
    • "command": "get_autossl_log",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return current user's AutoSSL metadata

This function retrieves values for the currently authenticated user's AutoSSL's metadata keys.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_metadata

Response samples

Content type
application/json
{
  • "data": {
    • "payload": {
      • "clobber_externally_signed": 1,
      • "notify_autossl_expiry": 1,
      • "notify_autossl_expiry_coverage": 1,
      • "notify_autossl_expiry_coverage_user": 1,
      • "notify_autossl_expiry_user": 1,
      • "notify_autossl_renewal": 1,
      • "notify_autossl_renewal_coverage": 1,
      • "notify_autossl_renewal_coverage_reduced": 1,
      • "notify_autossl_renewal_coverage_reduced_user": 1,
      • "notify_autossl_renewal_coverage_user": 0,
      • "notify_autossl_renewal_uncovered_domains": 1,
      • "notify_autossl_renewal_uncovered_domains_user": 1,
      • "notify_autossl_renewal_user": 1
      }
    },
  • "metadata": {
    • "command": "get_autossl_metadata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all AutoSSL-excluded domains

This function lists an account's domains the system excludes from AutoSSL.

Authorizations:
BasicAuth
query Parameters
username
required
string <username>
Example: username=example

The cPanel user's account.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_user_excluded_domains \
  username='example'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "excluded_domain": "cpcalendars.example.com"
        }
      ]
    },
  • "metadata": {
    • "command": "get_autossl_user_excluded_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available AutoSSL providers

This function lists available AutoSSL providers on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_providers

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "display_name": "Sectigo",
        • "enabled": 1,
        • "module_name": "cPanel",
        • "specs": {
          • "AVERAGE_DELIVERY_TIME": 120,
          • "DCV_METHODS": [
            • "http",
            • "dns"
            ],
          • "DELIVERY_METHOD": "queue",
          • "HTTP_DCV_MAX_REDIRECTS": 0,
          • "MAX_DOMAINS_PER_CERTIFICATE": 1000,
          • "RATE_LIMIT_CERTIFICATES_PER_REGISTERED_DOMAIN_PER_WEEK": 0,
          • "SUPPORTS_ANCESTOR_DCV": 1,
          • "SUPPORTS_WILDCARD": 0,
          • "VALIDITY_PERIOD": 7776000
          }
        },
      • {}
      ]
    },
  • "metadata": {
    • "command": "get_autossl_providers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start cPanel account AutoSSL check

This function performs an AutoSSL certificate check in the background for a cPanel user.

Authorizations:
BasicAuth
query Parameters
username
required
string
Example: username=example

The cPanel username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_autossl_check_for_one_user \
  username='example'

Response samples

Content type
application/json
{
  • "data": {
    • "pid": 12345
    },
  • "metadata": {
    • "command": "start_autossl_check_for_one_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove AutoSSL for domain

This function enables AutoSSL for an account's specified domains.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Examples:
  • domain=domain-1=cpcalendars.example.com&domain-2=cpcontacts.example.com - Enable AutoSSL for multiple domains.
  • domain=cpcalendars.example.com - Enable AutoSSL for a single domain.

Enable AutoSSL for this domain.

Note:

For multiple domains, increment the parameter name. For example, domain-1, domain-2, and domain-3.

username
required
string <username>
Example: username=username

The cPanel user's account.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  remove_autossl_user_excluded_domains \
  username='username' \
  domain='cpcalendars.example.com'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "remove_autossl_user_excluded_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Restore AutoSSL registration

This function resets the AutoSSL registration with a remote AutoSSL provider.

Authorizations:
BasicAuth
query Parameters
provider
required
string
Example: provider=cPanel

The AutoSSL provider's name.

x_*
string
Example: x_*=(varies)

Additional parameters which you wish to pass to the AutoSSL provider.

Note:

These additional parameters begin with the x_ prefix. For example, the Let's Encrypt provider accepts the x_terms_of_service_accepted parameter, to which you would pass the URL of the terms of service that you accept.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  reset_autossl_provider \
  provider='cPanel'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "reset_autossl_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update AutoSSL metadata

This function sets values for AutoSSL's metadata keys. This allows you to replace certificates that AutoSSL did not issue and toggle other AutoSSL notifications.

Note:

We recommend that you use the WHM API 1 set_autossl_metadata_key function instead.

Information:

  • You can enter more than one key and value pair in the metadata_json JSON hash.
  • Any keys that you do not explicitly define will adopt the system's default value.
Authorizations:
BasicAuth
query Parameters
required
object
Example: metadata_json={"clobber_externally_signed":1,"notify_autossl_expiry":1,"notify_autossl_expiry_coverage":1,"notify_autossl_expiry_coverage_user":1,"notify_autossl_expiry_user":1,"notify_autossl_renewal":1,"notify_autossl_renewal_coverage":1,"notify_autossl_renewal_coverage_reduced":1,"notify_autossl_renewal_coverage_reduced_user":1,"notify_autossl_renewal_coverage_user":1,"notify_autossl_renewal_uncovered_domains":1,"notify_autossl_renewal_uncovered_domains_user":1,"notify_autossl_renewal_user":1}

JSON-encoded object of metadata keys and values that control AutoSSL's behavior.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_autossl_metadata \
  metadata_json='{"clobber_externally_signed":"1","notify_autossl_expiry":"1","notify_autossl_expiry_coverage":"1","notify_autossl_expiry_coverage_user":"1","notify_autossl_expiry_user":"1","notify_autossl_renewal":"1","notify_autossl_renewal_coverage":"1","notify_autossl_renewal_coverage_reduced":"1","notify_autossl_renewal_coverage_reduced_user":"1","notify_autossl_renewal_coverage_user":"1","notify_autossl_renewal_uncovered_domains":"1","notify_autossl_renewal_uncovered_domains_user":"1","notify_autossl_renewal_user":"1"}'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_autossl_metadata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update AutoSSL metadata via JSON

This function sets values for AutoSSL's metadata keys. This allows you to replace certificates that AutoSSL did not issue and toggle other AutoSSL notifications.

Note:

  • This function performs the same actions as the WHM API 1 set_autossl_metadata function. However, this function accepts a single key and value pair as a parameter instead of JSON. Additionally, you can only enter one key and value pair per function call.
  • This function only accepts a single key and value pair. To set all values, use the WHM API 1 set_autossl_metadata function or make multiple calls to this function.
Authorizations:
BasicAuth
query Parameters
key
required
string
Possible Values: "clobber_externally_signed" "notify_autossl_expiry" "notify_autossl_expiry_coverage" "notify_autossl_expiry_coverage_user" "notify_autossl_renewal" "notify_autossl_renewal_user" "notify_autossl_renewal_coverage" "notify_autossl_renewal_coverage_user" "notify_autossl_renewal_coverage_reduced" "notify_autossl_renewal_coverage_reduced_user" "notify_autossl_renewal_uncovered_domains" "notify_autossl_renewal_uncovered_domains_user"
Example: key=notify_autossl_expiry

The AutoSSL metadata key that you wish to modify.

  • clobber_externally_signed — Whether to allow AutoSSL to replace certificates that none of this system’s AutoSSL modules issued. When you enable this option, AutoSSL will install certificates that replace users’ Certificate Authority (CA) issued certificates if they are invalid or expire within three days.
  • notify_autossl_expiry — Whether to send a notification when an AutoSSL certificate expires. This occurs when AutoSSL cannot request a new certificate.
  • notify_autossl_expiry_coverage — Whether to send a notification if at least one currently-secured domain will lose coverage when the certificate renews.
  • notify_autossl_expiry_coverage_user — Whether to send a notification if at least one currently-secured domain for a user will lose coverage when the certificate renews.
  • notify_autossl_renewal — Whether to send a notification when AutoSSL successfully renews a certificate.
  • notify_autossl_renewal_user — Whether to send a notification when AutoSSL successfully renews a certificate for a user.
  • notify_autossl_renewal_coverage — Whether to send a notification when a currently-secured domain fails DCV and the certificate has not reached its renewal period.
  • notify_autossl_renewal_coverage_user — Whether to send a notification when a user's currently-secured domain fails DCV and the certificate has not reached its renewal period.
  • notify_autossl_renewal_coverage_reduced — Whether to send a notification when AutoSSL has renewed a certificate, but the new certificate lacks at least one domain that the previous certificate secured.
  • notify_autossl_renewal_coverage_reduced_user — Whether to send a notification when AutoSSL has renewed a certificate for a user, but the new certificate lacks at least one domain that the previous certificate secured.
  • notify_autossl_renewal_uncovered_domains — Whether to send a notification when AutoSSL has renewed a certificate, but the new certificate lacks one or more of the website’s domains.
  • notify_autossl_renewal_uncovered_domains_user — Whether to send a notification when AutoSSL has renewed a certificate, but the new certificate lacks one or more of the website’s domains.
value
required
integer
Possible Values: 0 1
Example: value=1

Whether to allow AutoSSL to replace certificates that it did not issue for the clobber_externally_signed parameter.

or

Whether to send a notification for the notify_autossl_expiry, notify_autossl_expiry_coverage, notify_autossl_expiry_coverage_user, notify_autossl_renewal, notify_autossl_renewal_user, notify_autossl_renewal_coverage, notify_autossl_renewal_coverage, notify_autossl_renewal_coverage_reduced, notify_autossl_renewal_coverage_reduced_user, notify_autossl_renewal_uncovered_domains, and notify_autossl_renewal_uncovered_domains_user parameters.

  • 1 — Allow or notify.
  • 0 — Do not allow or notify.

Note:

For reference, the system preconfigures AutoSSL metadata keys to the following values:

  • The value for clobber_externally_signed defaults to 0.
  • The value for notify_autossl_expiry defaults to 1.
  • The value for notify_autossl_expiry_coverage defaults to 1.
  • The value for notify_autossl_expiry_coverage_user defaults to 1.
  • The value for notify_autossl_renewal defaults to 1.
  • The value for notify_autossl_renewal_user defaults to 1.
  • The value for notify_autossl_renewal_coverage defaults to 1.
  • The value for notify_autossl_renewal_coverage_user defaults to 1.
  • The value for notify_autossl_renewal_coverage_reduced defaults to 1.
  • The value for notify_autossl_renewal_coverage_reduced_user defaults to 1.
  • The value for notify_autossl_renewal_uncovered_domains defaults to 1.
  • The value for notify_autossl_renewal_uncovered_domains_user defaults to 1.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_autossl_metadata_key \
  key='notify_autossl_expiry' \
  value='1'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_autossl_metadata_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable AutoSSL for domain

This function disables AutoSSL for a specific domain on an account.

Warning:

This function replaces the list of any previously-excluded domains. To add a domain to the list of the user's excluded domains, use the add_autossl_user_excluded_domains function.

Authorizations:
BasicAuth
query Parameters
domain
string <domain>
Examples:
  • domain=domain=example.com&domain-1=example1.com&domain-2=example2.com - Multiple domains
  • domain=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains
  • domain=example.com - A single domain.

Disable AutoSSL for this domain. If you do not include this parameter, the system will enable AutoSSL for every domain on the account.

Note

To disable AutoSSL for multiple domains, duplicate or increment the parameter name. For example, to exclude three domains, you could:

  • Use the domain parameter multiple times.
  • Use the domain, domain-1, and domain-2 parameters.
username
required
string <username>
Example: username=example

The cPanel user's account.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_autossl_user_excluded_domains \
  username='example'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_autossl_user_excluded_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update the AutoSSL provider

This function sets the provider that the AutoSSL feature uses.

Note:

To disable AutoSSL, call WHM API 1's disable_autossl function.

Authorizations:
BasicAuth
query Parameters
provider
required
string
Example: provider=cPanel

The AutoSSL provider's name. For example:

  • cPanel
  • LetsEncrypt
x_*
string
Example: x_*=(varies)

Additional parameters which you wish to pass to the AutoSSL provider.

Note:

These additional parameters begin with the x_ prefix. For example, the Let's Encrypt provider accepts the x_terms_of_service_accepted parameter, to which you would pass the URL of the terms of service that you accept.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  set_autossl_provider \
  provider='cPanel'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "set_autossl_provider",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start AutoSSL check for all cPanel accounts

This function performs an AutoSSL certificate check in the background for all cPanel users that have the feature enabled.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_autossl_check_for_all_users

Response samples

Content type
application/json
{
  • "data": {
    • "pid": 29193
    },
  • "metadata": {
    • "command": "start_autossl_check_for_all_users",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

cPanel Account Settings

SSL Certificates / cPanel Account Settings

Return SSL certificate information

This function retrieves information about a certificate.

Authorizations:
BasicAuth
query Parameters
id
required
string
Example: id=example_com_bf638_f81af_1500191700_79e34f42c83f748bd49474ab9d66f7cd

The certificate's internal system ID.

user
required
string <username>
Example: user=username

The cPanel account's username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetchcrtinfo \
  user='username' \
  id='example_com_bf638_f81af_1500191700_79e34f42c83f748bd49474ab9d66f7cd'

Response samples

Content type
application/json
{
  • "data": {
    • "cabundle": "-----BEGIN CERTIFICATE-----\nMIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/MSQwIgYDVQQK\nExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMTDkRTVCBSb290IENBIFgzMB4X\nDTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0NlowSjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxl\ndCdzIEVuY3J5cHQxIzAhBgNVBAMTGkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkq\nhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnNMM8FrlLke3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4\nS0EFq6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8SMx+yk13\nEiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0Z8h/pZq4UmEUEz9l6YKH\ny9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWAa6xK8xuQSXgvopZPKiAlKQTGdMDQMc2P\nMTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj/PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIDAQAB\no4IBfTCCAXkwEgYDVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEE\nczBxMDIGCCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNvbTA7\nBggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9kc3Ryb290Y2F4My5w\nN2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAwVAYDVR0gBE0wSzAIBgZngQwBAgEw\nPwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcCARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNy\neXB0Lm9yZzA8BgNVHR8ENTAzMDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9P\nVENBWDNDUkwuY3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF\nAAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJouM2VcGfl96S8\nTihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/wApIvJSwtmVi4MFU5aMqrSDE\n6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwuX4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPM\nTZ+sOPAveyxindmjkW8lGy+QsRlGPfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M\n+X+Q7UNKEkROb3N6KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==\n-----END CERTIFICATE-----",
    • "certificate": "-----BEGIN CERTIFICATE-----\nMIIGeDCCBWCgAwIBAgISAxs2uBW3Q2TrGS/aRjTFh90EMA0GCSqGSIb3DQEBCwUAMEoxCzAJBgNV\nBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQDExpMZXQncyBFbmNyeXB0IEF1\ndGhvcml0eSBYMzAeFw0xNzA0MTcwNzU1MDBaFw0xNzA3MTYwNzU1MDBaMCUxIzAhBgNVBAMTGm9u\nZWFkYXl1bnRpbHRoZWRheWlkaWUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nv2OGaQw5oeg2hy0LqfYlBoncBPqElkTfZGqY/2WHoKr5TawPqOlsrLzx17946KGxLs0A3J1rRpi9\nOqrHdv69tj2pFRFC1USjlQmWnUi3h//aTYFNrfDmG+lNWZQ3ALCveTQXYIAvbmwLSPxh6wdtEmU0\nGjbqDNxsI8GSrZcJ543PSTXYFvp7S1yBNSn64S5QB8WeNkLGyF0G+ieXbCJo5neJrNh6+6U+x7mT\n/VBsQDOFOMIskjKo1q56+/elzgSi6lZ5w9IXuQRB3YbbWzCC/kFmzEB/NTe9R5v1AEzdcNwWXpfi\nvlrNIktLQDYIRyHqtyrXl3uR8fvmoYf0ll+BrwIDAQABo4IDezCCA3cwDgYDVR0PAQH/BAQDAgWg\nMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAMBgNVHRMBAf8EAjAAMB0GA1UdDgQWBBQW\ns0hUTrAJo+db1I2D9K2Aa2O3STAfBgNVHSMEGDAWgBSoSmpjBH3duubRObemRWXv86jsoTBwBggr\nBgEFBQcBAQRkMGIwLwYIKwYBBQUHMAGGI2h0dHA6Ly9vY3NwLmludC14My5sZXRzZW5jcnlwdC5v\ncmcvMC8GCCsGAQUFBzAChiNodHRwOi8vY2VydC5pbnQteDMubGV0c2VuY3J5cHQub3JnLzCCAYMG\nA1UdEQSCAXowggF2giFjcGFuZWwub25lYWRheXVudGlsdGhlZGF5aWRpZS5jb22CH21haWwub25l\nYWRheXVudGlsdGhlZGF5aWRpZS5jb22CHm1wMy5vbmVhZGF5dW50aWx0aGVkYXlpZGllLmNvbYIa\nb25lYWRheXVudGlsdGhlZGF5aWRpZS5jb22CIXJhbmRvbS5vbmVhZGF5dW50aWx0aGVkYXlpZGll\nLmNvbYIid2ViZGlzay5vbmVhZGF5dW50aWx0aGVkYXlpZGllLmNvbYIid2VibWFpbC5vbmVhZGF5\ndW50aWx0aGVkYXlpZGllLmNvbYIed2htLm9uZWFkYXl1bnRpbHRoZWRheWlkaWUuY29tgiJ3d3cu\nbXAzLm9uZWFkYXl1bnRpbHRoZWRheWlkaWUuY29tgh53d3cub25lYWRheXVudGlsdGhlZGF5aWRp\nZS5jb22CJXd3dy5yYW5kb20ub25lYWRheXVudGlsdGhlZGF5aWRpZS5jb20wgf4GA1UdIASB9jCB\n8zAIBgZngQwBAgEwgeYGCysGAQQBgt8TAQEBMIHWMCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxl\ndHNlbmNyeXB0Lm9yZzCBqwYIKwYBBQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5\nIGJlIHJlbGllZCB1cG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSBpbiBhY2NvcmRhbmNl\nIHdpdGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNlbmNyeXB0\nLm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAbfVset/dZ+ru/K2DMa2Od4pCnRYa\nLDREL7TyAWHjHq2fHK1WbzlO9zHis+C0ezB6QBPMnrGDZns/v1njGp1gASly1pqgAsytbQdPbfHv\n/Bx1HRWywniAKSRYFxrc3k3ThrSZxDj+A9mt0znNDNUvRNuP5dGFmQzFACykgNJ58yCeUJZkD78p\n7UjpbpzxWW2m6MHlHu7dDcCwSXpCa6uE4V9TeVs3OSo42C+ZlGH2x3GeZYlOZENmG2nFw0mQFSIW\nATyQuv1Jlc7tiUGmY9o13teTN4YLColMk037Rrwb/mne3ORCPB0k7QtPtzHnCdnRio2NvwZkPXzL\nbioRoW0dQg==\n-----END CERTIFICATE-----",
    • "is_self_signed": 0,
    • "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAv2OGaQw5oeg2hy0LqfYlBoncBPqElkTfZGqY/2WHoKr5TawP\nqOlsrLzx17946KGxLs0A3J1rRpi9OqrHdv69tj2pFRFC1USjlQmWnUi3h//aTYFN\nrfDmG+lNWZQ3ALCveTQXYIAvbmwLSPxh6wdtEmU0GjbqDNxsI8GSrZcJ543PSTXY\nFvp7S1yBNSn64S5QB8WeNkLGyF0G+ieXbCJo5neJrNh6+6U+x7mT/VBsQDOFOMIs\nkjKo1q56+/elzgSi6lZ5w9IXuQRB3YbbWzCC/kFmzEB/NTe9R5v1AEzdcNwWXpfi\nvlrNIktLQDYIRyHqtyrXl3uR8fvmoYf0ll+BrwIDAQABAoIBAG6cIm5LtnMwNXNi\nQT91Fmj0+8eU0VPXchQi11GjaAMfTP3q1xIT9c7PVCYQbtxjtncJ29mk0P73/0UM\ntkK7bwEIGdQnKa0AAlp8NCOqhwd+grgQZsiEVTkEWMPQuQkZFBDEXk5TRxZWMx93\nXU/r9smO29HasuHD8mun0BGrHPpJJm6JE8iMT9wIrr4pYb5TLtXtO/yQ5rxsT5uB\nbmuXAHZ51brj+aIdjrYNAVYHPvVDAjs7aHgKjbLvJ7DJPJKSbkbAEYKqT7lyQO5x\nGtLk1K5qKNHc1sFyybBF/LO1Tn7xTMbSuKce/AUvgE76RZ0nkvCD/kY1l3WBH2ns\nYFsojsECgYEA7UgMJgoKnerhmG/mnZqPUXb78PVgZmt0zmlAYRAcLc8K19xPKVOK\nz4HcDmfkPdkpsdp1YXJ6K/ueJOXq0aCFh2E+uYyqvsMQDFp72poxUPPlJ5zoj3jG\n6N9owoV2CuWX0QbhsE4/Hu5sVjBdE8WuqBBUqKp6602YV8YrA018bSkCgYEAznyq\nLhQujrpeqlN/HRhpNne5r5D8F4wQSZmFP9eRP1pnO2TQqY/wXJgOMKT20CcqwiiY\noVuOmQs1W3dz/MlWHanRKL5cIcF26Pgsp1jimD13JwPU/7nH4+CzJmkXGSHbNmQf\n2wvjv+jni2PbTZ5sotESziaJAdbcRAdg39KnexcCgYEAj086dycNbn9ULZs4L+wP\nr2YrmEa7KGCyNZCAH595RXmM1P7smMsqRVXrMJAy29/zPMXyqx5XB4V66FIs1tsa\nir+DANIitgBeCvgDYe5K5tfHiXtNQonxqOh1/zZYKxCr9sUvPiqkGOxrZkrjjHOS\nn1Ltrsj4YHGHF0xK4j3EbrECgYB403ANqJeZwyqTxmoST295hNNuDYvGB5qcRq43\nLl/6z16q3ZJQNj7zH7Ll+hHGubSGipTNjrLBkVJ2pE6FtBalIvKWQdXNltSK/HW8\nswFdDlKDzPU9cquqB5ktN79hYHNSv4H4fluVt6aN5S+1mqd9GpRDdz8iiWS4lgy0\nzCJenwKBgQC61u/GsjGx4yv0c3KJHgrpIroo3HYsamAdjJBfgBGKxrxVO5J7dbvd\n84UYzp+a0XNjazMxx5rEbU3HjKV5nsHjU+Eoqpz/vwfRqbC7mqINrRQoBKtEhuOY\n+xd6W+i58dOPv7PmgxPegmZ4Fo+jHx+mNLv9L+27JPMBRwRWUxH5TQ==\n-----END RSA PRIVATE KEY-----",
    • "subject.commonName_ip": "192.0.2.0"
    },
  • "metadata": {
    • "command": "fetchcrtinfo",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account SSL certificate information

This function retrieves information about SSL certificates that you could install for a user. This function does not provide information about the currently installed certificates.

Authorizations:
BasicAuth
query Parameters
crtdata
string
Example: crtdata=-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIFAhQDowAwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL\nZXhhbXBsZS5jb20wHhcNMTkxMTExMjAzNzUzWhcNMjAxMTEwMjAzNzUzWjAWMRQw\nEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAK31N5qqd4BhMRm318tt7CP3thvJ9nXv5j3Hks8bfNggAgBmWwh/iGEoyB0e\nmKmFkomXYQejSCkFmwI5/I+H53LA1UrnWURAHaY8UCJMMeCe22E9fbmASNMhcnov\n/AOYBl3kEWEkKVBN3dQZFsWzj+PTTui1zHl8nrr1POPLZMS+t8D3HppNoUBwBkKR\nQ/MetqCaQ3HlgbknMi0/5DbuaV0GJNbXNX9uhnGqQFUI21sEVU4xcvtEDN88dT1d\nx5EhLXobDV/brXgFm85QK/lZt3aWlIJLs/WJJSK+152PO3HhfoHpkx+JflMYoev5\nLauXhZGYXCEG8sBLa2PPH9WlpgcCAwEAAaOByzCByDAdBgNVHQ4EFgQU/Vx4Cer1\nmY3SaijxdCsA2Jo7q84wCQYDVR0TBAIwADBCBgNVHSMEOzA5gBT9XHgJ6vWZjdJq\nKPF0KwDYmjurzqEapBgwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb22CBQIUA6MAMB0G\nA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjA5BgNVHREEMjAwggtleGFtcGxl\nLmNvbYIQbWFpbC5leGFtcGxlLmNvbYIPd3d3LmV4YW1wbGUuY29tMA0GCSqGSIb3\nDQEBCwUAA4IBAQCneJA732g7srfydkgG0XJ8b1RS3ffVlnG1ahCDfIpBTx2M7Oco\n0oa4QK4fEJnyh5Zc861aNrRHecLk4KV4QmDmLJVxTKNv3QXqgPJu+zN49x9ESwRs\nbqiaD+K6MYmlyRukxY+v8jyOhTKvZTOjuuGKhDRcNNgn/kPIjZw3v37vY4o1pUPL\nP1YBw2Caa01HstzouaVZlw05Viwo2AHJE5u7zW+VcA4VR8WAD/2SqdyWZIo+chwd\nr3hWlRyHephLCBhOLb1wPk3E+mOIyryXjLpGdVnWewMSEY8AGvv7IORkO5ufCz/c\n5UlG1r1+l5AhnFQPGoREI49hXVAETVInW9Uk\n-----END CERTIFICATE-----

The certificate's text.

domain
string <domain>
Example: domain=example.com

The domain's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetchsslinfo

Response samples

Content type
application/json
{
  • "data": {
    • "cab": "-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIFAhQDowAwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL\\nZXhhbXBsZS5jb20wHhcNMTkxMTExMjAzNzUzWhcNMjAxMTEwMjAzNzUzWjAWMRQw\\nEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\\nggEBAK31N5qqd4BhMRm318tt7CP3thvJ9nXv5j3Hks8bfNggAgBmWwh/iGEoyB0e\\nmKmFkomXYQejSCkFmwI5/I+H53LA1UrnWURAHaY8UCJMMeCe22E9fbmASNMhcnov\\n/AOYBl3kEWEkKVBN3dQZFsWzj+PTTui1zHl8nrr1POPLZMS+t8D3HppNoUBwBkKR\\nQ/MetqCaQ3HlgbknMi0/5DbuaV0GJNbXNX9uhnGqQFUI21sEVU4xcvtEDN88dT1d\\nx5EhLXobDV/brXgFm85QK/lZt3aWlIJLs/WJJSK+152PO3HhfoHpkx+JflMYoev5\\nLauXhZGYXCEG8sBLa2PPH9WlpgcCAwEAAaOByzCByDAdBgNVHQ4EFgQU/Vx4Cer1\\nmY3SaijxdCsA2Jo7q84wCQYDVR0TBAIwADBCBgNVHSMEOzA5gBT9XHgJ6vWZjdJq\\nKPF0KwDYmjurzqEapBgwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb22CBQIUA6MAMB0G\\nA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjA5BgNVHREEMjAwggtleGFtcGxl\\nLmNvbYIQbWFpbC5leGFtcGxlLmNvbYIPd3d3LmV4YW1wbGUuY29tMA0GCSqGSIb3\\nDQEBCwUAA4IBAQCneJA732g7srfydkgG0XJ8b1RS3ffVlnG1ahCDfIpBTx2M7Oco\\n0oa4QK4fEJnyh5Zc861aNrRHecLk4KV4QmDmLJVxTKNv3QXqgPJu+zN49x9ESwRs\\nbqiaD+K6MYmlyRukxY+v8jyOhTKvZTOjuuGKhDRcNNgn/kPIjZw3v37vY4o1pUPL\\nP1YBw2Caa01HstzouaVZlw05Viwo2AHJE5u7zW+VcA4VR8WAD/2SqdyWZIo+chwd\\nr3hWlRyHephLCBhOLb1wPk3E+mOIyryXjLpGdVnWewMSEY8AGvv7IORkO5ufCz/c\\n5UlG1r1+l5AhnFQPGoREI49hXVAETVInW9Uk\\n-----END CERTIFICATE-----",
    • "crt": "-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIFAhQDowAwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL\\nZXhhbXBsZS5jb20wHhcNMTkxMTExMjAzNzUzWhcNMjAxMTEwMjAzNzUzWjAWMRQw\\nEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\\nggEBAK31N5qqd4BhMRm318tt7CP3thvJ9nXv5j3Hks8bfNggAgBmWwh/iGEoyB0e\\nmKmFkomXYQejSCkFmwI5/I+H53LA1UrnWURAHaY8UCJMMeCe22E9fbmASNMhcnov\\n/AOYBl3kEWEkKVBN3dQZFsWzj+PTTui1zHl8nrr1POPLZMS+t8D3HppNoUBwBkKR\\nQ/MetqCaQ3HlgbknMi0/5DbuaV0GJNbXNX9uhnGqQFUI21sEVU4xcvtEDN88dT1d\\nx5EhLXobDV/brXgFm85QK/lZt3aWlIJLs/WJJSK+152PO3HhfoHpkx+JflMYoev5\\nLauXhZGYXCEG8sBLa2PPH9WlpgcCAwEAAaOByzCByDAdBgNVHQ4EFgQU/Vx4Cer1\\nmY3SaijxdCsA2Jo7q84wCQYDVR0TBAIwADBCBgNVHSMEOzA5gBT9XHgJ6vWZjdJq\\nKPF0KwDYmjurzqEapBgwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb22CBQIUA6MAMB0G\\nA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjA5BgNVHREEMjAwggtleGFtcGxl\\nLmNvbYIQbWFpbC5leGFtcGxlLmNvbYIPd3d3LmV4YW1wbGUuY29tMA0GCSqGSIb3\\nDQEBCwUAA4IBAQCneJA732g7srfydkgG0XJ8b1RS3ffVlnG1ahCDfIpBTx2M7Oco\\n0oa4QK4fEJnyh5Zc861aNrRHecLk4KV4QmDmLJVxTKNv3QXqgPJu+zN49x9ESwRs\\nbqiaD+K6MYmlyRukxY+v8jyOhTKvZTOjuuGKhDRcNNgn/kPIjZw3v37vY4o1pUPL\\nP1YBw2Caa01HstzouaVZlw05Viwo2AHJE5u7zW+VcA4VR8WAD/2SqdyWZIo+chwd\\nr3hWlRyHephLCBhOLb1wPk3E+mOIyryXjLpGdVnWewMSEY8AGvv7IORkO5ufCz/c\\n5UlG1r1+l5AhnFQPGoREI49hXVAETVInW9Uk\\n-----END CERTIFICATE-----",
    • "crt_origin": "example",
    • "domain": "example.com",
    • "ip": "192.168.0.20",
    • "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEArfU3mqp3gGExGbfXy23sI/e2G8n2de/mPceSzxt82CACAGZb\nCH+IYSjIHR6YqYWSiZdhB6NIKQWbAjn8j4fncsDVSudZREAdpjxQIkwx4J7bYT19\nuYBI0yFyei/8A5gGXeQRYSQpUE3d1BkWxbOP49NO6LXMeXyeuvU848tkxL63wPce\nmk2hQHAGQpFD8x62oJpDceWBuScyLT/kNu5pXQYk1tc1f26GcapAVQjbWwRVTjFy\n+0QM3zx1PV3HkSEtehsNX9uteAWbzlAr+Vm3dpaUgkuz9YklIr7XnY87ceF+gemT\nH4l+Uxih6/ktq5eFkZhcIQbywEtrY88f1aWmBwIDAQABAoIBAD9rmDMOFPU7+d+r\nc8QZti7Cv6TP88e5h5JccTyKg/BzcudcabHmdP0fFh3vqq6bIPqCswBK2iMChSnB\npD9bx9jBTsG5KIVGbsjNUlW+u6xtngOMnIqFp4c5uXesiM9ynFecr21f9qPtT4Nl\nBjVbqojf3/PdW8eq1F/KysEtxPYpC/RI35iL0zl8EBZ5Ydn0Yb6ftr2e72mf8JDx\nN6SgQt3E7vviRSmivuURmN9KjD+grf94fiL7PDONL/ectOWrvXnD7ppmngNuae2m\n34OHraSM46QzOp/egFc0yyNQC2PKb4YxYMq7U2ijU2rM4d809HI9jG2BXmB1I2YO\no5vZK4kCgYEA2mggZsJs7L67NXryrDNm82RnoPEjoTT2zdzl92BvMYVmu2cRyi/m\n2X5HDzTlc3l8fqFERSSc/Vc/hjluaDT+vbJzNa1tFklMbb3rXW1Z6fhqadQf34jz\nAXjeUU90aCIgAcFyTVdiz12pS1ESNCeGlRFIBF5Z3nK3MV/JmUNjEBsCgYEAy+Z/\nAtRAc6YcYseVEyo0wq2NNfDStYNp7+GhcA8qp4+1pZ8dk7n9VfkSUem0WEoi7F7g\nlUVDsWr62XiFtkV3dv77CUTlXcjmReykTzvPclT9wqyj84F09FdPZ5XusiQ0GKPe\nwLUWv+NPFlarZSxvRedlwPnC3O7FrN9TAV0/WIUCgYEAwpa/N47GKXANr6ppB8+M\nTBIK2jO+QOTFd8j2Ax8iMobebt131iIzlVeSzBOe0vFMYC4ie1ARpw3TBS2qFqIQ\nzMZvK0XmyVJpC+WIC+dfkrvHY56g/zIvAALGYL9fwV+WELpfslTHLmYObZI/m8QT\nfkC1X18Ixs6CNTVYknqdij0CgYA+btZnJFyTzMIWUOxJkPvUvFVntdSe9Z0jcWAA\nMvSpl+xTyTPCPwneIETGxhuNiS3GWIrFyg6fLZWfrzKqC/03d32gafMdU12G/Z2W\nEUdEx9dnm3scHYCVLILIwfTzoPg+rzaOpSRRHyXhPip+8SslKWRTwWY0RfxLIZqF\n6WpzDQKBgQDIFver+WSw/LTHt8LvYWyWi7pOIu6Df0ff1AYYSTMzsz9UewfRlSFw\n/ASp0dR6Po84oxIYRERxbu1ZoDhQxnGb5M1i+iFsOYBIRVmbWs4k7A0kghjGqciA\nyIbJNfSVmgNTXN4VqXW1rAqYDGDgE+huGEpnD08bPfEQm9tp0Mss5w==\n-----END RSA PRIVATE KEY-----",
    • "key_origin": "example",
    • "searched_users": [
      • "root",
      • "example"
      ],
    • "user": "example"
    },
  • "metadata": {
    • "command": "fetchsslinfo",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Delete SSL vhost

This function deletes the SSL virtual host.

Authorizations:
BasicAuth
query Parameters
host
required
string
Example: host=example.com

The hostname whose SSL virtual host you'd like to delete.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_ssl_vhost \
  host='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "output": [
      • "Deleting the SSL host for example.com",
      • "Done."
      ],
    • "removed_vhost_data": [
      • {
        • "ip_port": [
          • "192.0.2.0",
          • "443"
          ],
        • "is_ssl": 1,
        • "primary_on_ip_port": "example.net",
        • "servername": "example.com",
        • "vhost_entry": "<VirtualHost 192.0.2.0 :443>\nServerName example.com\nServerAlias [...]\n"
        }
      ]
    },
  • "metadata": {
    • "command": "delete_ssl_vhost",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return server vhosts and SSL certificates

This function lists the server's virtual hosts (vhosts) and their installed SSL certificates.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_ssl_vhosts

Response samples

Content type
application/json
{
  • "data": {
    • "vhosts": [
      • {
        • "crt": {
          • "created": 1538308800,
          • "domains": [
            • "example.com",
            • "subdomain.example.com"
            ],
          • "ecdsa_curve_name": null,
          • "ecdsa_public": null,
          • "encryption_algorithm": "rsaEncryption",
          • "id": "example1_com_e353a_5bc13_1408033388_9a1d40aff655f98fed7206e5af466065",
          • "is_self_signed": 1,
          • "issuer.commonName": "example.com",
          • "issuer.organizationName": "Organization",
          • "issuer_text": "commonName\nsubdomain.example.com",
          • "modulus": "e353aa25cc8ad05d3225611e4410c0270c11b2d46f88705d3d179a23102ab24ee167c1a9070b9f554e83bade1b84256e11c5a0cb2ac96b96f28e802b11c721d73fbfe61dd9839974a6fce4e17915c0fbf885056f18656041cf70db460b22cab5fd2502491e4ab9f0d2cb727480e0ebd62e83870acda31bfa2d4625efd82234f9729f351ea02fb162609c1654c11b5dec468539a3bb83073a85f78bcf577cd8b718501145cccd89d7adb0bb18c872e7303a15e2c75a6ab315c7fa099e4351a4f0ff126c2693f71d9f21d9f798b94bb689277083fea8dcc01b6af268d0ad8b7a481f8a179d07639cdf3290c93723937a767c400a8ce4b1ca19f0a7117084d5bc13",
          • "modulus_length": 2048,
          • "not_after": 1601467200,
          • "not_before": 1569844800,
          • "public_exponent": "010001",
          • "signature_algorithm": "sha256WithRSAEncryption",
          • "subject.commonName": {
            • "commonName": "example.com"
            },
          • "subject_text": "commonName\nsubdomain.example.com",
          • "validation_type": "dv"
          },
        • "docroot": "/home/example/public_html",
        • "domains": [
          • "example.com"
          ],
        • "ip": "192.168.0.20",
        • "iptype": "dedicated",
        • "ipv6": "2001:0db8:0:0:1:0:0:1",
        • "is_primary_on_ip": 1,
        • "mail_sni_status": 1,
        • "needs_sni": 0,
        • "servername": "example.com",
        • "type": "sub",
        • "user": "example"
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_ssl_vhosts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return cPanel account FQDN certificate information

This function retrieves the certificate information for all fully qualified domain names (FQDNs) that the account owns.

Authorizations:
BasicAuth
query Parameters
domains
required
string <domain>
Examples:
  • domains=domains=example-1.com,example-2.com,example-3.com - Fetch information for multiple domains.
  • domains=example.com - Fetch information for a single domain.

A comma-separated list of domains for which to retrieve information.

Note:

For browser-based calls, you must URI-encode each comma (%2C).

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_ssl_certificates_for_fqdns \
  domains='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "payload": [
      • {
        • "cab": "-----BEGIN CERTIFICATE-----\nMIIDYzCCAkugAwJBAgIFAamFDR8wDQYJKoZIhvcNAQELBQAwFDESMBAGA1UEAwwJ\nc2lza28udGxkMB4XDTE5MDYyNjE1MDYxNVoXDTIwMDYyNTE1MDYxNVowFDESMBAG\nA1UEAwwJc2lza28udGxkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nq0wqPMMP8Q6RiRXe57UXExg3PeAAd00xxFRr6pMwPZtWrkcoYV0kfHEZ7nJmD6Bd\nUnuXrDqTb1z78CeqUFt5+ZQtjGt55CjPFaUkHbNErZm2l8bKB6sjnETZ7ee4AXx/\nmaf/jhgZ0o4SMAS5h87NOoF5yg/Y0tnuncpu/RyzeXzJLxy0Mn0WMGm2w5sXSH4l\n4oaGLorGWyDUfQPjwAwcQsVi97FZ7zElRru//jJ/tqijVLELv1AWudJkuZnJJmKW\nCvkT6YpIIB8UVwbTgnFuZ86Us2Yfe17pMatAVJV8MAbRym3Z4rmWmZr1xrTdoS+L\nSwz4kCffBY5psDRp/WRqAQIDAQABo4G7MIG4MB0GA1UdDgQWBBT22CZM+khxmDvi\nF5LbZVtqm20y8TAfBgNVHSMEGDAWgBT22CZM+khxmDviF5LbZVtqm20y8TAJBgNV\nHRMEAjAAMGsGA1UdEQRkMGKCCXNpc2tvLnRsZIIObWFpbC5zaXNrby50bGSCDXd3\ndy5zaXNrby50bGSCEXdlYm1haWwuc2lza28udGxkghBjcGFuZWwuc2lza28udGxk\nghF3ZWJkaXNrLnNpc2tvLnRsZDANBgkqhkiG9w0BAQsFAAOCAQEAWDXl/WRLHPxa\nnvziWJIcM8jkSxaaUKbRPsow1XVDj3HjpDYbKkYBLfZlmaDmeU6SnmGKFYi0wSDw\n+WkK97ja3+ONHFRlYHO2dHoQrxklrqOqyV2KB0HB6YgHCl9A2b6feC31Zly2i6jc\n3SWEpYIQHecRnELc6WKkfqm0oTJZH0h7Da4WgR10Myi3GE799g0xMO/KCxPF2mDS\n6Ukr/bez9a07zCODrf4o91PrCc7r85dZq8jt02wtGMPg+zvr3FfcVPFaPZ1Oppsx\nrUNVz5W/TqdtxZhr9J5PBpSMNiNnKq88KV1zqIJiNsk9qGJbt5mQQpK0enpKqkmr\nETgwb3sSbw==\n-----END CERTIFICATE-----",
        • "created": 1538308800,
        • "crt": "-----BEGIN CERTIFICATE-----\nMIIDYzCCAkugAwIBAgIFAamFDR8wDQYJKoZIhvcNAQELBQAwFDESMBAGA1UEAwwJ\nc2lza28udGxkMB4XDTE5MDYyNjE1MDYxNVoXDTIwMDYyNTE1MDYxNVowFDESMBAG\nA1UEAwwJc2lza28udGxkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nq0wqPMMP8Q6RiRXe57UXExg3PeAAd00xxFRr6pMwPZtWrkcoYV0kfHEZ7nJmD6Bd\nUnuXrDqTb1z78CeqUFt5+ZQtjGt55CjPFaUkHbNErZm2l8bKB6sjnETZ7ee4AXx/\nmaf/jhgZ0o4SMAS5h87NOoF5yg/Y0tnuncpu/RyzeXzJLxy0Mn0WMGm2w5sXSH4l\n4oaGLorGWyDUfQPjwAwcQsVi97FZ7zElRru//jJ/tqijVLELv1AWudJkuZnJJmKW\nCvkT6YpIIB8UVwbTgnFuZ86Us2Yfe17pMatAVJV8MAbRym3Z4rmWmZr1xrTdoS+L\nSwz4kCffBY5psDRp/WRqAQIDAQABo4G7MIG4MB0GA1UdDgQWBBT22CZM+khxmDvi\nF5LbZVtqm20y8TAfBgNVHSMEGDAWgBT22CZM+khxmDviF5LbZVtqm20y8TAJBgNV\nHRMEAjAAMGsGA1UdEQRkMGKCCXNpc2tvLnRsZIIObWFpbC5zaXNrby50bGSCDXd3\ndy5zaXNrby50bGSCEXdlYm1haWwuc2lza28udGxkghBjcGFuZWwuc2lza28udGxk\nghF3ZWJkaXNrLnNpc2tvLnRsZDANBgkqhkiG9w0BAQsFAAOCAQEAWDXl/WRLHPxa\nnvziWJIcM8jkSxaaUKbRPsow1XVDj3HjpDYbKkYBLfZlmaDmeU6SnmGKFYi0wSDw\n+WkK97ja3+ONHFRlYHO2dHoQrxklrqOqyV2KB0HB6YgHCl9A2b6feC31Zly2i6jc\n3SWEpYIQHecRnELc6WKkfqm0oTJZH0h7Da4WgR10Myi3GE799g0xMO/KCxPF2mDS\n6Ukr/bez9a07zCODrf4o91PrCc7r85dZq8jt02wtGMPg+zvr3FfcVPFaPZ1Oppsx\nrUNVz5W/TqdtxZhr9J5PBpSMNiNnKq88KV1zqIJiNsk9qGJbt5mQQpK0enpKqkmr\nETgwb3sSbw==\n-----END CERTIFICATE-----",
        • "domains": [
          • "example.servername.com",
          • "example.com",
          • "mail.example.com",
          • "www.example.com",
          • "www.example.servername.com"
          ],
        • "ecdsa_curve_name": null,
        • "ecdsa_public": null,
        • "friendly_name": "example.com",
        • "id": "example_servername_com_ce52d_6e643_2813308004_119580f9b01960cjones72bc519206bc",
        • "is_self_signed": 0,
        • "issuer.commonName": "example.servername.com",
        • "issuer.organizationName": "Organization",
        • "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAq0wqPMMP8Q6RiRXe57UXExg3PeAAd00xxFRr6pMwPZtWrkco\nYV0kfHEZ7nJmD6BdUnuXrDqTb1z78CeqUFt5+ZQtjGt55CjPFaUkHbNErZm2l8bK\nB6sjnETZ7ee4AXx/maf/jhgZ0o4SMAS5h87NOoF5yg/Y0tnuncpu/RyzeXzJLxy0\nMn0WMGm2w5sXSH4l4oaGLorGWyDUfQPjwAwcQsVi97FZ7zElRru//jJ/tqijVLEL\nv1AWudJkuZnJJmKWCvkT6YpIIB8UVwbTgnFuZ86Us2Yfe17pMatAVJV8MAbRym3Z\n4rmWmZr1xrTdoS+LSwz4kCffBY5psDRp/WRqAQIDAQABAoIBABR96A+cxitwMrjT\nhPbzEu+V1gXw5h1ffrSd5MsLEJpOGvB+UrZTDipU3WVJCiyUYpWbc2mHGFwaI4l3\nNUinqM/SiiBiOxKwTxWny8pBx9V8rfs6LLD+KCRpmCh9r+V9n0Yics/s0in+FO7p\nocg9VQ/KrWcevjF7ILB/pwdgh5fgw3lFf1Dp3eRG2LLh+ZuY+Q2pYkMrJhSQ0H/f\nTpuYLtZ+6tGzDvnorDJZ4H6kj+7J4UXIXWSxQe0m+hkPe/YU9e9zt4vaiHSu21PC\nNKxnmBASgnLP/0lKPGzTNhc7G4HkssfqYJ1l2W+mH2sFiQKee45EQkyhcFInDzwu\ng47CIoECgYEA3/OPyAEb4WJ1NIC+1tUunUZLC18FDwO2EqoJ2adblRkG2q8DzUPg\npzQpMEo07dwVXedN7TBehl8cN1sfBfmHdznCsW6zNbZ4481hucle1fXx0/05Hajj\n/A/w3NBxjPa45Zlu6Xcot/qy7mONz+xy/oubDI8BnXxJmHIywtsFhlcCgYEAw8+i\nEAhULx5B7hcmCBruuox6stNDleoAAxuaexylvQS5Q9Kse4cEA/ti7PF5b8kDmIH4\nb6JRenaiFmFNJTbAmwQY5iaobulpEA948H6uI7A2Al3NVJacLSmTod58I5ERsDhn\nJoBAtjZuVCZjAOalnyPC4gyFcPY4O7dJwmQDa2cCgYEAsxj6ZG2WmWF+7/UCKZal\nR7ueakKcLgy+wCBh7kFr+UnhdGPAe5iMAcuyIN9Hgu2d3NINPOGQxo8rZo2lusZ6\ncnur2u/3u73o4e0u+UA0apHcyrbYxYJ6iOtKqZy9IolxBpT04RqdYrzH+eN91sl2\nkWCeJ6X6GbL6vEKfm7tCqNMCgYALyW7e+jFfGLotQ9V1PXHLZvNn2lHCL3DKvxmg\neYv8gdFJJOBfGzSBrNs6mhqOQRJnVsOGrMWs0oFVSYwkRlR3wFpjWEZhTsmVPukv\nyOBgo5XMtKrMgbhq+4q4frUISw4+hlanOacrkME5bYoeHsQvfS6Y/tn1f8zIw3K8\nMdsG1wKBgQCFPy/bzPSVV9PI+IVAlOYlbtfTCAQGQ3jG44e1b5wkwm6Di0p44kr4\n5wi4Bxy+NuCDEIksTuo2/ZtjFlrBu233mQImqZp6b5uTeB27vwAxiX55pqsU4gme\neFdttHhA6s5/wOx9E3JRFI1ucerieUROQC+bt6NLvSu7V+amdgn7bw==\n-----END RSA PRIVATE KEY-----",
        • "key_algorithm": "rsaEncryption",
        • "modulus": "ab4c2a3cc30ff10e918915dee7b5171318373de000774d31c4546bea93303d9b56ae4728615d247c7119ee72660fa05d527b97ac3a936f5cfbf027aa505b79f9942d8c6b79e428cf15a5241db344ad99b697c6ca07ab239c44d9ede7b8017c7f99a7ff8e1819d28e123004b987cecd3a8179ca0fd8d2d9ee9dca6efd1cb3797cc92f1cb4327d163069b6c39b17487e25e286862e8ac65b20d47d03e3c00c1c42c562f7b159ef312546bbbffe327fb6a8a354b10bbf5016b9d264b999c92662960af913e98a48201f145706d382716e67ce94b3661f7b5ee931ab4054957c3006d1ca6dd9e2b996999af5c6b4dda12f8b4b0cf89027df058e69b03469fd646a01",
        • "modulus_length": 2048,
        • "not_after": 1569844800,
        • "not_before": 1538308800,
        • "signature_algorithm": "sha256WithRSAEncryption",
        • "subject.commonName": "example.com",
        • "users": [
          • "username"
          ],
        • "validation_type": "dv",
        • "verify_error": "DEPTH_ZERO_SELF_SIGNED_CERT"
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_ssl_certificates_for_fqdns",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add SSL certificate to installation queue

This function adds SSL certificates to the installation queue. This allows you to defer and batch SSL certificate installation.

Important:

You must enter the same quantity of username, cab, crt, key, and vhost_name parameters. For example, to add three certificates to the installation queue, enter the username parameter three times, then enter three cab, crt, key, and vhost_name parameters.

Authorizations:
BasicAuth
query Parameters
cab
required
string
Examples:
  • cab=cab-1=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ8V8e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- cab-2=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ7V7e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- cab-3=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- - Enqueue multiple CA bundles.
  • cab=cab=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ8V8e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- cab=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ7V7e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- cab=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- - Enqueue multiple CA bundles.
  • cab=-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- - Enqueue a single CA bundle.

The Certificate Authority (CA) bundle's contents.

Note:

  • We recommend that you enter an empty string. An empty string tells the server to download the CA bundle automatically.
  • To add multiple certificates to the installation queue, duplicate or increment the parameter name. For example, cab-1, cab-2, and cab-3.
crt
required
string
Examples:
  • crt=crt-1=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2CFCrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- crt-2=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2AZArc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- crt-3=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- - Enqueue the contents of multiple certificates.
  • crt=crt=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2CFCrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- crt=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2AZArc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- crt=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- - Enqueue the contents of multiple certificates.
  • crt=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE----- - Enqueue a single certificate's contents.

The certificate's contents.

Note:

To add multiple certificates to the installation queue, duplicate or increment the parameter name. For example, crt-1, crt-2, and crt-3.

key
required
string
Examples:
  • key=key-1=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3LMNmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- key-2=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3TUVmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- key-3=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3RSHmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- - Enqueue the private key text of multiple certificates.
  • key=key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3LMNmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3TUVmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3RSHmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- - Enqueue the private key text of multiple certificates.
  • key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3RSHmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY----- - Enqueue a single certificate's private key text.

The private key's text.

Note:

To add multiple certificates to the installation queue, duplicate or increment the parameter name. For example, key-1, key-2, and key-2.

username
required
string
Examples:
  • username=username-1=username1 username-2=username2 username-3=username3 - Enqueue multiple SSL certificate installations.
  • username=username=username1 username=username2 username=username3 - Enqueue multiple SSL certificate installations.
  • username=username - Enqueue a single SSL certificate installation.

The cPanel account username for which to enqueue the SSL certificate installations.

Note:

To add multiple certificates to the installation queue, duplicate or increment the parameter name. For example, username-1, username-2, and username-3.

vhost_name
required
string <domain>
Examples:
  • vhost_name=vhost_name-1=host1.example.com vhost_name-2=host2.example.com vhost_name-3=host3.example.com - Install the certificate for multiple vhosts.
  • vhost_name=vhost_name=host1.example.com vhost_name=host2.example.com vhost_name=host3.example.com - Install the certificate for multiple vhosts.
  • vhost_name=host.example.com - Install the certificate for a single vhost.

The name of the web virtual host (vhost) for which to install the certificate.

Note:

To add multiple certificates to the installation queue, duplicate or increment the parameter name. For example, vhost_name-1, vhost_name-2, and vhost_name-3.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  enqueue_deferred_ssl_installations \
  username='username' \
  cab='-----BEGIN%20CERTIFICATE-----%0AMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M%0AypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy%0AbW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE-----' \
  crt='-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE-----' \
  key='-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEowIBAAKCAQEAt6vq%2FPAW347qigdxemr6L85VVARjehbGuofqYH8%2ByxVLHBx%2F%0ApsuOg7iyj%2Bd2vKaFv2ap%2BQ6phUfCdD%2BHa4z4jDU0ooN%2FA6WNZyAJLbg3KRt9BSVb%0A9I0NOi90MaVPUCd6vT3RCx77X21rwpL%2FcCTPftuSCoyQ87%2BIQ4eUX8tsu%2BN%2BKCGS%0AgZyjnXBzp3scJDA9ZH5R6dtBbNTBHj%2Fg%2BrD9ivEMC%2Fw78Sc184bCcKeWcWrhrf3R%0AUauKowCeDMiVExUO7iokZbd0U1K1VSbvX7Xptr94hUFAY3atuCJ7pFvpW4d2ypKt%0A55rS1ItHF10V3sDRAxBG%2B2eqhS%2FpFkGF5%2Bva3QIDAQABAoIBAAONBE79iUOrLKec%0AezolpU6VS5sDNrUeiZsDk6ln7Fvavof9mQ4tc0TipjkX%2FXiqM32%2By1xwRyC3gW%2Fj%0A5odSw19ai%2Fj0V9lHMxOiT%2BsdW5uk12bpEP0KWQ4d6r4m9wCSstHDxy3S3IM8x0%2BM%0ArfmKDKTkM8%2BWZhsAQe8kSN8NPL3pIJnG%2Ftuc8lwFoZOEot6%2BAeGYdxxEdFbvVyEm%0Aa8%2FAhOQ5Z07T36bxuPtyRjwdnFH7hnmzpcWF5Iz8Jp8SrQ2XX2rKSQpa1Ic%2B6TMA%0AF7kJsOFiw%2B8aX6zTTVLsvQTHWEsnNWHKtbuNBoQcq2HyifrUxr550kZVMnyNC3ic%0A6EH%2FCxUCgYEA5qSo6zf6yJ5tdwm%2FNnrKwvFksapd%2Bi9%2BnAqQHHTFPtlzKHkZ7d5x%0AdklyzAMaoHVoeggtQynUcxcYKjy3i9Nj29P8wN6DhcxJY4Ohdk%2FsAILTcu8QyPzN%0A%2FcYVHWykmFuS55uEa2Mlv6j%2FTBraRJUYfiEl2ZvR77L5gke4GAsCKxcCgYEAy91D%0AlmTy4ka991Ungy%2BVcNTSw9z50l%2Fzu4GxmAlj1fsuX%2F27nbfpsOFjbvlm4xLfW3qM%0A%2BWkrvKXUuxeIbGcBnVlHFWgc6%2BKt5vNoOzUVsm5i90R%2Fg3vhB5cdvuVoTKf2EU4n%0ANVTSaM%2F6zpzBEHSKtTsbx0FiPjS04bk%2Bsi0REisCgYAwy3s1MEWtNd9AxN4gP4Aw%0AF%2FPOppV1PaESkCWG76lfL4%2FuaxhyO5JTjRxtTubONaih0KMKx4m7w5IINYo7WcCR%0AnFqnzyuSHfMUy59YMXZjcUoc0bkCXIGUA9kpvXdhCFafC0bLlVFCKBXC2xd8VPK2%0AlHq2fAHBLWMeDeBDreiKhwKBgHrcweP8uOioK8rI9kQ4xD649MD4B1PDYjfqRObV%0AGecXN27Ak3bNJTjlzTBPfLNzZ0tRg2649JP%2F%2BUI8P4rdVXrIGHANTAjZl2bt4S51%0Aorrjjh9pl9PdL9SMPXAUABTa0RDC4hxhH2HtnkEw9aX%2BJq5sjiQ7AoNs7mpvYxqs%0A0HH7AoGBALhKD8FxNGYLK8oCO27NBdL%2F%2BypxgH5EnwVr%2B3fF49tfC5xpV9Odfu1Z%0ANGNFbjK47PVCLaGKzQUvU7jSAbKt3pDR0IcfiF%2BM6rc86CmZf%2BvAPTN3%2BJwG%2BcIE%0AcKuYkroIzFWDu9NYiioUI7%2Fa9XdmTvfrT3RSHmup0FoRmlRHD%2FM8%0A-----END%20RSA%20PRIVATE%20KEY-----' \
  vhost_name='host.example.com'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "enqueue_deferred_ssl_installations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all SSL certificate components on vhost

This function lists the components of each SSL certificate on the server's virtual hosts.

Warning:

  • On most servers, this function returns a large amount of output. We strongly recommend that you filter and sort the output.

  • The following example uses the filter and sort options:

    https://hostname.example.com:2087/cpsess##########/json-api/fetch_vhost_ssl_components?api.version=1&api.filter.a.field=servername&api.filter.a.arg0=servername.com&api.filter.a.type=eq&api.filter.enable=1&api.sort.enable=1&api.sort.a.field=servername

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_vhost_ssl_components

Response samples

Content type
application/json
{
  • "data": {
    • "components": [
      • {
        • "cabundle": null,
        • "cabundle_id": null,
        • "certificate": "-----BEGIN CERTIFICATE-----\nMIIDcTCCAlmgAwIBAgIFAc/XZhswDQYJKoZIhvcNAQELBQAwFTETMBEGA1UEAwwK\ncmVzZWxsLmNvbTAeFw0xOTEyMjMxNjEwMDNaFw0yMDEyMjIxNjEwMDNaMBUxEzAR\nBgNVBAMMCnJlc2VsbC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB\nAQDs/rUGLbn4z7PeU7jMH1LeOYGc9omIATsxFwkRJUr7khxDZd59MYm2NzwLf1X2\n7ccYqYGbqjlwwpCWTrWvS9vAmrFqAr+5xp30w3bVhKrE9K+tYfUb4MbY0N/Cu0Hf\nOiSDbo07SAoOrGMHVVaPINNs1+eQ5sRxsJYBz//tOUYEJlrQAPttiHb3sk6J13Vv\nWArtk5+Q7L4lLKSxtPjQmwy/1hU2SRr0tmVkIaH77iOOMWvwB2pIYsRYjKujp0eE\ngo7FdhUIBCJ7+ZqabZHGGpm/UQ+jveI83qqB/xHD4ZxAX7GKUyHGzp8XyIPTFLNq\nAaGWN8Kv80+DZk2my78vFcjfAgMBAAGjgccwgcQwHQYDVR0OBBYEFHIsjBLssrvL\n+K0pebUQE3HYyIxFMAkGA1UdEwQCMAAwQQYDVR0jBDowOIAUciyMEuyyu8v4rSl5\ntRATcdjIjEWhGaQXMBUxEzARBgNVBAMMCnJlc2VsbC5jb22CBQHP12YbMB0GA1Ud\nJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjA2BgNVHREELzAtggpyZXNlbGwuY29t\ngg9tYWlsLnJlc2VsbC5jb22CDnd3dy5yZXNlbGwuY29tMA0GCSqGSIb3DQEBCwUA\nA4IBAQAP6DKtvvr5SQGqxPTaYraq3PU6AWJGSJwFEI4LiUauyNnXMrox4a5Mi3Bl\nOoxEoyW9Br9S6HQ7Ta0kLppcPl6RTuvJljady5feMiCSYaz59XYB5Bo8vTl7Qn7u\nq2UsLqo9qroCpF+qdmbsqR8kFUltjycnVZ8g21Hu2QoeyOKEbuzohy5mtffchoV8\nzsifokwid0f+Zd88oYPQNNPib2P9Ef06DUHy2hBBe0Wunh2McjYckRTdYgIPVANj\n0DhtCcD76Q1VtmjkReirj4CY63/8wcQ2wk37qtUI5x2SzMIAuv49HAwD7atwQKgZ\n03hIrdHhFSIwTJMG1nqyO+h3X5En\n-----END CERTIFICATE-----",
        • "certificate_id": "example_com_ecfeb_5c8df_1608653403_1de5d524f287f7ec75531239a2f4a133",
        • "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpgIBAAKCAQEA7P61Bi25+M+z3lO4zB9S3jmBnPaJiAE7MRcJESVK+5IcQ2Xe\nfTGJtjc8C39V9u3HGKmBm6o5cMKQlk61r0vbwJqxagK/ucad9MN21YSqxPSvrWH1\nG+DG2NDfwrtB3zokg26NO0gKDqxjB1VWjyDTbNfnkObEcbCWAc//7TlGBCZa0AD7\nbYh297JOidd1b1gK7ZOfkOy+JSyksbT40JsMv9YVNkka9LZlZCGh++4jjjFr8Adq\nSGLEWIyro6dHhIKOxXYVCAQie/mamm2RxhqZv1EPo73iPN6qgf8Rw+GcQF+xilMh\nxs6fF8iD0xSzagGhljfCr/NPg2ZNpsu/LxXI3wIDAQABAoIBAQDEBRA5YgzWDQVa\nuKi6vJXQFIRuDURH56zLt5/aPJw+Y+VYoaNarWSYACt73wB9UsJAVcNLu4nzCBqL\nF+MScI38Sna/ljJ6OBth3WImzKpqaW/82m7fdhVCM9E/wZ6EQhT9WK0cAUPASzlF\nUYJcs+vrtNBle1m0JziLmzy1O4/70R4Iongi6pnMbsXopA9zypKvkhQoxAEtb1i7\nJOsFKh0EDuo4tJWkbLaKmoe8CKPr+I9lRonR6q5mwwealhuvtKvPdrz1ckYwizBn\nJIAkY5s7OXbrBe4qYd/FboNem7ExuTqGWiO7oYs/RpdOGWst3Dq7l1oC/ePxbHWK\njcL5DG6hAoGBAPdQOFPQfLrI/UOTNOnghJ4xdfEPpElMOEtWZY02Oz4cZremXfhi\n+ZLOuww6f/Qey9uKH34Umi9ugszTFREEyukJJQ+nG04GkC6EmDgNcwn4lCR6iOMN\nJc8fsnRO3zZmFC9deEbfKkUWWYaVzzBEzqZpS0+DFbPrqz/NoS0WeBtJAoGBAPVR\ntN9Q8LyTA+HjT0h3tAtyLsxPlI8GAb3t89YjSkVNAAMCrUjbOx9g2cLdSIRdoKhj\n6cwRFB2OATne5E1PfyWiw5LLgUf7aGqhDhe4xOHQyN3NhBs1p1W+XNuCJJnLxnpF\nd3NnF8VUkrphlftBzYGCbtFfgzq0W6GxcSiksdrnAoGBAJEAltYFgmwdlei98aNC\nwV7jDwy0qBVVvBfn4wjFiDyleFArGiOdHElILoE/92+RcuMYe9h3ieNPfx9Kj6p3\nzeSOOQ2RY7/+tyCfG4SZ1h49gdZVhdbiCY4EPqRU7ii99w3CVtfu1qDFNt5jDaR2\nY1dMmxxWdi4UekahcOO3rdoJAoGBAMrIAGf8QxLNv47QU/AGKsivWOm/+oADKhty\nf3WJ9FG2pYTXiJ/JwGRerYJ7Yf8wWaX3+QGbOHJ5uJ+6lCMnzGUy1tEX8USsF5LU\nkI6hR/WVnQRjZokLX8frtFwqhtCudeEKXQQCus5960+vbMeljBc61xmxBwvWnEvb\nHjvHb9EPAoGBAMXpIOZPONaOZFpAnxkHMMpE8BSyCCBOYi22JiECcXQusWiI8PIT\nyxRAxIGZ6PY6ks3AEQhb9/oWSd9RVuXsflx01SFkpRIbSNwVWhLqr9HvfmpsZw2S\n5TTdqv/VaEByFDKJSIKnKk4e6rxa2XF6YxUEvZ59Bw3iP2fpksBG/nTu\n-----END RSA PRIVATE KEY-----",
        • "key_id": "ecfeb_5c8df_35927dbac0386ff253c269a9cda4c6f3",
        • "servername": "example.com"
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_vhost_ssl_components",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return domain DCV issues

This function returns a list of objects that contains the latest Domain Control Validation (DCV) problems for a specific domain.

Authorizations:
BasicAuth
query Parameters
domain
required
string <domain>
Example: domain=example.com

The domain for which to poll the DCV status.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_problems_for_domain \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "problems_by_domain": [
      • {
        • "domain": "example.tld",
        • "log": "2017-08-19T13:41:04.000Z",
        • "problem": "The domain does not resolve to any IPv4 addresses on the internet.",
        • "time": "2017-08-19T13:41:04.000Z"
        }
      ]
    },
  • "metadata": {
    • "command": "get_autossl_problems_for_domain",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return account DCV issues

This function returns the list of the latest Domain Control Validation (DCV) problems for a cPanel user.

Authorizations:
BasicAuth
query Parameters
username
required
string <username>
Example: username=username

The user for whom to poll the DCV status.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_autossl_problems_for_user \
  username='username'

Response samples

Content type
application/json
{
  • "data": {
    • "problems_by_domain": [
      • {
        • "domain": "doesnotexist.example.com",
        • "log": "2017-09-07T03:51:01.000Z",
        • "problem": "doesnotexist.example.com does not resolve to any IPv4 addresses on the internet.",
        • "time": "2017-08-12T21:02:56.000Z"
        }
      ]
    },
  • "metadata": {
    • "command": "get_autossl_problems_for_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return SSL-encrypted domain for service access

This function retrieves the most appropriate SSL-encrypted domain to use to access a service.

Authorizations:
BasicAuth
query Parameters
service
required
string
Example: service=whostmgr

The service's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_best_ssldomain_for_service \
  service='whostmgr'

Response samples

Content type
application/json
{
  • "data": {
    • "cert_match_method": "none",
    • "cert_valid_not_after": 1457452989,
    • "is_currently_valid": 0,
    • "is_self_signed": 1,
    • "is_wild_card": 0,
    • "ssldomain": "hostname.example.com",
    • "ssldomain_matches_cert": 0
    },
  • "metadata": {
    • "command": "get_best_ssldomain_for_service",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Install SSL certificate for service

This function installs a new SSL certificate on a service.

Important:

You must restart the selected service after you install a new SSL certificate.

Authorizations:
BasicAuth
query Parameters
cabundle
string <pem-certificate>
Default: ""
Example: cabundle=-----BEGIN CERTIFICATE----- MIIE3f4g5h7j73f235gy54hvcNAQELBQAwgYYxEDAOBgNVBAcMB2hvd097342boi0w389w0BCQEWEmMubGFycnl8293rhqurpg9qfgm5ldDEOMAwGA1UECAwFdGV4YXMxCzAJBgNVBAYTAlVTMSEwHwYDVQQDDBhiaW5hcnlhZ2Fpbi5jcGFuZWwubmluamExDzANBgNVBAoMBmNwYW5lbDAeFw0yMDA1MTgxODQ3NTFaFw0yMTA1MTgxODQ3NTFaMIGGMRAwDgYDVQQHDAdob3VzdG9uMSEwHwYJKoZIhvcNAQkBFhJjLmxhcnJ5QGNwYW5lbC5uZXQxDjAMBgNVBAgMBXRleGFzMQswCQYDVQQGEwJVUzEhMB8GA1UEAwwYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMQ8wDQYDVQQKDAZjcGFuZWwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC3i1fOlIUoURJf4BkMgoVvCeq5GZjzuCl6WXzz5WsADYUl84UzgXJIWtwBoTc2l32zyeWkIAkM/eNR12YMb0kXbgihbZtEsH0XimqcXmtiicoM3tjBi6u0cDEFr8TMdI396oArnnTc0CASfdXUGGtReZ6vOwxXOPPK5nYCvyFqBl1n0pQ2AV/Co9/WwhOCvV/Bm9aTzueZrbYB/9uW31LOpjs+0s1QNGHv6PTvH8HZFW/7Z9M3gSwUxfOOOQHEiiHRWfb/UqcTZZxjZhfY/IN6/SOsc3Z2t2KmQ5XI6ijCrjjJeaZSQYsge8LpHskr8G3WeTV9M9+1YnI7GRqs3+GdAgMBAAGjggEsMIIBKDAdBgNVHQ4EFgQUYWWThQj2tRL5PNkdPhUJdqEIcrswCQYDVR0TBAIwADCBtwYDVR0jBIGvMIGsgBRhZZOFCPa1Evk82R0+FQl2oQhyu6GBjKSBiTCBhjEQMA4GA1UEBwwHaG91c3RvbjEhMB8GCSqGSIb3DQEJARYSYy5sYXJyeUBjcGFuZWwubmV0MQ4wDAYDVQQIDAV0ZXhhczELMAkGA1UEBhMCVVMxITAfBgNVBAMMGGJpbmFyeWFnYWluLmNwYW5lbC5uaW5qYTEPMA0GA1UECgwGY3BhbmVsggUCGG94JTAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwIwYDVR0RBBwwGoIYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMA0GCSqGSIb3DQEBCwUAA4IBAQBhKmds+XDTycHc2bsSH+zDkWIw58+J26Re9Q9VnUcrSKtV3mmtW88r8FuEHEZdAOzFPTJ3Tdd1fha15wuS5dzOV+bCRrDTvJmD4vRPkQ5TSdyJgpIjpjwiOP1+ZwaF7xZ+FLMTcEl8SXM+lkoKEUQpHFKyQ0zGIaLCVt0QyXx16lesPMgPeb/KRXJPy7ZrUtyF0z0LgvOSDGNsGt4rD8FVgtdHRlMJf/XIoFeV5Zk+rHNoCXIQXh4nBzM8X2r3IrQ1Qh0Z3njN2Ld8ZUlxsWctlLzvzmjARzIzvbglO3wod5XoRLS+fU6oVyQ9yuQLGG6r6Y7iBYSHfAO8e0pLkp7G -----END CERTIFICATE-----

The certificate's Certificate Authority (CA) bundle.

Note:

You must URI-encode this value.

crt
required
string <pem-certificate>
Example: crt=-----BEGIN CERTIFICATE----- MIIE3f4g5h7j73f235gy54hvcNAQELBQAwgYYxEDAOBgNVBAcMB2hvd097342boi0w389w0BCQEWEmMubGFycnl8293rhqurpg9qfgm5ldDEOMAwGA1UECAwFdGV4YXMxCzAJBgNVBAYTAlVTMSEwHwYDVQQDDBhiaW5hcnlhZ2Fpbi5jcGFuZWwubmluamExDzANBgNVBAoMBmNwYW5lbDAeFw0yMDA1MTgxODQ3NTFaFw0yMTA1MTgxODQ3NTFaMIGGMRAwDgYDVQQHDAdob3VzdG9uMSEwHwYJKoZIhvcNAQkBFhJjLmxhcnJ5QGNwYW5lbC5uZXQxDjAMBgNVBAgMBXRleGFzMQswCQYDVQQGEwJVUzEhMB8GA1UEAwwYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMQ8wDQYDVQQKDAZjcGFuZWwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC3i1fOlIUoURJf4BkMgoVvCeq5GZjzuCl6WXzz5WsADYUl84UzgXJIWtwBoTc2l32zyeWkIAkM/eNR12YMb0kXbgihbZtEsH0XimqcXmtiicoM3tjBi6u0cDEFr8TMdI396oArnnTc0CASfdXUGGtReZ6vOwxXOPPK5nYCvyFqBl1n0pQ2AV/Co9/WwhOCvV/Bm9aTzueZrbYB/9uW31LOpjs+0s1QNGHv6PTvH8HZFW/7Z9M3gSwUxfOOOQHEiiHRWfb/UqcTZZxjZhfY/IN6/SOsc3Z2t2KmQ5XI6ijCrjjJeaZSQYsge8LpHskr8G3WeTV9M9+1YnI7GRqs3+GdAgMBAAGjggEsMIIBKDAdBgNVHQ4EFgQUYWWThQj2tRL5PNkdPhUJdqEIcrswCQYDVR0TBAIwADCBtwYDVR0jBIGvMIGsgBRhZZOFCPa1Evk82R0+FQl2oQhyu6GBjKSBiTCBhjEQMA4GA1UEBwwHaG91c3RvbjEhMB8GCSqGSIb3DQEJARYSYy5sYXJyeUBjcGFuZWwubmV0MQ4wDAYDVQQIDAV0ZXhhczELMAkGA1UEBhMCVVMxITAfBgNVBAMMGGJpbmFyeWFnYWluLmNwYW5lbC5uaW5qYTEPMA0GA1UECgwGY3BhbmVsggUCGG94JTAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwIwYDVR0RBBwwGoIYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMA0GCSqGSIb3DQEBCwUAA4IBAQBhKmds+XDTycHc2bsSH+zDkWIw58+J26Re9Q9VnUcrSKtV3mmtW88r8FuEHEZdAOzFPTJ3Tdd1fha15wuS5dzOV+bCRrDTvJmD4vRPkQ5TSdyJgpIjpjwiOP1+ZwaF7xZ+FLMTcEl8SXM+lkoKEUQpHFKyQ0zGIaLCVt0QyXx16lesPMgPeb/KRXJPy7ZrUtyF0z0LgvOSDGNsGt4rD8FVgtdHRlMJf/XIoFeV5Zk+rHNoCXIQXh4nBzM8X2r3IrQ1Qh0Z3njN2Ld8ZUlxsWctlLzvzmjARzIzvbglO3wod5XoRLS+fU6oVyQ9yuQLGG6r6Y7iBYSHfAO8e0pLkp7G -----END CERTIFICATE-----

The certificate to install.

Note:

You must URI-encode this value.

key
required
string <pem-private-key>
Example: key=-----BEGIN RSA PRIVATE KEY----- MIIEpQIBAAKCAQEA4FIdZcIKVK5+PtdzVm4CN45BXG5wX7KZ1/dP84MGIwtwxkkX hBqw7BawbHlexYXuarSnrHA8hm6RRxv/fRy+zOeg7y8v5CWG52m91GK7qSLxpruY gCJGJEK8fj6spbbLjxNd5XAmDwT80uMsq/3E9rGmg/ELY9X9vn5WlErRfi2Qjsiq x7AYUvcIkBHPOlRWzZgx2KjMjBU2U0w2RCUjgKgww/6xx2ccnTvn7HGvVjQMkh+1 UYCdGvT8fR2qJBKHZ5Cjdfc9N304qZCqYMhcrHX2gJqc+9zLtLk7PoEYXu17l6nU O3C/IdzBXYWu+UoMzpZ5tc5jKRA3+I7ggKjJlwIDAQABAoIBAQDR4GI648qQolXh 6+iws+qFGibTGU0wbET+SBjYx/0E6t5P1vEWm3Zu3WehhgkCm6WO1omOj9BBIs/w DSUEZNGrmwf64VZYijfm6gs+3EWiINyhWCF9uRORN5NuNquHvDhGHCOc2EnzgYIe uYgBP0R6X4phJjS26u8mvMO6qSnKd4wRrOf9ZU73L1VTmhMItshVxH2tuhKurkMV jWDAjWeJfycWe4JVgYxM4GA6g5kKi5nrkhpVEsklh1FJZn65U0aWXUpHAm2ihhKf Fq9FgC+8Xz8UAtf8JYbAW3D1E/0lRZuLt+5cosK8b2+9CIUNRjYMtyXlbI0RGwl9 FO/9sv05AoGBAP0jfp8qUqf4u4pkE1W2SzzbQ6oYKYHTMiORVHi2qysgrxAZFKGj fW7c7UTpxlCaqqDBRQA+lZH16xVD3idwYvmw/9AKxSozxe3wKbQFRM+XYHc7la+2 TiQiJgjflEadSa57FNgBB7SpeEzaIfmGBYWJXkM+6wuaGUz5qZs/SFJNAoGBAOLb Ouh7CWTk5oISVBfqxnwFEpaMHT5vpzNBwUWUVMhrxNZP3OVSN++qKxpJhCF/M2no OdxX7CYkrGvHFTvV9WKpa0kYQGms+ybyoMOYxJax8rV+Zq9gg2QKwaakoJljaAlX 5yUuy32YhLxWodQhE7mlhAUyXIuNLVuYee0Y2ZVzAoGAaV6tBnQHlAPljOW7ZqJL Dzn2IIeOP4w6ArQsBVOETJ9+P6UxAVecjtlHqrfk5Qh8ng3VOxTSDb/f6yok/yW5 DVawJVlWWQrUCQc/VMActIy+iuMym8G3JTNRwb/PaNVwJkD1nDRRkNI6UUM7gTJY eg2EP1mhXWL3xSLnhsgAwsECgYEAqnm2xfeXsqM0+bAOU77RE2e4dTuryjybeDBE riXupIIf9DElvYrQkCDfrSxrx8RP/ZlOyd+kjXFnxMJhmYqKkW7hOZeo6ADe54DT AMmvidMFog/v2ID9m9NdfP4f1cTW7JaLE+0bbDGOJf4wNDn7GbphAIq88v3PhRKL JXpUIDMCgYEA2P7D/oZu+dEPW8JhUsDDXY238ZDbQzWBi6n1uUnMJCnUABd/mvuV ILR/iSBHmt9UdH2YECwry58xFjhXwfTvPc155PiJddjENGFUqohjl0wh0VzLEyfF Vb6iVMIdrycD/O4U26I3Qco2lQYPoPgrBkAGJ5/GCjkTiL0JssoMXa4= -----END RSA PRIVATE KEY-----

The certificate's key.

Note:

You must URI-encode this value.

service
required
string
Possible Values: "ftp" "exim" "dovecot" "cpanel"
Example: service=cpanel

The service on which to install the SSL certificate.

  • ftp
  • exim
  • dovecot
  • cpanel

Important:

You must restart the selected service after you install a new SSL certificate.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  install_service_ssl_certificate \
  service='cpanel' \
  crt='-----BEGIN CERTIFICATE-----
MIIE3f4g5h7j73f235gy54hvcNAQELBQAwgYYxEDAOBgNVBAcMB2hvd097342boi0w389w0BCQEWEmMubGFycnl8293rhqurpg9qfgm5ldDEOMAwGA1UECAwFdGV4YXMxCzAJBgNVBAYTAlVTMSEwHwYDVQQDDBhiaW5hcnlhZ2Fpbi5jcGFuZWwubmluamExDzANBgNVBAoMBmNwYW5lbDAeFw0yMDA1MTgxODQ3NTFaFw0yMTA1MTgxODQ3NTFaMIGGMRAwDgYDVQQHDAdob3VzdG9uMSEwHwYJKoZIhvcNAQkBFhJjLmxhcnJ5QGNwYW5lbC5uZXQxDjAMBgNVBAgMBXRleGFzMQswCQYDVQQGEwJVUzEhMB8GA1UEAwwYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMQ8wDQYDVQQKDAZjcGFuZWwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC3i1fOlIUoURJf4BkMgoVvCeq5GZjzuCl6WXzz5WsADYUl84UzgXJIWtwBoTc2l32zyeWkIAkM/eNR12YMb0kXbgihbZtEsH0XimqcXmtiicoM3tjBi6u0cDEFr8TMdI396oArnnTc0CASfdXUGGtReZ6vOwxXOPPK5nYCvyFqBl1n0pQ2AV/Co9/WwhOCvV/Bm9aTzueZrbYB/9uW31LOpjs+0s1QNGHv6PTvH8HZFW/7Z9M3gSwUxfOOOQHEiiHRWfb/UqcTZZxjZhfY/IN6/SOsc3Z2t2KmQ5XI6ijCrjjJeaZSQYsge8LpHskr8G3WeTV9M9+1YnI7GRqs3+GdAgMBAAGjggEsMIIBKDAdBgNVHQ4EFgQUYWWThQj2tRL5PNkdPhUJdqEIcrswCQYDVR0TBAIwADCBtwYDVR0jBIGvMIGsgBRhZZOFCPa1Evk82R0+FQl2oQhyu6GBjKSBiTCBhjEQMA4GA1UEBwwHaG91c3RvbjEhMB8GCSqGSIb3DQEJARYSYy5sYXJyeUBjcGFuZWwubmV0MQ4wDAYDVQQIDAV0ZXhhczELMAkGA1UEBhMCVVMxITAfBgNVBAMMGGJpbmFyeWFnYWluLmNwYW5lbC5uaW5qYTEPMA0GA1UECgwGY3BhbmVsggUCGG94JTAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwIwYDVR0RBBwwGoIYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMA0GCSqGSIb3DQEBCwUAA4IBAQBhKmds+XDTycHc2bsSH+zDkWIw58+J26Re9Q9VnUcrSKtV3mmtW88r8FuEHEZdAOzFPTJ3Tdd1fha15wuS5dzOV+bCRrDTvJmD4vRPkQ5TSdyJgpIjpjwiOP1+ZwaF7xZ+FLMTcEl8SXM+lkoKEUQpHFKyQ0zGIaLCVt0QyXx16lesPMgPeb/KRXJPy7ZrUtyF0z0LgvOSDGNsGt4rD8FVgtdHRlMJf/XIoFeV5Zk+rHNoCXIQXh4nBzM8X2r3IrQ1Qh0Z3njN2Ld8ZUlxsWctlLzvzmjARzIzvbglO3wod5XoRLS+fU6oVyQ9yuQLGG6r6Y7iBYSHfAO8e0pLkp7G
-----END CERTIFICATE-----' \
  key='-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA4FIdZcIKVK5+PtdzVm4CN45BXG5wX7KZ1/dP84MGIwtwxkkX
hBqw7BawbHlexYXuarSnrHA8hm6RRxv/fRy+zOeg7y8v5CWG52m91GK7qSLxpruY
gCJGJEK8fj6spbbLjxNd5XAmDwT80uMsq/3E9rGmg/ELY9X9vn5WlErRfi2Qjsiq
x7AYUvcIkBHPOlRWzZgx2KjMjBU2U0w2RCUjgKgww/6xx2ccnTvn7HGvVjQMkh+1
UYCdGvT8fR2qJBKHZ5Cjdfc9N304qZCqYMhcrHX2gJqc+9zLtLk7PoEYXu17l6nU
O3C/IdzBXYWu+UoMzpZ5tc5jKRA3+I7ggKjJlwIDAQABAoIBAQDR4GI648qQolXh
6+iws+qFGibTGU0wbET+SBjYx/0E6t5P1vEWm3Zu3WehhgkCm6WO1omOj9BBIs/w
DSUEZNGrmwf64VZYijfm6gs+3EWiINyhWCF9uRORN5NuNquHvDhGHCOc2EnzgYIe
uYgBP0R6X4phJjS26u8mvMO6qSnKd4wRrOf9ZU73L1VTmhMItshVxH2tuhKurkMV
jWDAjWeJfycWe4JVgYxM4GA6g5kKi5nrkhpVEsklh1FJZn65U0aWXUpHAm2ihhKf
Fq9FgC+8Xz8UAtf8JYbAW3D1E/0lRZuLt+5cosK8b2+9CIUNRjYMtyXlbI0RGwl9
FO/9sv05AoGBAP0jfp8qUqf4u4pkE1W2SzzbQ6oYKYHTMiORVHi2qysgrxAZFKGj
fW7c7UTpxlCaqqDBRQA+lZH16xVD3idwYvmw/9AKxSozxe3wKbQFRM+XYHc7la+2
TiQiJgjflEadSa57FNgBB7SpeEzaIfmGBYWJXkM+6wuaGUz5qZs/SFJNAoGBAOLb
Ouh7CWTk5oISVBfqxnwFEpaMHT5vpzNBwUWUVMhrxNZP3OVSN++qKxpJhCF/M2no
OdxX7CYkrGvHFTvV9WKpa0kYQGms+ybyoMOYxJax8rV+Zq9gg2QKwaakoJljaAlX
5yUuy32YhLxWodQhE7mlhAUyXIuNLVuYee0Y2ZVzAoGAaV6tBnQHlAPljOW7ZqJL
Dzn2IIeOP4w6ArQsBVOETJ9+P6UxAVecjtlHqrfk5Qh8ng3VOxTSDb/f6yok/yW5
DVawJVlWWQrUCQc/VMActIy+iuMym8G3JTNRwb/PaNVwJkD1nDRRkNI6UUM7gTJY
eg2EP1mhXWL3xSLnhsgAwsECgYEAqnm2xfeXsqM0+bAOU77RE2e4dTuryjybeDBE
riXupIIf9DElvYrQkCDfrSxrx8RP/ZlOyd+kjXFnxMJhmYqKkW7hOZeo6ADe54DT
AMmvidMFog/v2ID9m9NdfP4f1cTW7JaLE+0bbDGOJf4wNDn7GbphAIq88v3PhRKL
JXpUIDMCgYEA2P7D/oZu+dEPW8JhUsDDXY238ZDbQzWBi6n1uUnMJCnUABd/mvuV
ILR/iSBHmt9UdH2YECwry58xFjhXwfTvPc155PiJddjENGFUqohjl0wh0VzLEyfF
Vb6iVMIdrycD/O4U26I3Qco2lQYPoPgrBkAGJ5/GCjkTiL0JssoMXa4=
-----END RSA PRIVATE KEY-----'

Response samples

Content type
application/json
{
  • "data": {
    • "certificate": "-----BEGIN CERTIFICATE-----\nMIIE3f4g5h7j73f235gy54hvcNAQELBQAwgYYxEDAOBgNVBAcM\nB2hvd097342boi0w389w0BCQEWEmMubGFycnl8293rhqurpg9qfgm5ldDEOMAwG\nA1UECAwFdGV4YXMxCzAJBgNVBAYTAlVTMSEwHwYDVQQDDBhiaW5hcnlhZ2Fpbi5j\ncGFuZWwubmluamExDzANBgNVBAoMBmNwYW5lbDAeFw0yMDA1MTgxODQ3NTFaFw0y\nMTA1MTgxODQ3NTFaMIGGMRAwDgYDVQQHDAdob3VzdG9uMSEwHwYJKoZIhvcNAQkB\nFhJjLmxhcnJ5QGNwYW5lbC5uZXQxDjAMBgNVBAgMBXRleGFzMQswCQYDVQQGEwJV\nUzEhMB8GA1UEAwwYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMQ8wDQYDVQQKDAZj\ncGFuZWwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC3i1fOlIUoURJf\n4BkMgoVvCeq5GZjzuCl6WXzz5WsADYUl84UzgXJIWtwBoTc2l32zyeWkIAkM/eNR\n12YMb0kXbgihbZtEsH0XimqcXmtiicoM3tjBi6u0cDEFr8TMdI396oArnnTc0CAS\nfdXUGGtReZ6vOwxXOPPK5nYCvyFqBl1n0pQ2AV/Co9/WwhOCvV/Bm9aTzueZrbYB\n/9uW31LOpjs+0s1QNGHv6PTvH8HZFW/7Z9M3gSwUxfOOOQHEiiHRWfb/UqcTZZxj\nZhfY/IN6/SOsc3Z2t2KmQ5XI6ijCrjjJeaZSQYsge8LpHskr8G3WeTV9M9+1YnI7\nGRqs3+GdAgMBAAGjggEsMIIBKDAdBgNVHQ4EFgQUYWWThQj2tRL5PNkdPhUJdqEI\ncrswCQYDVR0TBAIwADCBtwYDVR0jBIGvMIGsgBRhZZOFCPa1Evk82R0+FQl2oQhy\nu6GBjKSBiTCBhjEQMA4GA1UEBwwHaG91c3RvbjEhMB8GCSqGSIb3DQEJARYSYy5s\nYXJyeUBjcGFuZWwubmV0MQ4wDAYDVQQIDAV0ZXhhczELMAkGA1UEBhMCVVMxITAf\nBgNVBAMMGGJpbmFyeWFnYWluLmNwYW5lbC5uaW5qYTEPMA0GA1UECgwGY3BhbmVs\nggUCGG94JTAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwIwYDVR0RBBww\nGoIYYmluYXJ5YWdhaW4uY3BhbmVsLm5pbmphMA0GCSqGSIb3DQEBCwUAA4IBAQBh\nKmds+XDTycHc2bsSH+zDkWIw58+J26Re9Q9VnUcrSKtV3mmtW88r8FuEHEZdAOzF\nPTJ3Tdd1fha15wuS5dzOV+bCRrDTvJmD4vRPkQ5TSdyJgpIjpjwiOP1+ZwaF7xZ+\nFLMTcEl8SXM+lkoKEUQpHFKyQ0zGIaLCVt0QyXx16lesPMgPeb/KRXJPy7ZrUtyF\n0z0LgvOSDGNsGt4rD8FVgtdHRlMJf/XIoFeV5Zk+rHNoCXIQXh4nBzM8X2r3IrQ1\nQh0Z3njN2Ld8ZUlxsWctlLzvzmjARzIzvbglO3wod5XoRLS+fU6oVyQ9yuQLGG6r\n6Y7iBYSHfAO8e0pLkp7G\n-----END CERTIFICATE-----",
    • "certificate_info": {
      • "domains": [
        • "example.com"
        ],
      • "ecdsa_curve_name": null,
      • "ecdsa_public": null,
      • "is_self_signed": 1,
      • "issuer.commonName": "example.com",
      • "issuer.organizationName": "Organization",
      • "issuer_text": "localityName\ncity\nemailaddress\[email protected]\nstateOrProvinceName\nstate\ncountryName\nUS\ncommonName\nhostname\norganizationName\ncpanel",
      • "key_algorithm": "rsaEncryption",
      • "modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
      • "modulus_length": 2048,
      • "not_after": 1601467200,
      • "not_before": 1601467200,
      • "signature_algorithm": "sha256WithRSAEncryption",
      • "validation_type": "dv"
      },
    • "service": "cpanel",
    • "service_description": "Calendar, cPanel, WebDisk, Webmail, and WHM Services"
    },
  • "metadata": {
    • "command": "install_service_ssl_certificate",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Install SSL certificate

This function installs an SSL certificate.

Authorizations:
BasicAuth
query Parameters
cab
string
Example: cab=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE-----

The certificate's certificate authority (CA) bundle.

If you do not use this parameter, the system automatically determines the appropriate CA bundle file to use.

Note:

You must URI-encode this value.

crt
required
string
Example: crt=-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE-----

The certificate's text.

Note:

You must URI-encode this value.

domain
required
string <domain>
Example: domain=example.com

The domain's name.

ip
string <ipv4>
Example: ip=192.168.0.20

The IP address of the certificate's domain.

This parameter defaults to the domain's local IP address.

key
required
string
Example: key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEpAIBAAKCAQEA4AVM6J4Qg3DIFWr/eJ5GRmIATYsJIepKbrDy70sq+udcO8R8xxak0oMZ/9mUdpjSNK/fLVTuCO0kxTfQ9VUWJllX7ThD6Zh9ZvlC/nf/OEZLm3ZbnBgu8rbC8E9wuDOkKbJLnINgdhtowIydLK2MJ++q62bFV89jkHWTMcKyyqHENo3hc+lkpd9vnp8rZTinaVb7nX26uQqAFZYRo+WU0G/NPsq40QVSMoqPxyEz4qXo0hvuIlCXmzFZq/6fCVPEKPLhQgMmpdBkMz4dVOazREfqXdjMD2+QXSNiA1AwWr8l0r4rtzlxEYDJIR41yXp0xMl3KoolxMyvLBqZy32niQIDAQABAoIBAQCmbGmhWmPsMeoCt1WJFxQgD4goE0U6k+Kt7vjbOt14Pk6v/B2yjaju1wSGpO59WLS4/XrwI2se6IXrmba7u3VUEgWXLriNHoLy7/SMNTs+ZEKhAMG36eNe3tVdT7busTag31r6sEMGGwCsIwpU+azosk0oylWLEX/m/uHWEs1eaIEWWWtgHB+KZrrP7Rr9RYfVQ144DxmOxS3Ca9+mST62WqAVPR6POWGEfZqnZl/ePWZPcQYbFrhwnnefNoYBl/bnLZBo8rbNWxAqOEOuKfkrBzglKG/39WKPw8rj4JIVzY0yOuFCW6xCDWRkOrhU8Ol/3FvwDa3uJpkpmgPr4TgxAoGBAPGPLmxSuOYR97mDAXxrs037F2GCbqWvI6m7/ezWe9yn+bMpjSIWfsgtq4FsyqzPueEkDdQWi3xh6nu2WI/1Tl875opGAqEIJMqss/u11tnva5wzu1cCL6H85A5+HMOBvP3sm6CObKcVw92h7kxynVIUJJWhjfeZMN8gBFFpKIVFAoGBAO1ptXBmXLC/YKKvtHI3M16/ZopvM8ZqU2HcAHaw214Refw9JJ/e3/xTNfSerVTyCAQO1AdWTzJKBN8jmSYv1Mk1D3RpQPNR7wVzi46KR081AU41uMpqIGVOwHtyVnW/ZfLrc1DLIK8Cx8aHfoxffwzoMO5SEQSooeZfOLhsfDN1AoGBAKQTUEINsj+75psgbAr6ELGgItJ9yPBLVRr+cUzEpx9LDWVvjMihpP4NX1gq8EOPWT+ewLHVmmsjCyV6xw8JXXF8e2xif3in0m3D/wCzE7u2T06rKM3B017hKnrZmGoHnrqPU2osM4sOUpshWX6dv1Q4EF1+fbK3YCW+VpCBsB9NAoGAQo+uhNLODee56iKkzpjXWCsFTq6ar3hD5F3P63buKdNwhd2GlSPhXFbf+7M5GWW6BZk6rMvv7EOAVice2uvyFm8/4/1WbmF8R+T7LX1rPLO5p/m701QpvP11TabiwqRkqtSEQhSRF0AKTojSW/yyHCZFAawUhV/Z9EKiHmKb97kCgYAyzmFc2it0HqnsOnRybop603nqMtWGTQO4cxa93HUDpYajuK2K3DfrxUj6lG3z/oKJGGE2JqgZ6LBAhNJtJWJu2ox3pKGE63QjLJnVwb8y1NFYpe/crbLePuBwIR0L7drXxfv7O5btY7h6QI2d1/UIAQPAWbxLoTM+ndQ/uPEdfA%3D%3D-----END%20RSA%20PRIVATE%20KEY-----

The certificate's key.

Note:

You must URI-encode this value.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  installssl \
  domain='example.com' \
  crt='-----BEGIN%20CERTIFICATE-----%0AMIIDNTCCAh2gAwIBAgIFAY0o0kwwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL%0AZG9tYWluLnRlc3QwHhcNMTcxMDMxMTUyMjU1WhcNMTgxMDMxMTUyMjU1WjAWMRQw%0AEgYDVQQDDAtkb21haW4udGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC%0AggEBALer6vzwFt%2BO6ooHcXpq%2Bi%2FOVVQEY3oWxrqH6mB%2FPssVSxwcf6bLjoO4so%2Fn%0Adrymhb9mqfkOqYVHwnQ%2Fh2uM%2BIw1NKKDfwOljWcgCS24NykbfQUlW%2FSNDTovdDGl%0AT1Aner090Qse%2B19ta8KS%2F3Akz37bkgqMkPO%2FiEOHlF%2FLbLvjfighkoGco51wc6d7%0AHCQwPWR%2BUenbQWzUwR4%2F4Pqw%2FYrxDAv8O%2FEnNfOGwnCnlnFq4a390VGriqMAngzI%0AlRMVDu4qJGW3dFNStVUm71%2B16ba%2FeIVBQGN2rbgie6Rb6VuHdsqSreea0tSLRxdd%0AFd7A0QMQRvtnqoUv6RZBhefr2t0CAwEAAaOBiTCBhjAdBgNVHQ4EFgQUeitnD4U4%0AMXtmLX53dTAZPENjovwwHwYDVR0jBBgwFoAUeitnD4U4MXtmLX53dTAZPENjovww%0ACQYDVR0TBAIwADA5BgNVHREEMjAwggtkb21haW4udGVzdIIQbWFpbC5kb21haW4u%0AdGVzdIIPd3d3LmRvbWFpbi50ZXN0MA0GCSqGSIb3DQEBCwUAA4IBAQAeD4Fc%2FBwM%0AfJEvlPO30%2FOp2JJxG92tbgsoY9CKTYoZy0IMHhwOrt%2FB36joYDrOhtiO6XsRw4Zm%0AAPT8ey9p61kUc6XWs5oU9aifKeAKzWCZV9wQphbY%2F0rQp1YPsVN9tBgiag754HPo%0AbNDhWOZSZDKnh82DikTD6iciTxeblrvcbFC4Z76JH31dvqmNMEAgZvPCpq86Ued5%0A52gKM0u2%2BrK%2FzIYjh%2FhooqN%2BTY%2BJQ667JzLzPNenzAYFsoIQgVj6%2FZoFqJA4nbxC%0Azv%2Fspqc0OQ2W9m5egRPDhngKt%2Bi9804N7FeilBL%2FcpEgUHhgzMBi1T9n%2BYBrc6bO%0AjNjvnEQRbqZY%0A-----END%20CERTIFICATE-----' \
  key='-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEpAIBAAKCAQEA4AVM6J4Qg3DIFWr/eJ5GRmIATYsJIepKbrDy70sq+udcO8R8xxak0oMZ/9mUdpjSNK/fLVTuCO0kxTfQ9VUWJllX7ThD6Zh9ZvlC/nf/OEZLm3ZbnBgu8rbC8E9wuDOkKbJLnINgdhtowIydLK2MJ++q62bFV89jkHWTMcKyyqHENo3hc+lkpd9vnp8rZTinaVb7nX26uQqAFZYRo+WU0G/NPsq40QVSMoqPxyEz4qXo0hvuIlCXmzFZq/6fCVPEKPLhQgMmpdBkMz4dVOazREfqXdjMD2+QXSNiA1AwWr8l0r4rtzlxEYDJIR41yXp0xMl3KoolxMyvLBqZy32niQIDAQABAoIBAQCmbGmhWmPsMeoCt1WJFxQgD4goE0U6k+Kt7vjbOt14Pk6v/B2yjaju1wSGpO59WLS4/XrwI2se6IXrmba7u3VUEgWXLriNHoLy7/SMNTs+ZEKhAMG36eNe3tVdT7busTag31r6sEMGGwCsIwpU+azosk0oylWLEX/m/uHWEs1eaIEWWWtgHB+KZrrP7Rr9RYfVQ144DxmOxS3Ca9+mST62WqAVPR6POWGEfZqnZl/ePWZPcQYbFrhwnnefNoYBl/bnLZBo8rbNWxAqOEOuKfkrBzglKG/39WKPw8rj4JIVzY0yOuFCW6xCDWRkOrhU8Ol/3FvwDa3uJpkpmgPr4TgxAoGBAPGPLmxSuOYR97mDAXxrs037F2GCbqWvI6m7/ezWe9yn+bMpjSIWfsgtq4FsyqzPueEkDdQWi3xh6nu2WI/1Tl875opGAqEIJMqss/u11tnva5wzu1cCL6H85A5+HMOBvP3sm6CObKcVw92h7kxynVIUJJWhjfeZMN8gBFFpKIVFAoGBAO1ptXBmXLC/YKKvtHI3M16/ZopvM8ZqU2HcAHaw214Refw9JJ/e3/xTNfSerVTyCAQO1AdWTzJKBN8jmSYv1Mk1D3RpQPNR7wVzi46KR081AU41uMpqIGVOwHtyVnW/ZfLrc1DLIK8Cx8aHfoxffwzoMO5SEQSooeZfOLhsfDN1AoGBAKQTUEINsj+75psgbAr6ELGgItJ9yPBLVRr+cUzEpx9LDWVvjMihpP4NX1gq8EOPWT+ewLHVmmsjCyV6xw8JXXF8e2xif3in0m3D/wCzE7u2T06rKM3B017hKnrZmGoHnrqPU2osM4sOUpshWX6dv1Q4EF1+fbK3YCW+VpCBsB9NAoGAQo+uhNLODee56iKkzpjXWCsFTq6ar3hD5F3P63buKdNwhd2GlSPhXFbf+7M5GWW6BZk6rMvv7EOAVice2uvyFm8/4/1WbmF8R+T7LX1rPLO5p/m701QpvP11TabiwqRkqtSEQhSRF0AKTojSW/yyHCZFAawUhV/Z9EKiHmKb97kCgYAyzmFc2it0HqnsOnRybop603nqMtWGTQO4cxa93HUDpYajuK2K3DfrxUj6lG3z/oKJGGE2JqgZ6LBAhNJtJWJu2ox3pKGE63QjLJnVwb8y1NFYpe/crbLePuBwIR0L7drXxfv7O5btY7h6QI2d1/UIAQPAWbxLoTM+ndQ/uPEdfA%3D%3D-----END%20RSA%20PRIVATE%20KEY-----'

Response samples

Content type
application/json
{
  • "data": {
    • "action": "install",
    • "aliases": [
      • "mail.example.com",
      • "subdomain.example.com"
      ],
    • "domain": "example.com",
    • "extra_certificate_domains": [
      • "mail.example.com",
      • "subdomain.example.com"
      ],
    • "html": "Certificate verification passed<br/> <br /> The Certificate for the domain example.com was installed on the IP 192.168.0.20. </html><br><b>Finished SSL Install Process for example.com (www.example.com).</b>",
    • "ip": "192.168.0.20",
    • "message": "The SSL certificate is now installed onto the domain \"example.com\" using the IP address \"192.168.0.20\". Apache is restarting in the background.",
    • "servername": "example.com",
    • "status": 1,
    • "statusmsg": "The SSL certificate is now installed onto the domain \"example.com\" using the IP address \"192.168.0.20\". Apache is restarting in the background.",
    • "user": "username",
    • "warning_domains": [
      • "subdomain.example.com"
      ],
    • "working_domains": [
      • "example.com",
      • "mail.example.com"
      ]
    },
  • "metadata": {
    • "command": "installssl",
    • "output": "<br>The SSL certificate is now installed onto the domain “example.com“ using the IP address“192.168 .0 .20“. < br / > Apache is restarting in the background.",
    • "reason": "The SSL certificate is now installed onto the domain “example.com“ using the IP address “192.168.0.20“.Apache is restarting in the background.",
    • "result": 1,
    • "version": 1
    }
}

SSL Server Settings

SSL Certificates / SSL Server Settings

Return system services and associated certificates

This function lists the system's services and their associated certificates.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_service_ssl_components

Response samples

Content type
application/json
{
  • "data": {
    • "services": [
      • {
        • "cabundle": "",
        • "certificate": "-----BEGIN CERTIFICATE-----\nMIIECjCCAvKgAwIBAgIEW7p6xzANBgkqhkiG9w0BAQUFADCBnTELMAkGA1UEBhMC\nVVMxEDAOBgNVBAgMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAoM\nB1Vua25vd24xEDAOBgNVBAsMB1Vua25vd24xHTAbBgNVBAMMFGphc29uLmRldi5j\ncGFuZWwubmV0MScwJQYJKoZIhvcNAQkBFhhzc2xAamFzb24uZGV2LmNwYW5lbC5u\nZXQwHhcNMTMwNDI5MjEwNDU5WhcNMTQwNDI5MjEwNDU5WjCBnTELMAkGA1UEBhMC\nVVMxEDAOBgNVBAgMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAoM\nB1Vua25vd24xEDAOBgNVBAsMB1Vua25vd24xHTAbBgNVBAMMFGphc29uLmRldi5j\ncGFuZWwubmV0MScwJQYJKoZIhvcNAQkBFhhzc2xAamFzb24uZGV2LmNwYW5lbC5u\nZXQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCmc8Oxc0RmSzX4eR9W\nLTrqa/TY+qOuP8ClGTgP1FOWSjZnfDTUhnfst/XtA13wJvXw+Pv+IXReUtrx87nl\njHPwuu/bcJMg4iAufQUlCwUaWbMP8f7yLYPXFAwcgc6jFKCJDOjSImeZhyGBxYp0\nAWx6qiz/WscrV1zs3o8wSqVyouoD2LFzq3bG6M2539DageERnO/UuLTb++DkbH8e\n4v6LX9VQTljMvA0TtPpB7Mnr0Nq+HR/sXHJPdIFn58BVPpl/m3frNqvOcJc/Bt8V\nF0jUG3WN4+/Xr6byRkoVR/X/FYRp2W4ki+Rk357aDnzoVKiTMqLBJ4sXxCU2ipYE\n9FTbAgMBAAGjUDBOMB0GA1UdDgQWBBSiMwrIK+JMVx8ufKnfByp3V+ycoTAfBgNV\nHSMEGDAWgBSiMwrIK+JMVx8ufKnfByp3V+ycoTAMBgNVHRMEBTADAQH/MA0GCSqG\nSIb3DQEBBQUAA4IBAQAdL/oywZw+EMwNGf/e1JqjXull/fgoNMZHxsBwQb2smZuN\nKoTlkf2zDO7yTTIUnrBP1TveIlAejDLMMR7yqVgmDrVM/pl4WQjL/APbrWGExsE8\nJeEu+DjOIEveOVTTXCwaVo8ck2JO3QWZwPeRUZBwifZOfaYa8gwpdcUy8Tu/HX9T\nxsOLv/vQar8JC4Obh5eFrMBp87Obf1m/2Kmpaj9PGQQiiq+HU3r4dZf24bLGESr/\nvPXIfInwZ0Fr4G+OzwDqPgI9nCm13myZ+ZBybL64pp741ReRP1dHQGYnwtht/Dh4\n/vFZEL9Wv/18E4lUCJjMgBIknjWkyt6FtygmB1DS\n-----END CERTIFICATE-----",
        • "certificate_info": {
          • "domains": [
            • "example.com"
            ],
          • "ecdsa_curve_name": null,
          • "ecdsa_public": null,
          • "is_self_signed": 1,
          • "issuer.commonName": "example.com",
          • "issuer.organizationName": "Writer's Guild of America",
          • "issuer_text": "countryName\nUS\nstateOrProvinceName\nUnknown\nlocalityName\nUnknown\norganizationName\nUnknown\norganizationalUnitName\nUnknown\ncommonName\nexample.com\nemailAddress\[email protected]",
          • "key_algorithm": "rsaEncryption",
          • "modulus": null,
          • "modulus_length": null,
          • "not_after": 1601467200,
          • "not_before": 1569844800
          },
        • "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEA4FIdZcIKVK5+PtdzVm4CN45BXG5wX7KZ1/dP84MGIwtwxkkX\nhBqw7BawbHlexYXuarSnrHA8hm6RRxv/fRy+zOeg7y8v5CWG52m91GK7qSLxpruY\ngCJGJEK8fj6spbbLjxNd5XAmDwT80uMsq/3E9rGmg/ELY9X9vn5WlErRfi2Qjsiq\nx7AYUvcIkBHPOlRWzZgx2KjMjBU2U0w2RCUjgKgww/6xx2ccnTvn7HGvVjQMkh+1\nUYCdGvT8fR2qJBKHZ5Cjdfc9N304qZCqYMhcrHX2gJqc+9zLtLk7PoEYXu17l6nU\nO3C/IdzBXYWu+UoMzpZ5tc5jKRA3+I7ggKjJlwIDAQABAoIBAQDR4GI648qQolXh\n6+iws+qFGibTGU0wbET+SBjYx/0E6t5P1vEWm3Zu3WehhgkCm6WO1omOj9BBIs/w\nDSUEZNGrmwf64VZYijfm6gs+3EWiINyhWCF9uRORN5NuNquHvDhGHCOc2EnzgYIe\nuYgBP0R6X4phJjS26u8mvMO6qSnKd4wRrOf9ZU73L1VTmhMItshVxH2tuhKurkMV\njWDAjWeJfycWe4JVgYxM4GA6g5kKi5nrkhpVEsklh1FJZn65U0aWXUpHAm2ihhKf\nFq9FgC+8Xz8UAtf8JYbAW3D1E/0lRZuLt+5cosK8b2+9CIUNRjYMtyXlbI0RGwl9\nFO/9sv05AoGBAP0jfp8qUqf4u4pkE1W2SzzbQ6oYKYHTMiORVHi2qysgrxAZFKGj\nfW7c7UTpxlCaqqDBRQA+lZH16xVD3idwYvmw/9AKxSozxe3wKbQFRM+XYHc7la+2\nTiQiJgjflEadSa57FNgBB7SpeEzaIfmGBYWJXkM+6wuaGUz5qZs/SFJNAoGBAOLb\nOuh7CWTk5oISVBfqxnwFEpaMHT5vpzNBwUWUVMhrxNZP3OVSN++qKxpJhCF/M2no\nOdxX7CYkrGvHFTvV9WKpa0kYQGms+ybyoMOYxJax8rV+Zq9gg2QKwaakoJljaAlX\n5yUuy32YhLxWodQhE7mlhAUyXIuNLVuYee0Y2ZVzAoGAaV6tBnQHlAPljOW7ZqJL\nDzn2IIeOP4w6ArQsBVOETJ9+P6UxAVecjtlHqrfk5Qh8ng3VOxTSDb/f6yok/yW5\nDVawJVlWWQrUCQc/VMActIy+iuMym8G3JTNRwb/PaNVwJkD1nDRRkNI6UUM7gTJY\neg2EP1mhXWL3xSLnhsgAwsECgYEAqnm2xfeXsqM0+bAOU77RE2e4dTuryjybeDBE\nriXupIIf9DElvYrQkCDfrSxrx8RP/ZlOyd+kjXFnxMJhmYqKkW7hOZeo6ADe54DT\nAMmvidMFog/v2ID9m9NdfP4f1cTW7JaLE+0bbDGOJf4wNDn7GbphAIq88v3PhRKL\nJXpUIDMCgYEA2P7D/oZu+dEPW8JhUsDDXY238ZDbQzWBi6n1uUnMJCnUABd/mvuV\nILR/iSBHmt9UdH2YECwry58xFjhXwfTvPc155PiJddjENGFUqohjl0wh0VzLEyfF\nVb6iVMIdrycD/O4U26I3Qco2lQYPoPgrBkAGJ5/GCjkTiL0JssoMXa4=\n-----END RSA PRIVATE KEY-----",
        • "service": "ftp"
        }
      ]
    },
  • "metadata": {
    • "command": "fetch_service_ssl_components",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create self-signed SSL certificate

This function generates a private key file, a certificate signing request (CSR), and a self-signed SSL certificate.

Authorizations:
BasicAuth
query Parameters
countryName
string <ISO-3166-1 (alpha-2)>
Example: countryName=US

The certificate's country code.

If you do not use this parameter, your CSR will not include this field.

domains
required
string <domain>
Examples:
  • domains=domain=example1.com,example2.com,example3.com - Generate an SSL certificate for multiple domains.
  • domains=example.com - Generate an SSL certificate for a single domain.

A comma-separated list of the certificate's domains.

emailAddress
string <email>

The certificate's contact email address.

If you do not use this parameter, your CSR will not include this field.

keysize
integer >= 1
Example: keysize=2048

The size of the certificate's key, in bits.

If you do not use this parameter, your CSR will not include this field.

localityName
string
Example: localityName=Houston

The certificate's city or locality.

If you do not use this parameter, your CSR will not include this field.

organizationalUnitName
string or null
Default: null
Example: organizationalUnitName=Development

The department of the organization that owns the certificate.

organizationName
string
Example: organizationName=Example, L.L.C.

The certificate's organization.

If you do not use this parameter, your CSR will not include this field.

pass
string or null
Default: null
Example: pass=123456luggage

The certificate's passphrase.

skip_certificate
integer
Default: 0
Possible Values: 1 0
Example: skip_certificate=0

Whether the function will skip certificate generation.

  • 1 — Skip certificate generate (do not generate a certificate).
  • 0 — Do not skip certificate generation (generate a certificate).

Note:

The function will still generate a CSR and key and save both to the user's SSLStorage data store.

stateOrProvinceName
string
Example: stateOrProvinceName=Texas

The certificate's state or province name.

If you do not use this parameter, your CSR will not include this field.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  generatessl \
  domains='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "cert": "-----BEGIN CERTIFICATE-----\nMIIDVDCCAjygAwIBAgIFANMbQ1IwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL\nZXhhbXBsZS5jb20wHhcNMjAwMzE2MTg1OTU4WhcNMjEwMzE2MTg1OTU4WjAWMRQw\nEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBALnif/SIEE3xfi7iXCI3Kk7yNFrKw9b3SbCwTFEV4HZZpX+gK0ZkwT1vkkT6\nIFs68DVJI9KxXycCY8ZVI64TeD5Hqqy3p9NAkALyfC9OJlDP/mAKjgUZYISMci4K\njuf252rrtox5I5DgbWfXGe12HAjOnQrNjJMvscU9DstXMjDtzrlpwHZ/PH+v/Rcw\nt1WwpcAVOFNxQq6Z0CDwKW/JsHu7tVRa57QMlLTm2BEMIPlTHHoHRJk0zOQuHP3x\n87eYpnCiE/WbC5xlfm912fnFvvECb/6OGtAsw7GC0KnovS1W+rPfZHAdbbA61ukU\nMh+U5VJaNot/kqfbJYpkMD1VRu8CAwEAAaOBqDCBpTAdBgNVHQ4EFgQUSU78eVCc\nJPFAzdImFwAufRu+2WEwCQYDVR0TBAIwADBCBgNVHSMEOzA5gBRJTvx5UJwk8UDN\n0iYXAC59G77ZYaEapBgwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb22CBQDTG0NSMB0G\nA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAWBgNVHREEDzANggtleGFtcGxl\nLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEAf9dzrKj4LGvkBN3q0VHvPsKicl8tABxK\nuv4vKoiAXuh7R9k2bnFqpfvDa7j2qbBd5Gh4ctjdwTv7eA/E0sELgxlezcx9grgX\nCk//GRieAoEj6ZOx1AdKw/Pj6jQyMpU9mQi7+nbpcl1CmQlBc9c2OiayjAAwxm1s\n+Uj7C9+OOkFXeLt/adurcKHhDO3tVD9fqr+pFiVjJOyuIr+T/84gAUAK4RxipaDg\nf35OapjaVQesolECPEP9l/ajf5e2C33JBDwoVqa3b7wwhStN4YpF+7SAd74K1QRz\nrPum8QKnzZjwtx0OBRJl/CHQBz4u0LJGBH4vXhgzzoAcdlGouKf8RA==\n-----END CERTIFICATE-----\n",
    • "cert_id": "example_com_a2459_9d253_1405012775_521f3620ac92180d24a74813a921b23e",
    • "certfile": "/var/cpanel/ssl/system/certs/example_com_e0054_da789_1405012513_401c27501f5e0dd8d1b1d9caa902a0c8.crt",
    • "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIChDCCAWwCAQAwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3\nDQEBAQUAA4IBDwAwggEKAoIBAQC54n/0iBBN8X4u4lwiNypO8jRaysPW90mwsExR\nFeB2WaV/oCtGZME9b5JE+iBbOvA1SSPSsV8nAmPGVSOuE3g+R6qst6fTQJAC8nwv\nTiZQz/5gCo4FGWCEjHIuCo7n9udq67aMeSOQ4G1n1xntdhwIzp0KzYyTL7HFPQ7L\nVzIw7c65acB2fzx/r/0XMLdVsKXAFThTcUKumdAg8ClvybB7u7VUWue0DJS05tgR\nDCD5Uxx6B0SZNMzkLhz98fO3mKZwohP1mwucZX5vddn5xb7xAm/+jhrQLMOxgtCp\n6L0tVvqz32RwHW2wOtbpFDIflOVSWjaLf5Kn2yWKZDA9VUbvAgMBAAGgKTAnBgkq\nhkiG9w0BCQ4xGjAYMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEB\nCwUAA4IBAQCEPc5HD2KRQpqqm7aG6Y/oOnbGALi7GcOsr/vo+voWRDhC/nTAC9vp\nDXEjWY4FfA7N1VSgH5f04k40SBWlfvgCzQAB2AfLEo6LReNv1oCpojvKZVbJq+pq\nKTEMhkFzj4CBTG2gt9rAhKmNai7AnvDWdrnulsVShAsQMYsEeVmCxfGE9w3IEmLP\nJSvUB6/RSPF8zB5yP6/tZy00k+Mt/959yPAxDicrNASbCA2/TkuaBEaP+2v9lJY7\nzg2Z1js/Nv/5DE+1sqp+7GI26M6ZCSNzSyTVs2MOl6ecJTxhRCbVTYFy9SDRtsGE\nVOpPe2+XTcBM/mGIIRJharQNgy7S8kZ0\n-----END CERTIFICATE REQUEST-----\n",
    • "csr_id": "example_com_e0054_da789_96b6625681492b7c43844b6ec37764de",
    • "csrfile": "/var/cpanel/ssl/system/csrs/example_com_a2459_9d253_d5edb563abb8dd426099bbb358c8f2bc.csr",
    • "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAueJ/9IgQTfF+LuJcIjcqTvI0WsrD1vdJsLBMURXgdlmlf6Ar\nRmTBPW+SRPogWzrwNUkj0rFfJwJjxlUjrhN4PkeqrLen00CQAvJ8L04mUM/+YAqO\nBRlghIxyLgqO5/bnauu2jHkjkOBtZ9cZ7XYcCM6dCs2Mky+xxT0Oy1cyMO3OuWnA\ndn88f6/9FzC3VbClwBU4U3FCrpnQIPApb8mwe7u1VFrntAyUtObYEQwg+VMcegdE\nmTTM5C4c/fHzt5imcKIT9ZsLnGV+b3XZ+cW+8QJv/o4a0CzDsYLQqei9LVb6s99k\ncB1tsDrW6RQyH5TlUlo2i3+Sp9slimQwPVVG7wIDAQABAoIBAGIHgzdwcjjIvKT5\nF2Gr+hH8RYQEHtfFPgWCVB0HDoMbr93omCndhNNjfZ4G0v2JzZgsZEn+5JFr/zZf\nPBvXhLhDj0za5hTQnaIQQ1GnQymnJx17M36Y7X+5mZWSV98ZJN4MRQ8763fCA7CZ\njcDfYtV6MPO7hwEwS+4azyyJZZzLRUP2Z8kpXv3PFlXUeddZHwQgyKRdLcQWXE/w\niFClYSfsk10y8Nm6BKzI6TkZS32zIGt3FdJ8+kARJteV0sg6hjPpZMH0223Cbn+h\nlq9eU5b8N5xq7FBmmrfpJcaPdkmo8nUzEGQszyHHjF3N3p78065T+PEb+Jlirsl/\nQf48ssECgYEA9o5wPmAtP8/tdDtdUSHJDbvERq0i2SeEmlrc/82mw82WlHA//sg8\npqeT3EtH8QdvZqSVSw74Yr4TNOLMwLt8T5Rg+gPYsdoqc++d8hB/ru6nvRBwJ437\nZN2JeoEObvNv4QgnfFpeKGxgaX49Yx6u0DJsABWpWsAppCUTXtxP2D8CgYEAwQEo\nQ0tFhwKz4e2gSyOSkuWUJi+tbY//+ouZEGlIYCzObXsZ/bM/AIEZKiAVTdyY5h91\nnAXLFRgcP3z0+h0XeiTcSZN4oEiMwL1/mPmx4uBMZijV54+ABjUFbVStlzxh4KLN\nzf0HUOPAA1biCNDn1yY+a8C+hKky2Ec+Nx//ZVECgYBqD5v5OSY97RQYi/D4lbAH\nWF52iMQU5gsE21F2OOEkGaxM7nyY/UoZ5ryUZ03rQWeKoAIY57exwlJAzc+GmSBA\nm3OcGUt+NntMpCctmitS9RbzHb8hRNJ/8UzShfHPiKj4BKn3tGgMu5I9zzBZEzng\nFdCfuLHBeChxlAFhLSSrwQKBgQCUUsxbcvRavmP5Y8HFHPBevdotwoQ4Z+rj4/Zc\nm1yItMZrcqhVxTPMsmnhasiUjsxeRZz/q6AXdPD4hZJKyKKrNrqoPJH+M+MfmEIA\nERx468Eq3YUNsMVFf+fMzr+dM0VQ+izJegPuUSjWKCYLemhBet2Lt5NypgkyFwYk\nHQ4MEQKBgCeQOxNn2exJj0B6wt0Ts+tHdQlreLv+7zMB+CWODnkaXAiRqB8mr1O1\nmFZApPHnx3HUrxRsiHfvf9m2N2gpzyVcK86zbQSti5PB9sqEMw5eHd1qtlPSOV31\nJUG9qpLL/Jf6+AsZCNGOrjMQD99Sh3x/tPZVbK49OyOe6HxV5Ht0\n-----END RSA PRIVATE KEY-----\n",
    • "key_id": "e0054_da789_101721a053024156a34e0df8a9c388d4",
    • "keyfile": "/var/cpanel/ssl/system/keys/e0054_da789_101721a053024156a34e0df8a9c388d4.key",
    • "sender": "admin",
    • "sender_host": "hostname.example.com"
    },
  • "metadata": {
    • "command": "generatessl",
    • "reason": "Key, Certificate, and CSR generated OK",
    • "result": 1,
    • "version": 1
    }
}

Return domains with installed SSL certificates

This function lists the server's domains with installed SSL certificates.

Authorizations:
BasicAuth
query Parameters
registered
integer
Default: 0
Possible Values: 1 0
Example: registered=1

Whether to limit the results to certificates registered with a certificate authority (CA).

  • 1 — Registered certificates only.
  • 0 — All certificates.
user
string <username>
Example: user=username

The cPanel username.

If you do not use this parameter, the function returns certificates for all accounts on the server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  listcrts

Response samples

Content type
application/json
{
  • "data": {
    • "crt": [
      • {
        • "domain": "example.com",
        • "domain_owners": [
          • "username"
          ],
        • "domains": [
          • "example.com"
          ],
        • "ecdsa_curve_name": null,
        • "friendly_name": "TestCertificate",
        • "id": "example._com_d13b4_362b9_1400343187_b05e5c3e443dda9a8869c4cf7457829e",
        • "is_self_signed": 1,
        • "issuer.organizationName": "Organization",
        • "key_algorithm": "rsaEncryption",
        • "modulus_length": 2048,
        • "not_after": 1601467200,
        • "registered": 1,
        • "signature_algorithm": "sha256WithRSAEncryption",
        • "validation_type": "dv"
        }
      ]
    },
  • "metadata": {
    • "command": "listcrts",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update SSL certificate users database

This function rebuilds the database of SSL certificate users.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  rebuilduserssldb

Response samples

Content type
application/json
{
  • "data": {
    • "records": [
      • "username"
      ]
    },
  • "metadata": {
    • "command": "rebuilduserssldb",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create self-signed SSL certificate for service

This function regenerates a self-signed SSL certificate and assigns it to a service.

Authorizations:
BasicAuth
query Parameters
service
required
string
Possible Values: "ftp" "exim" "dovecot" "cpanel"
Example: service=cpanel

The service.

  • ftp - The ftp service.
  • exim - The exim service.
  • dovecot - The dovecot service.
  • cpanel - The cpanel service.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  reset_service_ssl_certificate \
  service='cpanel'

Response samples

Content type
application/json
{
  • "data": {
    • "certificate": "-----BEGIN CERTIFICATE-----\nMIIDWzCCAkOgAwIBAgIFAiil8fgwDQYJKoZIhvcNAQELBQAwRjEcMBoGA1UEAwwT\ndm01LmRvY3MuY3BhbmVsLm5ldDEmMCQGCSqGSIb3DQEJARYXc3NsQHZtNS5kb2Nz\nLmNwYW5lbC5uZXQwHhcNMTQxMTI0MTg0NDE5WhcNMTUxMTI0MTg0NDE5WjBGMRww\nGgYDVQQDDBN2bTUuZG9jcy5jcGFuZWwubmV0MSYwJAYJKoZIhvcNAQkBFhdzc2xA\ndm01LmRvY3MuY3BhbmVsLm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAKYsBFQaqfz9ggP2uw+Vm4196hDlgZtx/A7cN7ktDkCzztxpQ1Us6zty0DPB\nKm6aMhi8tvfO1/DU8+L2ybmgXXmAvhMjEdBYtiMd7rUVAo4zuPOzwABJzfTq46Wk\ntQiuT9TZ+051ixFLRyz58ke0jAqqQugeZK1d5q1m82lUow3LU3oPhtYiR31ROU4g\nHt1/p+okMf3T21Bl6lLXQf8EVwUL8c0zrRsLYlhIFGyedaVqoZ47anGFc0U0ZJzw\nBOXnmxbYZY+pExXiNZpxTjUDKgtLvY8CjrHjNgVXSL9S7J8Src4/l7SvKoRjnAit\nKsMh6d/nTC4bukX5FGBph9anoFcCAwEAAaNQME4wHQYDVR0OBBYEFDBzN9RDgdnH\nHx5x7iUeBDX8qQ3yMB8GA1UdIwQYMBaAFDBzN9RDgdnHHx5x7iUeBDX8qQ3yMAwG\nA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBACYT6VSDfRxsGIzzoYMlIN9K\nd1pfDqFVFKZecI9M+fc0iAnYYRm5VUpItw5fAoMbrjCL4XMZKImSmkAWc4m9cCDs\nWT4rSEE/Fhv3dUjI3Hg7CFoxwU+Ke+yORsPNCv/9lDjReh9pU120UIttOa1lu9NN\nkT8QcUN0+NAvhj6MTm87VsQBNEpQhddyPuOmtga/zf8HTOcvtbeoRTueVNa4yNvP\n3UI6FLwNWNebzgm5zunahY7svqrTbKkNbQbIFqHrhSZdY5i7+I7Lgi9hfri7nDDk\nl6Dv+Ntm0LKWJNEKuZ8I+QVuJiFIFqF/8Gsqc/8pDuJF3b7UchyqGCXJhnExBR4=\n-----END CERTIFICATE-----",
    • "certificate_info": {
      • "domains": [
        • "example.com"
        ],
      • "ecdsa_curve_name": null,
      • "ecdsa_public": null,
      • "is_self_signed": 1,
      • "issuer.commonName": "example.com",
      • "issuer.organizationName": "Writer's Guild of America",
      • "issuer_text": "commonName\nhostname.example.com\nemailAddress\[email protected]",
      • "key_algorithm": "rsaEncryption",
      • "modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
      • "modulus_length": 2048,
      • "not_after": 1398805499,
      • "not_before": 1367269499
      },
    • "service": "ftp"
    },
  • "metadata": {
    • "command": "reset_service_ssl_certificate",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Install or Uninstall Package

System Package Management / Install or Uninstall Package

Start RPM package installation, update, or removal

This function installs, upgrades, or uninstalls RPM packages.

Note:

The system queues this function's actions to run as background tasks. The actions may require additional time to finish.

Authorizations:
BasicAuth
query Parameters
install
string
Examples:
  • install=install=package1 install=package2 - Install multiple RPM packages.
  • install=package1 - Install a single RPM package.

The RPM package that you want to install. If you do not use this parameter, the function does not install a package.

Note:

You can pass this parameter multiple times to install more than one RPM package

uninstall
string
Examples:
  • uninstall=uninstall=package3 uninstall=package4 uninstall=package5 - Uninstall multiple RPM packages.
  • uninstall=package3 - Uninstall a single RPM package.

The RPM package that you want to uninstall. If you do not use this parameter, the function does not uninstall a package.

Note:

You can pass this parameter multiple times to uninstall more than one RPM package.

upgrade
string
Examples:
  • upgrade=upgrade=package6 upgrade=package7 upgrade=package8 - Upgrade multiple RPM packages.
  • upgrade=package6 - Upgrade a single RPM package.

The RPM package that you want to upgrade. If you do not use this parameter, the function does not upgrade a package.

Note:

You can pass this parameter multiple times to upgrade more than one RPM package.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_submit_actions

Response samples

Content type
application/json
{
  • "data": {
    • "build": 9717
    },
  • "metadata": {
    • "command": "package_manager_submit_actions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Start RPM package upgrade

This function downloads and installs package updates on the server.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_upgrade

Response samples

Content type
application/json
{
  • "data": {
    • "build": 10111
    },
  • "metadata": {
    • "command": "package_manager_upgrade",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Install WHM plugin RPM package

This function starts a plugin installation. The installation runs as a background process.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=plugin name

The name of a plugin RPM to install.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  install_rpm_plugin \
  name='plugin name'

Response samples

Content type
application/json
{
  • "data": {
    • "log_entry": "2017-01-01T19:39:27Z_plugin_name",
    • "pid": 1234
    },
  • "metadata": {
    • "command": "install_rpm_plugin",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Uninstall WHM plugin RPM package

This function starts the uninstall process for a plugin. The uninstall process runs as a background process.

Authorizations:
BasicAuth
query Parameters
name
required
string
Example: name=plugin_name

The name of a plugin RPM to uninstall.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  uninstall_rpm_plugin \
  name='plugin_name'

Response samples

Content type
application/json
{
  • "data": {
    • "log_entry": "2017-01-01T19:39:27Z_plugin_name",
    • "pid": 1234
    },
  • "metadata": {
    • "command": "uninstall_rpm_plugin",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

List Package Information

System Package Management / List Package Information

Return RPM package update status

This function checks the activity of the process that you executed in the WHM API 1 package_manager_submit_actions function.

Authorizations:
BasicAuth
query Parameters
build
required
integer
Example: build=10053

The process's build number returned by the WHM API 1 package_manager_submit_actions function.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_is_performing_actions \
  build='10053'

Response samples

Content type
application/json
{
  • "data": {
    • "active": 1
    },
  • "metadata": {
    • "command": "package_manager_is_performing_actions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available RPM packages

This function lists information about the system's available RPM packages.

Authorizations:
BasicAuth
query Parameters
state
string
Default: "any"
Possible Values: "any" "installed" "not_installed" "updatable"
Example: state=installed

Return RPM packages that exist in a specified state.

  • any — All RPMs available on the system.
  • installed — The RPMs installed on the system.
  • not_installed — The available RPMs not yet installed on the system.
  • updatable — The RPMs with updates available.

Responses

Response Schema: application/json
object

A list of RPM objects that match the requested state.

object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_list_packages

Response samples

Content type
application/json
{
  • "data": {
    • "packages": [
      • {
        • "package": "MariaDB-client"
        },
      • {
        • "package": "MariaDB-common"
        }
      ]
    },
  • "metadata": {
    • "command": "package_manager_list_packages",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available RPM packages

This function lists a key's available RPMs. For more information, read our rpm.versions system documentation.

Authorizations:
BasicAuth
query Parameters
key
string
Example: key=3rdparty

The RPM's key. If you do not specify a value, the function returns all RPM categories.

section
required
string
Example: section=rpm_groups

The RPM's section.

Responses

Response Schema: application/json
object or object

The RPM section and its associated RPMs.

Note:

  • This function uses the RPM section's name and RPM key's name for each return value.
  • If you specify the key parameter, this function returns only the called RPM key.
  • If you do not specify the key parameter, the function returns all RPM keys in the called section parameter.
object

Request samples 

whmapi1 --output=jsonpretty \
  get_rpm_version_data \
  section='rpm_groups'

Response samples

Content type
application/json
{
  • "data": {
    • "3rdparty": [
      • "cpanel-pcre",
      • "cpanel-pixman",
      • "cpanel-analog"
      ]
    },
  • "metadata": {
    • "command": "get_rpm_version_data",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return required but uninstalled server RPM package

This function lists RPMs that the server needs, but the server owner has not yet installed. When you call this function, it performs the same actions as the following command:

/usr/local/cpanel/scripts/check_cpanel_pkgs --list-only --targets[target]

For more information, read our rpm.versions system documentation.

Authorizations:
BasicAuth
query Parameters
target
string
Example: target=3rdparty

The target that depends on the uninstalled RPMs. If you do not specify a value, the function lists all of the required but uninstalled RPMs for all RPM targets.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  list_rpms

Response samples

Content type
application/json
{
  • "data": {
    • "rpms": [
      • "cpanel-pcre"
      ]
    },
  • "metadata": {
    • "command": "list_rpms",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return available RPM packages information

This function retrieves information about the system's available RPM packages.

Note:

You must use either the ns or the package parameters.

Authorizations:
BasicAuth
query Parameters
disable-excludes
integer
Default: 0
Possible Values: 1 0
Example: disable-excludes=1

Whether the system will disable yum's exclude behavior.

  • 1 — Disable yum's exclude behavior.
  • 0 — Do not disable yum's exclude behavior.
ns
required
string
Value: "ea"
Examples:
  • ns=ns=ea ns=altea - View multiple namespaces.
  • ns=ea - View one namespace.

An available RPM package namespace.

Note:

  • ea and any from ea4_get_additional_pkg_prefixes API call are the only possible values.
  • If you use this parameter, you cannot use the package parameter.
  • To view more than one namespace, pass the parameter multiple times. For example, ns=ea and ns=altea.
package
required
string
Examples:
  • package=package=ea-php55 package=ea-apr-util - View multiple packages.
  • package=ea-php55 - View one package.

An RPM package name on the system.

Note:

  • If you use this parameter, you cannot use the ns parameter.
  • To view more than one package, pass the parameter multiple times. For example, package=ea-php55 and package=ea-apr-util.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_get_package_info \
  ns='ea' \
  package='ea-php55'

Response samples

Content type
application/json
{
  • "data": {
    • "packages": [
      • {
        • "architecture": "x86_64",
        • "license": "ASL 2.0",
        • "long_description": "The mission of the Apache Portable Runtime (APR) is to provide a\\nfree library of C data structures and routines.",
        • "more_info_url": "http://apr.apache.org",
        • "package": "ea-apr-util",
        • "pkg_dep": {
          • "conflicts": [
            • "ea-php55-php-ioncube5"
            ],
          • "requires": [
            • "glibc",
            • "libuuid",
            • "expat",
            • "libdb",
            • "ea-apr"
            ]
          },
        • "pkg_group": "System Environment/Libraries",
        • "release": "7.7.1.cpanel",
        • "repo_name": "NYI",
        • "short_description": "Apache Portable Runtime Utility library",
        • "size": 214647,
        • "state": "updatable",
        • "version": "1.6.1",
        • "version_installed": "1.6.1-4.4.8.cpanel",
        • "version_latest": "1.6.1-7.7.1.cpanel"
        }
      ]
    },
  • "metadata": {
    • "command": "package_manager_get_package_info",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return possible RPM package changes

This function determines the actions that would result from the provisioning of a specified RPM package or packages.

Authorizations:
BasicAuth
query Parameters
ns
string
Value: "ea"
Examples:
  • ns=ns=ea ns=altea - Operate under multiple namespaces.
  • ns=ea - Operate under one namespace.

The RPM namespace that represents a set of packages. Note:

  • ea and any from ea4_get_additional_pkg_prefixes API call are the only possible values. * When more than one namespace is involved, pass the parameter multiple times. For example, ns=ea and ns=altea.
package
required
string
Examples:
  • package=package=ea-apache24-mod_headers package=ea-apache24-mod_cgid package=ea-apache24-mod_mpm_event - Submit multiple RPM packages.
  • package=ea-apache24-mod_headers - Submit a single RPM package.

The name of an RPM package.

Note:

  • To submit more than one package, pass the parameter multiple times. For example, package=ea-php55 and package=ea-apr-util.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_resolve_actions \
  package='ea-apache24-mod_headers'

Response samples

Content type
application/json
{
  • "data": {
    • "install": [
      • "ea-apache24-mod_mpm_event",
      • "ea-apache24-mod_cgid"
      ],
    • "unaffected": [
      • "ea-php70-php-devel",
      • "ea-php56-runtime",
      • "ea-php55-php-common",
      • "ea-apache24-mod_headers",
      • "ea-php56-php-bcmath",
      • "ea-php70-php-curl",
      • "ea-php70-php-xml"
      ],
    • "uninstall": [
      • "ea-apache24-mod_cgi",
      • "ea-apache24-mod_mpm_prefork"
      ],
    • "upgrade": [
      • "ea-php56"
      ]
    },
  • "metadata": {
    • "command": "package_manager_resolve_actions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Package Manager Settings

System Package Management / Package Manager Settings

Return RPM management build log

This function returns build log content.

Authorizations:
BasicAuth
query Parameters
build
required
integer >= 1
Example: build=1234

The build process ID returned by the package_manager_submit_actions function.

offset
required
integer <bytes> >= 0
Example: offset=4567

The position in the build log from which you wish to display entries.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_get_build_log \
  build='1234' \
  offset='4567'

Response samples

Content type
application/json
{
  • "data": {
    • "content": [
      • "line1",
      • "line2",
      • "line3"
      ],
    • "offset": 9672,
    • "still_running": 1
    },
  • "metadata": {
    • "command": "package_manager_get_build_log",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Repair RPM management yum cache issues

This function attempts to repair yum cache issues.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  package_manager_fixcache

Response samples

Content type
application/json
{
  • "data": {
    • "cache_seems_ok_now": 1
    },
  • "metadata": {
    • "command": "package_manager_fixcache",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove rpm.versions system configuration

This function removes RPM data. When you call this function, it performs the same actions as the following command:

/usr/local/cpanel/scripts/update_local_rpm_versions --del section.key value

For more information, read our rpm.versions system documentation.

Note:

After you call this function, we strongly recommend that you run the /usr/local/cpanel/scripts/check_cpanel_pkgs script.

Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=3rdparty
section
required
string
Example: section=rpm_groups

The RPM's section within the rpm.versions file.

value
required
string
Example: value=cpanel-pcre

The RPM name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_rpm_version \
  section='rpm_groups' \
  key='3rdparty' \
  value='cpanel-pcre'

Response samples

Content type
application/json
{
  • "data": {
    • "status": 1
    },
  • "metadata": {
    • "command": "delete_rpm_version",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update rpm.versions system configuration

This function edits RPM data. When you call this function, it performs the same actions as the following command:

/usr/local/cpanel/scripts/update_local_rpm_versions --edit section.key value

For more information, read our rpm.versions system documentation.

Note:

After you call this function, we strongly recommend that you run the /usr/local/cpanel/scripts/check_cpanel_pkgs script.

Authorizations:
BasicAuth
query Parameters
key
required
string
Example: key=3rdparty

The RPM's key.

section
required
string
Example: section=rpm_groups

The RPM's section.

value
required
string
Example: value=cpanel-pcre

The RPM's value.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  edit_rpm_version \
  section='rpm_groups' \
  key='3rdparty' \
  value='cpanel-pcre'

Response samples

Content type
application/json
{
  • "data": {
    • "status": 1
    },
  • "metadata": {
    • "command": "edit_rpm_version",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

cPanel Account Transfer

Transfers / cPanel Account Transfer

Stop transfer session

This function aborts an active transfer session.

Authorizations:
BasicAuth
query Parameters
transfer_session_id
required
string
Example: transfer_session_id=exampleservercopya20140206192428NtyW

The transfer session's ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  abort_transfer_session \
  transfer_session_id='exampleservercopya20140206192428NtyW'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "abort_transfer_session",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create remote server transfer session as root user

This function creates a transfer session as the root user.

Important:

For information about the ports that cPanel & WHM uses, read our How to Configure Your Firewall for cPanel Services documentation.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authentication

There are several methods that you can use to authenticate a transfer session with the remote server:

Authenticate as root

If you use SSH to authenticate as the root user, the remote server's SSH must accept root logins. For more information read OpenSSH's sshd_config documentation.

The following table displays the correct parameters and values for this authentication method:

Parameter Value
user root
password root's password

You can also use an SSH public key to authenticate the root user. If the SSH public key is encrypted, include the SSH key's passphrase.

The following table displays the correct parameters and values for this authentication method:

Parameter Value if the SSH Key is not encrypted Value if the SSH Key is encrypted
user root root
sshkey_name The root user's SSH key. The root user's SSH key.
sshkey_passphrase (none) The root user's SSH key passphrase.

Authenticate as a user

Many server administrators do not permit direct root logins via SSH on their servers.

  • If the remote server forbids root logins, you must use another user and their password on the remote server, and then escalate to the root user. For more information read OpenSSH's sshd_config documentation.
  • If the system administrator used WHM's Manage Wheel Group Users interface (WHM >> Home >> Security Center >> Manage Wheel Group Users) to grant the user su access, then you will need to specify su and the root password.
  • If the user has sudo access, you do not need the root password.

The following table displays the correct parameters and values for this authentication method:

Parameter Value if the user has sudo access Value if the user has su access
user The username. The username.
password The user's password. The user's password.
root_escalation_method sudo su
root_password (none) The root user's password.

You can also use an SSH public key instead of a password to authenticate that user. If the SSH public key is encrypted, include the SSH key's passphrase.

The following table displays the correct parameters and values for this authentication method:

Parameter sudo su
user The username. The username.
sshkey_name The user's SSH key. The user's SSH key.
sshkey_passphrase (If encrypted) The user's SSH key passphrase. The user's SSH key passphrase.
root_escalation_method sudo su
root_password (none) The root user's password.
Authorizations:
BasicAuth
query Parameters
comm_transport
required
string
Default: "ssh"
Possible Values: "ssh" "whostmgr" "whostmgr_insecure"
Example: comm_transport=ssh

The method by which the transfer system will execute commands on the remote system.

  • ssh — Use SSH. The function uses the remote server's indicated SSH port value.
  • whostmgr — Use the remote server's secure WHM port. This will reject invalid TLS handshakes.
  • whostmgr_insecure — Use the remote server's secure WHM port, but ignores any TLS verification failures.
compressed
required
integer
Possible Values: 0 1
Example: compressed=1

Whether to compress data before transfer.

  • 1 — Compress.
  • 0 — Do not compress.
copy_reseller_privs
required
integer
Possible Values: 0 1
Example: copy_reseller_privs=1

Whether to transfer reseller privileges.

  • 1 — Transfer.
  • 0 — Do not transfer.
enable_custom_pkgacct
required
integer
Possible Values: 0 1
Example: enable_custom_pkgacct=1

Whether to use a custom pkgacct scripts on the remote server for the transfer session.

  • 1 — Use a custom pkgacct script.
  • 0 — Do not use a custom script.
required
string or string
Example: host=192.168.0.0

The remote server's hostname or IP address.

low_priority
required
integer
Possible Values: 0 1
Example: low_priority=1

Whether to run the remote server processes at low priority in order to reduce impact on server performance.

  • 1 — Run at low priority.
  • 0 — Run at high priority.
password
string
Example: password=123456luggage

The username's password.

Note:

Use this parameter if you will authenticate to the remote server with a password. Do not use this parameter if you will authenticate to the remote server with an SSH key.

port
integer [ 1 .. 65535 ]
Default: 22
Example: port=22

The remote server's SSH port number.

restore_threads
required
integer >= 1
Example: restore_threads=1

The number of CPU threads to use for restore sessions.

root_escalation_method
string
Possible Values: "su" "sudo"
Example: root_escalation_method=sudo

The escalation method to use to connect to the remote server.

  • su
  • sudo

Note:

Use this parameter if the sshd_config file's PermitRootLogin value is No.

root_password
string
Example: root_password=123456luggage

root's password on the remote server.

Note:

Use this parameter if the sshd_config file's PermitRootLogin value is No and you will use the root user's password to escalate access.

sshkey_name
string
Example: sshkey_name=FrancisScott

The SSH key's name.

Note:

  • Use this parameter if you will authenticate to the remote server with an SSH key. Do not use this parameter if you will authenticate to the remote server with a password.
  • SSH keys are available in WHM's Manage root's SSH Keys interface (WHM >> Home >> Security Center >> Manage root’s SSH Keys).
sshkey_passphrase
string
Example: sshkey_passphrase=kkwtoowoygidsa

The SSH key's passphrase.

Note:

Use this parameter if you will authenticate to the remote server with an SSH key, and the key is encrypted.

transfer_threads
required
integer >= 1
Example: transfer_threads=1

The number of CPU threads to use for transfer sessions.

unencrypted
required
integer
Possible Values: 0 1
Example: unencrypted=0

Whether to not use SSL to encrypt data.

  • 1 — Do not use SSL.
  • 0 — Use SSL.
unrestricted_restore
required
integer
Possible Values: 0 1
Example: unrestricted_restore=1

Whether to skip the Restricted Restore system.

  • 1 — Skip.
  • 0 — Do not skip.

Note:

If you want to pass the force parameter in the WHM API 1 enqueue_transfer_item function, you must set this parameter to a value of 0.

use_backups
required
integer
Possible Values: 0 1
Example: use_backups=1

Whether to use an existing backup instead of packaging the data again if the backup is less than 24 hours old.

  • 1 — Use an existing backup.
  • 0 — Package the data.
user
required
string
Example: user=root

The username to use to connect to the remote server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_remote_root_transfer_session \
  host='192.168.0.0' \
  user='root' \
  transfer_threads='1' \
  restore_threads='1' \
  unrestricted_restore='1' \
  comm_transport='ssh' \
  copy_reseller_privs='1' \
  compressed='1' \
  unencrypted='0' \
  use_backups='1' \
  low_priority='1' \
  enable_custom_pkgacct='1'

Response samples

Content type
application/json
{
  • "data": {
    • "analyze_rawout": "Fetching information from remote host: \\u201c10.1.100.35\\u201d \\u2026 \\u2026\\nDone\\nFetching information from remote host: \\u201c10.1.100.35\\u201d \\u2026 \\u2026\\nDone\\n\",",
    • "create_rawout": "Basic credential check \\u2026 \\u2026\\nDone\\nFetching information from remote host: \\u201c10.1.100.35\\u201d \\u2026 \\u2026\\nDone\\nFetching WHM Version \\u2026\\nDone\\nTesting \\u201cvm5.docs.cpanel.net\\u201d for transfer streaming support with password authentication....<strong>Streaming Supported</strong>\\nRemote Server Type: \\u201cWHM1130\\u201d\\n\",",
    • "transfer_session_id": "vm5docscpanelcopya20140430200606V06z"
    },
  • "metadata": {
    • "command": "create_remote_root_transfer_session",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create remote server transfer session

This function creates a transfer session with a non-root user to a remote server.

Important:

  • The source and target servers must be able to communicate over port 2087 to use this feature.
  • The source and target servers must also be able to communicate over the port that your servers use for SSH connections.
  • For more information about the ports that cPanel & WHM uses, read our How to Configure Your Firewall for cPanel & WHM Services documentation.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
host
required
string <domain>
Example: host=hostname.example.com

The server hostname for the account.

password
required
string
Example: password=12345luggage

The account's password.

unrestricted_restore
required
integer
Value: 1
Example: unrestricted_restore=1

Whether to skip the Restricted Restore process.

  • 1 - Skip Restricted Restore.
  • 0 - Use Restricted Restore.

Note:

You must set this parameter to a value of 1.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  create_remote_user_transfer_session \
  host='hostname.example.com' \
  password='12345luggage' \
  unrestricted_restore='1'

Response samples

Content type
application/json
{
  • "data": {
    • "transfer_session_id": "vm5docscpanelnoroo201402251939519hmy"
    },
  • "metadata": {
    • "command": "create_remote_user_transfer_session",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add module to transfer session

This function adds a transfer session to a queue. For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Important:

The module parameter determines which additional parameters to use with the function.

Authorizations:
BasicAuth
Request Body schema: application/x-www-form-urlencoded

An enqueue transfer item.

localuser
required
string <username>

The local account's username.

module
required
string

The transfer system module.

  • LegacyAccountBackup — This module restores legacy-account backup files.
  • FeatureListRemoteRoot — This module transfers the feature list from the remote server.
  • PackageRemoteRoot — This module transfers the package settings.
  • AccountLocal — This module restores backup files.
  • AccountRemoteRoot — This module uses the root credentials to transfer account settings that are not a part of a package.
  • AccountRemoteUser — This module uses the account's user credentials to transfer account settings that are not a part of a package.

Note:

  • The module parameter determines which additional parameters to use with the function.
  • You must perform each module action as a separate step.

When you call this function, you must include the additional parameters for the desired transfer system module. Select a module from the menu to view its required additional parameters:

transfer_session_id
required
string

The transfer session's ID.

user
required
string <username>

The account to transfer.

customip
string

The custom IP address to assign to the transferred account.

Note:

This parameter requires that the ip parameter has a value of 1.

detected_remote_user
string

The user account name that the remote server returns when you query the user account.

domain
string <domain>

The domain name.

force
integer
Possible Values: 0 1

Whether to overwrite an account with an identical username.

  • 1 — Overwrite the account.
  • 0 — Do not overwrite the account.

This parameter performs the following actions:

  • Restores the cPanel account on the destination server.
  • Overwrites all account settings, data, and databases.
  • Ignores errors and warnings for naming conflicts.

Note:

  • The values you enter for the user and localuser parameters must match.
  • You cannot use this parameter if you called the WHM API 1 create_remote_root_transfer_session function with the unrestricted_restore parameter set to 1.
ip
integer
Possible Values: 0 1

Whether to assign a dedicated IP address to the transferred account.

  • 1 — Assign a dedicated IP address.
  • 0 — Do not assign a dedicated IP address.

Note:

If no dedicated IP address exists, the system assigns the account to a shared IP address.

string or string
Default: ".existing"

The server on which the account's email will reside after it completes the transfer.

  • .local — The local server.
  • .existing — Use the location defined in the account's backup data.
  • The alias (friendly name) of a remote cPanel & WHM linked server node.. For example, the example-alias for the servernode.example.com domain.

Note:

The system will use the .local option if:

  • The system cannot use the cPanel & WHM linked server node when you call the .existing option.
  • The cPanel & WHM linked server node's alias (friendly name) is invalid.
overwrite_sameowner_dbs
integer
Possible Values: 0 1

Whether to allow the system to overwrite the account's existing databases with the databases in the backup file.

  • 1 — Overwrite.
  • 0 — Do not overwrite.
overwrite_sameowner_dbusers
integer
Possible Values: 0 1

Whether to allow the system to overwrite the account's existing database users with the database users in the backup file.

  • 1 — Overwrite.
  • 0 — Do not overwrite.
overwrite_with_delete
integer
Possible Values: 0 1

Whether to replace and delete all directories and files on the destination server.

  • 1 — Overwrite.
  • 0 — Do not overwrite.

Warning:

If you use this parameter, the system deletes every directory and file on the destination server. The system does not delete the directories and files from the source server.

replaceip
string
Possible Values: "all" "basic"

The lines in the domain's zonefile to replace with the new IP address.

  • all — Replace all of the matching A record addresses in the zone file with the new IP address, including custom A records.
  • basic — Replace only the cPanel-managed A records for this IP address. This includes the main domain and any service subdomains.
reseller
integer
Possible Values: 0 1

Whether to make the account a reseller.

  • 1 — Make the account a reseller account.
  • 0 — Do not make the account a reseller account.
shared_mysql_server
integer
Possible Values: 0 1

Whether one of the following conditions is true:

  • The target and remote servers share the same remote MySQL server.
  • The target server is the remote MySQL server for the remote server.
  • The remote server is the remote MySQL server for the target server.

Value:

  • 1 — One is true.
  • 0 — None are true.
size
integer >= 1
Default: 1

The size of the content to transfer, in bytes. The restore system uses this value to determine the best filesystem partition for the restored account’s home directory. For best results, give as accurate of a value as possible.

skipaccount
integer
Possible Values: 0 1

Whether to skip the recreation of the account.

  • 1 — Skip.
  • 0 — Restore.

Note:

  • The values you enter for the user and localuser parameters must match.
  • This parameter is similar to the force parameter, but performs none of the account creation steps.
skipacctdb
integer
Possible Values: 0 1

Whether to skip the transfer of the account's databases.

  • 1 — Skip.
  • 0 — Restore.
skipbwdata
integer
Possible Values: 0 1

Whether to skip the transfer of the account's bandwidth data.

  • 1 — Skip.
  • 0 — Restore.
skiphomedir
integer
Possible Values: 0 1

Whether to skip the contents of the home directory.

  • 1 — Skip.
  • 0 — Restore.
skipres
integer
Possible Values: 0 1

Whether to skip restoration of the account's reseller permissions.

  • 1 — Skip.
  • 0 — Restore.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --input=json --output=jsonpretty \
  enqueue_transfer_item

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "enqueue_transfer_item",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Suspend active transfer session

This function pauses an active transfer session.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
transfer_session_id
required
string
Example: transfer_session_id=exampleservercopya20140206192428NtyW

The transfer session's ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  pause_transfer_session \
  transfer_session_id='exampleservercopya20140206192428NtyW'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "pause_transfer_session",
    • "reason": "OK.",
    • "result": 1,
    • "version": 1
    }
}

Start or restart transfer session

This function starts or restarts a transfer session.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
transfer_session_id
required
string
Example: transfer_session_id=exampleservercopya20140206192428NtyW

The transfer session's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  start_transfer_session \
  transfer_session_id='exampleservercopya20140206192428NtyW'

Response samples

Content type
application/json
{
  • "data": {
    • "pid": 90210
    },
  • "metadata": {
    • "command": "start_transfer_session",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Transfer Configuration

Transfers / Transfer Configuration

Validate remote server's SSH credentials

This function checks the SSH credentials on the remote server.

Authentication

There are several methods that you can use to authenticate a transfer session with the remote server.

PermitRootLogin=Yes

The simplest authentication method is to use the root user and password. To do this, the sshd_config file on the remote server must contain the following value: PermitRootLogin=Yes

The following table displays the correct parameters and values for this authentication method:

Parameter Value
user root
password root's password.

You can also use the SSH Public Key to authenticate the root user. If the SSH Public Key is encrypted, include the SSH Key's passphrase.

The following table displays the correct parameters and values for this authentication method:

Parameter Value if the SSH Key is not encrypted Value if the SSH Key is encrypted
user root root
sshkey_name root's SSH key name. root's SSH key name.
sshkey_passphrase (none) root's SSH key passphrase.

PermitRootLogin=No

Many server administrators do not permit direct root logins on their servers.

  • If the remote server contains PermitRootLogin=No in the sshd_config file, then you must use another user and their password on the remote server, and then escalate to root.
  • If the system administrator used WHM's Manage Wheel Group Users interface (WHM >> Home >> Security Center >> Manage Wheel Group Users) to grant the user su access, then you will need to specify su and the root password.
  • If the user has sudo access, you do not need the root password.

The following table displays the correct parameters and values for this authentication method:

Parameter Value if the user has sudo access Value if the user has su access
user The user's username. The user's username.
password The user's password. The user's password.
root_escalation_method sudo su
root_password (none) root's password.

You can also use an SSH Public Key instead of a password to authenticate that user. If the SSH Public Key is encrypted, include the SSH Key's passphrase.

The following table displays the correct parameters and values for this authentication method:

Parameter sudo su
user The user's username. The user's username.
sshkey_name The user's SSH key name. The user's SSH key name.
sshkey_passphrase (If encrypted) The user's SSH key passphrase. The user's SSH key passphrase.
root_escalation_method sudo su
root_password (none) root's password.
Authorizations:
BasicAuth
query Parameters
required
string or string
Example: host=192.168.0.0

The remote server's hostname or IP address.

password
string
Example: password=123456luggage

The username's password.

port
integer [ 1 .. 65535 ]
Default: 22
Example: port=22

The remote server's SSH port number.

root_escalation_method
string
Possible Values: "su" "sudo"
Example: root_escalation_method=sudo

The escalation method to use to connect to the remote server.

  • su
  • sudo

Note:

Use this parameter if PermitRootLogin=No in the remote server's sshd_config file.

root_password
string
Example: root_password=123456luggage

root's password on the remote server.

Note:

Use this parameter if PermitRootLogin=No in the remote server's sshd_config file and the root_escalation_method value is set to su.

sshkey_name
string
Example: sshkey_name=FrancisScott

The SSH key's name.

Note:

SSH keys are available in WHM's Manage root's SSH Keys interface (WHM >> Home >> Security Center >> Manage root’s SSH Keys).

sshkey_passphrase
string
Example: sshkey_passphrase=kkwtoowoygidsa

The SSH key's passphrase.

Note:

Use this parameter if the SSH Key is encrypted.

user
required
string <username>
Example: user=root

The username to use to connect to the remote server.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  remote_basic_credential_check \
  host='192.168.0.0' \
  user='root'

Response samples

Content type
application/json
{
  • "data": {
    • "output": "Basic credential check…\nDone\n",
    • "response": "basic credential check\n"
    },
  • "metadata": {
    • "command": "remote_basic_credential_check",
    • "reason": "Success",
    • "result": 1,
    • "version": 1
    }
}

Validate username availability on target server

This function validates a system user for use on the target server.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
user
required
string
Example: user=username

The system username.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  validate_system_user \
  user='username'

Response samples

Content type
application/json
{
  • "data": {
    • "exists": 1,
    • "reserved": 1,
    • "valid_for_new": 1,
    • "valid_for_transfer": 1
    },
  • "metadata": {
    • "command": "validate_system_user",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove cPanel account's archives

This function removes a cPanel user account's archives.

Authorizations:
BasicAuth
query Parameters
mountpoint
string
Default: "/home"
Example: mountpoint=/home/example/

The filepath to the archive storage location.

user
required
string <username>
Example: user=username

The cPanel account username.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  delete_account_archives \
  user='username'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "delete_account_archives",
    • "output": {
      • "messages": [
        • "Found archive: /home/example/example.tar.gz"
        ],
      • "warnings": [
        • "This is a warning message."
        ]
      },
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return a transfer module's schema

This function retrieves a transfer module's key structure.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
module
required
string
Possible Values: "AccountLocal" "AccountRemoteRoot" "AccountRemoteUser" "FeaturesListRemoteRoot" "LegacyAccountBackup" "PackageRemoteRoot"
Example: module=AccountRemoteRoot

The transfer module's name.

  • AccountLocal
  • AccountRemoteRoot
  • AccountRemoteUser
  • FeaturesListRemoteRoot
  • LegacyAccountBackup
  • PackageRemoteRoot

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  transfer_module_schema \
  module='AccountRemoteRoot'

Response samples

Content type
application/json
{
  • "data": {
    • "schema": {
      • "keys": {
        • "copypoint": {
          • "def": "text"
          },
        • "cpmovefile": {
          • "def": "text"
          },
        • "customip": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "detected_remote_user": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "disabled": {
          • "def": "text"
          },
        • "domain": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "files": {
          • "def": "BIGINT UNSIGNED DEFAULT 1"
          },
        • "force": {
          • "def": "int(1) DEFAULT 0"
          },
        • "ip": {
          • "def": "int(1) DEFAULT 0"
          },
        • "live_transfer": {
          • "def": "int(1) DEFAULT 0"
          },
        • "localuser": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "mail_location": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "overwrite_all_dbs": {
          • "def": "int(1) DEFAULT 0"
          },
        • "overwrite_all_dbusers": {
          • "def": "int(1) DEFAULT 0"
          },
        • "overwrite_sameowner_dbs": {
          • "def": "int(1) DEFAULT 0"
          },
        • "overwrite_sameowner_dbusers": {
          • "def": "int(1) DEFAULT 0"
          },
        • "overwrite_with_delete": {
          • "def": "int(1) DEFAULT 0"
          },
        • "prerequisite_user": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "priority": {
          • "def": "int(1) DEFAULT 255"
          },
        • "replaceip": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "reseller": {
          • "def": "int(1) DEFAULT 0"
          },
        • "shared_mysql_server": {
          • "def": "int(1) DEFAULT 0"
          },
        • "size": {
          • "def": "BIGINT UNSIGNED DEFAULT 1"
          },
        • "skipaccount": {
          • "def": "int(1) DEFAULT 0"
          },
        • "skipacctdb": {
          • "def": "int(1) DEFAULT 0"
          },
        • "skipbwdata": {
          • "def": "int(1) DEFAULT 0"
          },
        • "skipemail": {
          • "def": "int(1) DEFAULT 0"
          },
        • "skiphomedir": {
          • "def": "int(1) DEFAULT 0"
          },
        • "skipres": {
          • "def": "int(1) DEFAULT 0"
          },
        • "skipsubdomains": {
          • "def": "int(1) DEFAULT 0"
          },
        • "user": {
          • "def": "char(255) DEFAULT NULL"
          },
        • "xferpoint": {
          • "def": "int(1) DEFAULT 0"
          }
        },
      • "primary": [
        • "user"
        ],
      • "required": [
        • "user",
        • "localuser"
        ]
      }
    },
  • "metadata": {
    • "command": "transfer_module_schema",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Transfer Monitoring

Transfers / Transfer Monitoring

Return available transfer modules

This function lists all available transfer modules.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  available_transfer_modules

Response samples

Content type
application/json
{
  • "data": {
    • "modules": {
      • "AccountLocal": "5000",
      • "AccountRemoteRoot": "3000",
      • "AccountRemoteUser": "4000",
      • "FeatureListRemoteRoot": "1000",
      • "LegacyAccountBackup": "6000",
      • "PackageRemoteRoot": "2000"
      }
    },
  • "metadata": {
    • "command": "available_transfer_modules",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate remote server's credentials

This function checks the remote server's credentials, which a transfer session uses to connect.

Authorizations:
BasicAuth
query Parameters
transfer_session_id
required
string
Example: transfer_session_id=exampleservercopya20140206192428NtyW

The transfer session's ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  analyze_transfer_session_remote \
  transfer_session_id='exampleservercopya20140206192428NtyW'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "analyze_transfer_session_remote",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return transfer session's status

This function retrieves the state of a transfer session.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
transfer_session_id
required
string
Example: transfer_session_id=exampleservercopya20140206192428NtyW

The transfer session's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_transfer_session_state \
  transfer_session_id='exampleservercopya20140206192428NtyW'

Response samples

Content type
application/json
{
  • "data": {
    • "state_name": "TRANSFER_INPROGRESS"
    },
  • "metadata": {
    • "command": "get_transfer_session_state",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return transfer session's log file

This function returns a transfer session's log file.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
required
string or string
Example: logfile=master.log

The log file's name.

transfer_session_id
required
string
Example: transfer_session_id=vm5docscpanelcopya20140224163412sylG

The transfer session's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  fetch_transfer_session_log \
  transfer_session_id='vm5docscpanelcopya20140224163412sylG' \
  logfile='master.log'

Response samples

Content type
application/json
{
  • "data": {
    • "log": "{\"contents\":{\"action\":\"start\",\"time\":1598991042,\"child_number\":0},\"pid\":12789,\"type\":\"control\",\"indent\":0,\"partial\":0}\n{\"partial\":0,\"indent\":0,\"type\":\"control\",\"pid\":12789,\"contents\":{\"time\":1598991042,\"action\":\"initiator\",\"child_number\":0,\"msg\":\"norootcopy\"}}\n{\"partial\":0,\"indent\":0,\"pid\":12789,\"type\":\"control\",\"contents\":{\"msg\":2.3,\"child_number\":0,\"time\":1598991042,\"action\":\"version\"}}\n{\"type\":\"control\",\"pid\":12789,\"contents\":{\"time\":1598991042,\"queue\":\"TRANSFER\",\"action\":\"queue_count\",\"msg\":1,\"child_number\":0},\"partial\":0,\"indent\":0}\n{\"contents\":{\"time\":1598991042,\"action\":\"queue_size\",\"queue\":\"TRANSFER\",\"child_number\":0,\"msg\":1},\"type\":\"control\",\"pid\":12789,\"indent\":0,\"partial\":0}\n{\"type\":\"control\",\"pid\":12789,\"contents\":{\"time\":1598991042,\"queue\":\"RESTORE\",\"action\":\"queue_count\",\"child_number\":0,\"msg\":1},\"partial\":0,\"indent\":0}\n{\"partial\":0,\"indent\":0,\"pid\":12789,\"type\":\"control\",\"contents\":{\"child_number\":0,\"msg\":1,\"time\":1598991042,\"action\":\"queue_size\",\"queue\":\"RESTORE\"}}\n{\"partial\":0,\"indent\":0,\"pid\":12789,\"type\":\"control\",\"contents\":{\"action\":\"remotehost\",\"time\":1598991042,\"msg\":\"10.1.32.200\",\"child_number\":0}}\n{\"partial\":0,\"indent\":0,\"type\":\"control\",\"pid\":12790,\"contents\":{\"item\":\"root\",\"time\":1598991042,\"child_number\":1,\"action\":\"start\",\"queue\":\"TRANSFER\",\"logfile\":\"item-TRANSFER_AccountRemoteUser_root\",\"local_item\":\"root\",\"item_name\":\"Account\",\"item_type\":\"AccountRemoteUser\"}}\n{\"indent\":0,\"partial\":0,\"contents\":{\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"logfile\":\"item-TRANSFER_AccountRemoteUser_root\",\"item_type\":\"AccountRemoteUser\",\"item_name\":\"Account\",\"local_item\":\"root\",\"msg\":\"item-TRANSFER_AccountRemoteUser_root\",\"item\":\"root\",\"time\":1598991042,\"child_number\":1},\"pid\":12790,\"type\":\"control\"}\n{\"indent\":0,\"partial\":0,\"contents\":{\"logfile\":\"item-TRANSFER_AccountRemoteUser_root\",\"item_name\":\"Account\",\"item_type\":\"AccountRemoteUser\",\"local_item\":\"root\",\"msg\":{\"size\":1},\"queue\":\"TRANSFER\",\"action\":\"start-item\",\"child_number\":1,\"item\":\"root\",\"time\":1598991042},\"pid\":12790,\"type\":\"control\"}\n{\"contents\":{\"child_number\":1,\"item\":\"root\",\"time\":1598991042,\"logfile\":\"item-TRANSFER_AccountRemoteUser_root\",\"local_item\":\"root\",\"msg\":{\"dangerous_items\":0,\"skipped_items\":0,\"altered_items\":0,\"failure\":\"The account “root” already exists on “control.box.new”.\",\"size\":1,\"warnings\":0,\"contents\":{\"warnings\":null,\"skipped_items\":null,\"dangerous_items\":null,\"altered_items\":null}},\"item_name\":\"Account\",\"item_type\":\"AccountRemoteUser\",\"queue\":\"TRANSFER\",\"action\":\"failed-item\"},\"type\":\"control\",\"pid\":12790,\"indent\":0,\"partial\":0}\n{\"indent\":0,\"partial\":0,\"contents\":{\"item_type\":\"AccountRemoteUser\",\"item_name\":\"Account\",\"msg\":{\"size\":1},\"local_item\":\"root\",\"logfile\":\"item-RESTORE_AccountRemoteUser_root\",\"action\":\"start-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"time\":1598991042,\"item\":\"root\"},\"type\":\"control\",\"pid\":12790}\n{\"pid\":12790,\"type\":\"control\",\"contents\":{\"item_type\":\"AccountRemoteUser\",\"item_name\":\"Account\",\"msg\":{\"size\":1,\"failure\":\"The account “root” already exists on “control.box.new”.\"},\"local_item\":\"root\",\"logfile\":\"item-RESTORE_AccountRemoteUser_root\",\"action\":\"failed-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"time\":1598991042,\"item\":\"root\"},\"partial\":0,\"indent\":0}\n{\"contents\":{\"time\":1598991042,\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":1},\"pid\":12790,\"type\":\"control\",\"indent\":0,\"partial\":0}\n{\"type\":\"control\",\"pid\":12791,\"contents\":{\"queue\":\"RESTORE\",\"action\":\"complete\",\"time\":1598991043,\"child_number\":1},\"partial\":0,\"indent\":0}\n{\"pid\":12789,\"type\":\"control\",\"contents\":{\"child_number\":0,\"action\":\"complete\",\"time\":1598991043},\"partial\":0,\"indent\":0}\n"
    },
  • "metadata": {
    • "command": "fetch_transfer_session_log",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return transfer session's information

This function analyzes a transfer session.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authorizations:
BasicAuth
query Parameters
transfer_session_id
required
string
Example: transfer_session_id=exampleservercopya20140206192428NtyW

The transfer session's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  retrieve_transfer_session_remote_analysis \
  transfer_session_id='exampleservercopya20140206192428NtyW'

Response samples

Content type
application/json
{
  • "data": {
    • "config": {
      • "shared_mysql_server": 1
      },
    • "items": {
      • "accounts": [ ],
      • "packages": [ ]
      },
    • "local": {
      • "available_ips": [
        • "192.168.1.1"
        ],
      • "dbs": {
        • "dbs": {
          • "MYSQL": {
            • "user_db1": {
              • "owner": "user"
              },
            • "user_db2": {
              • "owner": "user"
              }
            },
          • "PGSQL": {
            • "user_db1": {
              • "owner": "user"
              },
            • "user_db2": {
              • "owner": "user"
              }
            }
          },
        • "users": {
          • "MYSQL": {
            • "user_user1": {
              • "owner": "user"
              },
            • "user_user2": {
              • "owner": "user"
              }
            },
          • "PGSQL": {
            • "user_user1": {
              • "owner": "user"
              },
            • "user_user2": {
              • "owner": "user"
              }
            }
          }
        },
      • "dedicated_ips": {
        • "192.168.1.2": "domain.tld"
        },
      • "domains": {
        • "*": "nobody",
        • "domain.tld": "user"
        },
      • "groups": {
        • "bin": 1,
        • "nobody": 1
        },
      • "host": "hostname.domain.tld",
      • "major_version": "11.90",
      • "roundcube_dbtype": "sqlite",
      • "users": {
        • "nobody": 1,
        • "root": 1
        },
      • "version": "11.90.0.6"
      },
    • "modules": {
      • "Backups": {
        • "analysis": {
          • "Local Backups Version": "11.90.0.6",
          • "Remote Backups Version": "11.88.0.7"
          },
        • "name": "Backups"
        },
      • "MySQL": {
        • "analysis": {
          • "Local Type": "MySQL",
          • "Local Version": "5.7",
          • "Remote Type": "MariaDB",
          • "Remote Version": "10.3"
          },
        • "name": "Database Server"
        }
      },
    • "options": {
      • "skip_reseller_privs": 0,
      • "unrestricted": 0
      },
    • "remote": {
      • "conflicts": { },
      • "cpversion": "11.64",
      • "dbs": {
        • "dbs": {
          • "MYSQL": {
            • "user_db1": {
              • "owner": "user"
              },
            • "user_db2": {
              • "owner": "user"
              }
            },
          • "PGSQL": {
            • "user_db1": {
              • "owner": "user"
              },
            • "user_db2": {
              • "owner": "user"
              }
            }
          },
        • "users": {
          • "MYSQL": {
            • "user_user1": {
              • "owner": "user"
              },
            • "user_user2": {
              • "owner": "user"
              }
            },
          • "PGSQL": {
            • "user_user1": {
              • "owner": "user"
              },
            • "user_user2": {
              • "owner": "user"
              }
            }
          }
        },
      • "has_disk_used": 1,
      • "has_files_used": 1,
      • "has_owners": 1,
      • "has_package_extensions": 1,
      • "has_xfertool": 1,
      • "host": "192.168.1.1",
      • "hostname": "hostname.domain.tld",
      • "linked_nodes": [
        • {
          • "alias": "mailnode",
          • "enabled_services": [
            • "exim",
            • "imap"
            ],
          • "hostname": "remotemailnode.example.com",
          • "last_check": 1600126907,
          • "system_settings": {
            • "Mail": {
              • "globalspamassassin": 0
              }
            },
          • "tls_verified": 1,
          • "username": "root",
          • "version": "11.90.0.6",
          • "worker_capabilities": {
            • "Mail": { }
            }
          }
        ],
      • "major_version": "11.90",
      • "resellers": {
        • "resell2": 1,
        • "reseller": 1,
        • "root": 1
        },
      • "roundcube_dbtype": "sqlite",
      • "server_type": "WHM1164",
      • "supports_live_transfers": 1,
      • "version": "11.90.0.6"
      },
    • "transfer_session_id": "exampleservercopya20140206192428NtyW"
    },
  • "metadata": {
    • "command": "retrieve_transfer_session_remote_analysis",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

UserData

Scoped userdata storage functions.

Get scoped userdata

This function retrieves all userdata key/value pairs within the specified scope.

Authorizations:
BasicAuth
query Parameters
scope
required
string
Example: scope=example_scope

The scope name whose userdata you wish to retrieve.

Responses

Response Schema: application/json
object

A mapping of userdata keys to their string values for the given scope.

object

Request samples 

whmapi1 --output=jsonpretty \
  get_scoped_userdata \
  scope='example_scope'

Response samples

Content type
application/json
{
  • "data": {
    • "theme": "dark",
    • "items_per_page": "50"
    },
  • "metadata": {
    • "command": "get_scoped_userdata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Set scoped userdata

This function sets (creates or updates) a userdata key/value pair within the specified scope and returns the full updated mapping.

Authorizations:
BasicAuth
query Parameters
json
string
Example: json={"theme":"dark"}

A json string to save to the specified scope.

Note: The "json" argument cannot be used with the "key" or "value" arguments.

key
string
Example: key=theme

The userdata key to set.

Note: The "json" argument cannot be used with the "key" or "value" arguments.

scope
required
string
Example: scope=example_scope

The scope name to modify.

value
string
Example: value=dark

The value to assign to the key.

Note: The "json" argument cannot be used with the "key" or "value" arguments.

Responses

Response Schema: application/json
object

The updated mapping of all userdata in the scope.

object

Request samples 

whmapi1 --output=jsonpretty \
  set_scoped_userdata \
  scope='example_scope' \
  key='theme' \
  value='dark'

Response samples

Content type
application/json
{
  • "data": {
    • "theme": "dark",
    • "items_per_page": "50"
    },
  • "metadata": {
    • "command": "set_scoped_userdata",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

EasyApache Settings

Web Server Configuration / EasyApache Settings

Return installed Easyapache 4 packages

This function returns a list of the currently-installed EasyApache 4 packages.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ea4_get_currently_installed_packages

Response samples

Content type
application/json
{
  • "data": {
    • "packages": [
      • "ea-apache24"
      ]
    },
  • "metadata": {
    • "command": "ea4_get_currently_installed_packages",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ea4-metainfo.json file contents

This function returns the contents of the /etc/cpanel/ea4/ea4-metainfo.json file.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object

Contents of the /etc/cpanel/ea4/ea4-metainfo.json file.

object

Request samples 

whmapi1 --output=jsonpretty \
  ea4_metainfo

Response samples

Content type
application/json
{
  • "data": {
    • "additional_packages": [
      • "ea-nginx",
      • "ea-example"
      ],
    • "default_php_handler": "cgi",
    • "default_php_package": "ea-php72",
    • "type": "object"
    },
  • "metadata": {
    • "command": "ea4_metainfo",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return EasyApache 4 recommendations

This function returns any recommendations attached to your installed EasyApache 4 packages. For more information about the recommendation system, read our EasyApache 4 Recommendations documentation.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ea4_recommendations

Response samples

Content type
application/json
{
  • "data": {
    • "ea-php55-php": [
      • {
        • "desc": "PHP DSO runs as the user by default. In a shared hosting environment, this is a security issue.",
        • "level": "danger",
        • "name": "PHP DSO",
        • "on": "add",
        • "options": [
          • {
            • "items": [
              • "ruid2",
              • "mpm-itk"
              ],
            • "level": "success",
            • "recommended": true,
            • "text": "We strongly recommend that you install one of the following packages unless this is a single-user system:"
            },
          • {
            • "level": "warning",
            • "recommended": false,
            • "text": "If you use suPHP, you will add some security, but may experience performance issues on your server."
            }
          ],
        • "url": "https://www.example.com"
        }
      ]
    },
  • "metadata": {
    • "command": "ea4_recommendations",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Create EasyApache 4 profile

This function creates an EasyApache 4 profile. This function only writes files to the /etc/cpanel/ea4/profiles/custom/ directory.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
desc
string
Default: ""
Example: desc=This is my new profile.

The description of the profile.

filename
required
string
Example: filename=new_profile.json

The profile's file name.

name
required
string
Example: name=New Profile

The profile's display name.

overwrite
integer
Default: 0
Possible Values: 0 1
Example: overwrite=1

Whether to overwrite the file, if it exists.

  • 1 — Overwrite the file.
  • 0 — Do not overwrite the file.
pkg
required
Array of strings
Example: pkg=ea-apache24&pkg=ea-apache24-foo

The packages that the profile contains.

tag
Array of strings
Default: ""
Example: tag=Apache 2.4&tag=Optimized for static content

Tags that are appropriate for the profile.

version
string
Default: "0"
Example: version=1.3

The profile's version number.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ea4_save_profile \
  filename='new_profile.json' \
  name='New Profile' \
  pkg='ea-apache24' pkg='ea-apache24-foo'

Response samples

Content type
application/json
{
  • "data": {
    • "already_exists": 1,
    • "path": "/etc/cpanel/ea4/profiles/custom/new_profile.json"
    },
  • "metadata": {
    • "command": "ea4_save_profile",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return any additional package prefixes, beyond `ea`.

This function returns any additional package prefixes set up in the /etc/cpanel/ea4/additional-pkg-prefixes/ file.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty ea4_get_additional_pkg_prefixes

Response samples

Content type
application/json
{
  • "data": {
    • "additional_pkg_prefixes": [
      • "altea"
      ]
    },
  • "metadata": {
    • "command": "ea4_get_additional_pkg_prefixes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return EasyApache 4 profiles

This function returns a list of all EasyApache 4 profiles and the packages that each profile provides.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  ea4_list_profiles

Response samples

Content type
application/json
{
  • "data": {
    • "cpanel": [
      • {
        • "active": 1,
        • "desc": "The currently installed packages on the server.",
        • "name": "No PHP",
        • "pkgs": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "tags": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "validation_data": {
          • "not_on_server": [
            • "ea-apache24",
            • "ea-php74"
            ]
          },
        • "version": "1.2"
        }
      ],
    • "custom": [
      • {
        • "desc": "The currently installed packages on the server.",
        • "name": "No PHP",
        • "path": "default.json",
        • "pkgs": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "tags": [
          • "Apache 2.4",
          • "PHP 7.4"
          ],
        • "validation_data": {
          • "not_on_server": [
            • "ea-apache24",
            • "ea-php74"
            ]
          },
        • "version": "1.2"
        }
      ],
    • "property1": [
      • {
        • "desc": "The currently installed packages on the server.",
        • "name": "No PHP",
        • "path": "default.json",
        • "pkgs": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "tags": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "validation_data": {
          • "not_on_server": [
            • "ea-apache24",
            • "ea-php74"
            ]
          },
        • "version": "1.2"
        }
      ],
    • "property2": [
      • {
        • "desc": "The currently installed packages on the server.",
        • "name": "No PHP",
        • "path": "default.json",
        • "pkgs": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "tags": [
          • "ea-apache24",
          • "ea-php74"
          ],
        • "validation_data": {
          • "not_on_server": [
            • "ea-apache24",
            • "ea-php74"
            ]
          },
        • "version": "1.2"
        }
      ]
    },
  • "metadata": {
    • "command": "ea4_list_profiles",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

PHP

The PHP module for WHM API 1.

Return PHP preconfigured domains

This function lists domains that obtain their PHP version from a specified PHP configuration.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
domain
required
string
Examples:
  • domain=domain=example.com domain=example2.com domain=example3.com - Pass multiple domains.
  • domain=example.com - Pass a single domain.

A domain on the system.

Note:

  • You must pass either the system_default or domain parameters, or both.
  • You can pass this parameter multiple times.
  • You cannot pass the name of a parked domain.
system_default
required
integer
Possible Values: 1 0
Example: system_default=1

Whether to return domains that inherit the system's default PHP version.

  • 1 — Return domains that inherit the system's default PHP version.
  • 0 — Do not return domains that inherit the system's default PHP version.

Note:

  • You must pass either the system_default or domain parameters, or both.
  • If you pass this parameter with a false value and do not also pass the domain parameter, the function returns an error.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_impacted_domains \
  system_default='1' \
  domain='example.com'

Response samples

Content type
application/json
{
  • "data": {
    • "domains": [
      • "example.com",
      • "subdomain.example.com",
      • "example2.com"
      ]
    },
  • "metadata": {
    • "command": "php_get_impacted_domains",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP handlers

This function returns the PHP handlers on the system.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
version
string
Example: version=ea-php72

An installed PHP version.

  • ea-php54
  • ea-php55
  • ea-php56
  • ea-php70
  • ea-php71
  • ea-php72
  • inherit
  • Any custom PHP package name.

Important:

We deprecated PHP 5.6 and PHP 7.0 and will remove them in a future version. For more information, read our cPanel Deprecation Plan documentation.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_handlers

Response samples

Content type
application/json
{
  • "data": {
    • "version_handlers": [
      • {
        • "available_handlers": [
          • "cgi",
          • "none",
          • "suphp"
          ],
        • "current_handler": "suphp",
        • "version": "ea-php72"
        }
      ]
    },
  • "metadata": {
    • "command": "php_get_handlers",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP version of all virtual hosts

This function returns the PHP version of every virtual host that a reseller controls.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_vhost_versions

Response samples

Content type
application/json
{
  • "data": {
    • "versions": [
      • {
        • "account": "rm3",
        • "account_owner": "root",
        • "documentroot": "/home/example/public_html",
        • "homedir": "/home/rm3",
        • "is_suspended": 0,
        • "main_domain": 1,
        • "php_fpm": 1,
        • "php_fpm_pool_parms": {
          • "pm_max_children": 5,
          • "pm_max_requests": 20,
          • "pm_process_idle_timeout": 10
          },
        • "phpversion_source": [
          • {
            • "domain": "example.com",
            • "system_default": 1
            }
          ],
        • "version": "ea-php72",
        • "vhost": "otherchars.rm3.tld"
        }
      ]
    },
  • "metadata": {
    • "command": "php_get_vhost_versions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP version's php.ini file

This function returns the contents of a PHP version's php.ini file.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
version
required
string
Example: version=ea-php74

The name of an installed PHP version's package.

  • ea-php##, where ## represents the major and minor versions of PHP (for example, ea-php74 represents PHP 7.4).
  • inherit
  • Any custom PHP package name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_ini_get_content \
  version='ea-php74'

Response samples

Content type
application/json
{
  • "data": {
    • "content": "display_errors; Default Value: On; Development Value: On; Production Value: Off;"
    },
  • "metadata": {
    • "command": "php_ini_get_content",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Update PHP version's php.ini file

This function changes the contents of a PHP version's php.ini file.

Notes:

  • This document only applies to systems that run EasyApache 4.
  • Due to the limited field length of HTTP GET method calls, we strongly recommend that you use the HTTP POST method.

Important: When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
content
required
string
Example: content=[PHP] ; About php.ini ; php.ini is responsible for configuring many of the aspects of PHP's behavior. pcre.backtrack_limit=100000

The contents of the php.ini file that you wish to change.

version
required
string
Example: version=ea-php74

The version of PHP for which you wish to change the php.ini file.

  • ea-php72
  • ea-php73
  • ea-php74
  • Any custom PHP package name

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_ini_set_content \
  content=$'[PHP]
; About php.ini
; php.ini is responsible for configuring many of the aspects of PHP\'s behavior.
pcre.backtrack_limit=100000
' \
  version='ea-php74'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "php_ini_set_content",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Update PHP default save path

This function sets the location of PHP's default session save path.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
overwrite
integer
Default: 0
Possible Values: 0 1
Example: overwrite=0

Whether to overwrite the existing session save path in the php.ini file.

  • 1 — Overwrite the existing value in the php.ini file.
  • 0 — Do not overwrite the existing value in the php.ini file.
path
string
Default: "/var/cpanel/php/sessions"
Example: path=/var/cpanel/php/sessions

The directory in which to save session information.

Warning:

For security reasons, do not set this value to /tmp or another insecure location.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  php_set_session_save_path

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "php_set_session_save_path",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update default PHP version

The version of PHP that you wish to set as the system's default.

  • ea-php81
  • inherit
  • Any custom PHP package name.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
version
required
string
Example: version=ea-php81

The version of PHP that you wish to set as the system's default.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  php_set_system_default_version \
  version='ea-php74'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "php_set_system_default_version",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Update domain's PHP values

This function allows WHM's MultiPHP Manager interface (WHM >> Home >> Software >> MultiPHP Manager) to change the values of a domain.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth
query Parameters
php_fpm
integer
Default: 0
Possible Values: 1 0
Example: php_fpm=1

Whether PHP-FPM is enabled.

  • 1 — Enabled.
  • 0 — Disabled.
object <json>
Example: php_fpm_pool_parms={"pm_max_children":5,"pm_max_requests":20,"pm_process_idle_timeout":10}

A JSON-encoded string containing a hash of values.

version
required
string
Possible Values: "ea-php54" "ea-php55" "ea-php56" "ea-php70" "ea-php71" "ea-php72" "inherit"
Example: version=ea-php70

The virtual host's (vhost) PHP version.

Note:

This parameter also accepts any custom PHP package names.

vhost
required
string
Examples:
  • vhost=vhost-1=otherchars.rm3.tld vhost-2=morechars.rm3.tld vhost-3=lotschars.rm3.tld - Set multiple vhosts.
  • vhost=otherchars.rm3.tld - Set a single vhost.

The virtual host's name.

Note:

To set multiple vhosts, increment the parameter name. For example, vhost-1, vhost-2, and vhost-3.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  php_set_vhost_versions \
  version='ea-php70' \
  vhost='otherchars.rm3.tld'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "php_set_vhost_versions",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return installed PHP versions

This function returns the installed PHP versions on a server.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role , the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_installed_versions

Response samples

Content type
application/json
{
  • "data": {
    • "versions": [
      • "ea-php74"
      ]
    },
  • "metadata": {
    • "command": "php_get_installed_versions",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Return system default PHP version

This function returns the system default PHP version.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_system_default_version

Response samples

Content type
application/json
{
  • "data": {
    • "version": "ea-php56"
    },
  • "metadata": {
    • "command": "php_get_system_default_version",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Return virtual hosts per PHP version

This function lists the virtual hosts that use a specified version of PHP.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
version
required
string
Example: version=ea-php56

The name of an installed PHP package.

  • ea-php##, where ## represents the major and minor versions of PHP (for example, ea-php72 represents PHP 7.2).
  • inherit
  • Any custom PHP package name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_vhosts_by_version \
  version='ea-php56'

Response samples

Content type
application/json
{
  • "data": {
    • "vhosts": [
      • "example.com"
      ]
    },
  • "metadata": {
    • "command": "php_get_vhosts_by_version",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP version's directives

This function returns the directives in the selected PHP version's php.ini file. WHM's MultiPHP INI Editor interface (Home >> Software >> MultiPHP INI Editor) lists these directives in the Basic Mode section.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
version
required
string
Example: version=ea-php74

The name of an installed version of PHP.

  • ea-php72
  • ea-php73
  • ea-php74
  • Any custom PHP package name

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_ini_get_directives \
  version='ea-php74'

Response samples

Content type
application/json
{
  • "data": {
    • "directives": [
      • {
        • "default_value": "1",
        • "info": "This option enables the URL-aware fopen wrappers that enable accessing URL object like files. Default wrappers are provided for the access of remote files using the ftp or http protocol, some extensions like zlib may register additional wrappers.",
        • "key": "allow_url_fopen",
        • "php_ini_mode": "PHP_INI_SYSTEM",
        • "type": "boolean",
        • "value": "On"
        }
      ]
    },
  • "metadata": {
    • "command": "php_ini_get_directives",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

Update PHP version's handler

This function sets a PHP version's handler.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
handler
required
string
Possible Values: "cgi" "suphp" "dso" "none"
Example: handler=suphp

An installed PHP handler.

  • cgi
  • suphp
  • dso
  • none
version
required
string
Example: version=ea-php70

An installed PHP version.

  • ea-php54
  • ea-php55
  • ea-php56
  • ea-php70
  • ea-php71
  • ea-php72
  • inherit
  • Any custom PHP package name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  php_set_handler \
  version='ea-php70' \
  handler='suphp'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "php_set_handler",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update PHP version's directives

This function sets the value of a PHP version's directives.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role , the system disables this function.

Authorizations:
BasicAuth
query Parameters
directive
required
string
Examples:
  • directive=directive-1=allow_url_fopen:0&directive-2=max_input_vars=1000 - Set the values for multiple directives.
  • directive=allow_url_fopen:0 - Set the value for a single directive.

The name of a PHP directive and its value.

Note:

To change the directive's value for multiple PHP directives, duplicate or increment the parameter name. For example, to change three directives, use the directive parameter multiple times or use the directive-1, directive-2 , and directive-3 parameters.

version
required
string
Example: version=ea-php72

PHP version on the system.

Note

  • ea-php56
  • ea-php70
  • ea-php71
  • ea-php72
  • Any custom PHP package name.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_ini_set_directives \
  directive='allow_url_fopen:0' \
  version='ea-php72'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "php_ini_set_directives",
    • "reason": "Ok",
    • "result": 1,
    • "version": 1
    }
}

PHP-FPM

Web Server Configuration / PHP-FPM

Enable PHP-FPM on all domains

This function activates PHP-FPM for any non-PHP-FPM domains on a server.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  convert_all_domains_to_fpm

Response samples

Content type
application/json
{
  • "data": {
    • "build_id": 1493645268
    },
  • "metadata": {
    • "command": "convert_all_domains_to_fpm",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP-FPM conversion status

This function indicates whether the system's process to convert all of WHM's accounts to use PHP-FPM is in progress.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  is_conversion_in_progress

Response samples

Content type
application/json
{
  • "data": {
    • "inProgress": 1
    },
  • "metadata": {
    • "command": "is_conversion_in_progress",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update PHP-FPM directives and pool options

This function configures the PHP INI directives and pool options for a system's or domain's PHP-FPM configuration.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth
Request Body schema: application/json
required
required
Array of objects

An array of objects containing the PHP-FPM configuration values to validate or update.

domain
string
Default: ""

A blank value or domain name whose PHP-FPM configuration you wish to set.

validate_only
boolean
Default: false

Whether the function request is for validation or to update the settings.

  • true - Only validate the configuration.
  • false - Validate and update the configuration.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "config": [
    • {
      • "base_flag_name": "error_reporting",
      • "trinary_admin_value": 1,
      • "value": "E_ALL & ~E_NOTICE"
      },
    • {
      • "base_flag_name": "pm_max_children",
      • "trinary_admin_value": 0,
      • "value": "10"
      }
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "php_fpm_config_set",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP-FPM preconfigured status

This function determines whether your system runs with a preconfigured PHP-FPM configuration.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_old_fpm_flag

Response samples

Content type
application/json
{
  • "data": {
    • "old_fpm_flag": 2
    },
  • "metadata": {
    • "command": "php_get_old_fpm_flag",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable PHP-FPM preconfigured status

This function creates the /etc/cpanel/ea4/old_fpm_flag touch file.

Note:

If this touch file exists, the system will not display a message that indicates whether your system runs on an outdated PHP-FPM configuration. If you wish to see the message again, delete this touch file.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_set_old_fpm_flag

Response samples

Content type
application/json
{
  • "data": {
    • "success": 0
    },
  • "metadata": {
    • "command": "php_set_old_fpm_flag",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable PHP-FPM on new cPanel accounts and domains

This function determines whether to enable PHP-FPM on new accounts and domains on a server.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth
query Parameters
default_accounts_to_fpm
required
integer
Possible Values: 0 1
Example: default_accounts_to_fpm=1

Whether to enable PHP-FPM on all new accounts and domains on a server.

  • 1 — Enable PHP-FPM.
  • 0 — Disable PHP-FPM.

Responses

Response Schema: application/json
data
any
object

Request samples 

whmapi1 --output=jsonpretty \
  php_set_default_accounts_to_fpm \
  default_accounts_to_fpm='1'

Response samples

Content type
application/json
{
  • "data": null,
  • "metadata": {
    • "command": "php_set_default_accounts_to_fpm",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return workload data for PHP-FPM on all domains

This function provides information that will help you to determine whether your server can handle the workload if you enable PHP-FPM for all domains.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  get_fpm_count_and_utilization

Response samples

Content type
application/json
{
  • "data": {
    • "domains_to_be_enabled": 2,
    • "domains_using_fpm": 20,
    • "memory_needed": 90000,
    • "number_of_new_fpm_accounts_we_can_handle": 8,
    • "show_warning": 0,
    • "total_domains": 22
    },
  • "metadata": {
    • "command": "get_fpm_count_and_utilization",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP-FPM directives and pool options

This function retrieves the PHP INI directives and pool options for a system's or domain's PHP-FPM configuration.

Important:

When you disable the WebServer role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth
Request Body schema: application/json
required
domain
string
Default: ""

A blank value or domain name whose PHP-FPM configuration you wish to retrieve.

  • A valid domain that resides on the local server — Retrieves the domain's PHP-FPM configuration information.
  • A blank value — Retrieves the system's PHP-FPM information.

Responses

Response Schema: application/json
object
object

Request samples

Content type
application/json
{
  • "domain": "example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    • "config": [
      • {
        • "base_flag_name": "short_open_tag",
        • "trinary_admin_value": 1,
        • "value": "on"
        },
      • {
        • "base_flag_name": "log_errors",
        • "trinary_admin_value": 1,
        • "value": "on"
        },
      • {
        • "base_flag_name": "pm_process_idle_timeout",
        • "trinary_admin_value": 0,
        • "value": "10"
        },
      • {
        • "base_flag_name": "error_reporting",
        • "trinary_admin_value": 2,
        • "value": "E_ALL & ~E_NOTICE"
        },
      • {
        • "base_flag_name": "disable_functions",
        • "trinary_admin_value": 1,
        • "value": "exec,passthru,shell_exec,system"
        },
      • {
        • "base_flag_name": "error_log",
        • "trinary_admin_value": 1,
        • "value": "[% homedir %]/logs/[% scrubbed_domain %].php.error.log"
        },
      • {
        • "base_flag_name": "pm_max_children",
        • "trinary_admin_value": 0,
        • "value": "5"
        },
      • {
        • "base_flag_name": "pm_max_requests",
        • "trinary_admin_value": 0,
        • "value": "20"
        },
      • {
        • "base_flag_name": "allow_url_fopen",
        • "trinary_admin_value": 1,
        • "value": "on"
        },
      • {
        • "base_flag_name": "doc_root",
        • "trinary_admin_value": 1,
        • "value": "[% documentroot %]"
        }
      ]
    },
  • "metadata": {
    • "command": "php_fpm_config_get",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return PHP-FPM status on new accounts

This function determines whether the system enables PHP-FPM for new domains and accounts.

Important:

When you disable the Web Server role, the system disables this function.

Warning:

We strongly recommend that you only activate Apache PHP-FPM if your server has at least 2 GB of RAM available, or at least 30 MB of RAM per domain. If you enable PHP-FPM on a server with less than the required RAM, your server may experience severe performance issues.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  php_get_default_accounts_to_fpm

Response samples

Content type
application/json
{
  • "data": {
    • "default_accounts_to_fpm": 0
    },
  • "metadata": {
    • "command": "php_get_default_accounts_to_fpm",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Rule Settings

Web Server Security (ModSecurity) / Rule Settings

Add staged ModSecurity rule

This function adds a new rule to a ModSecurity™ configuration staging file. For example, if you choose to add a rule for the example.conf file, the function stages the rule in the example.conf. STAGE file.

Important:

This function does not actually deploy the rule. To deploy the rule, use the WHM API 1 Functions - modsec_deploy_all_rule_changes function.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec2.user.conf

The ModSecurity configuration file.

rule
required
string
Example: rule=SecAction "phase:1,id:168,nolog,pass,setvar:tx.REMOTE_ADDR=/%{REMOTE_ADDR}/"

The rule's text.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_add_rule \
  config='modsec2.user.conf' \
  rule='SecAction "phase:1,id:168,nolog,pass,setvar:tx.REMOTE_ADDR=/%{REMOTE_ADDR}/"'

Response samples

Content type
application/json
{
  • "data": {
    • "rule": {
      • "config": null,
      • "config_active": null,
      • "disabled": 0,
      • "duplicate": 0,
      • "id": 168,
      • "meta_msg": "Example rule message",
      • "rule": "SecAction \\\"phase:1,id:168,nolog,pass,setvar:tx.REMOTE_ADDR=/%{REMOTE_ADDR}/\\\"",
      • "staged": null,
      • "vendor_active": null,
      • "vendor_id": null
      }
    },
  • "metadata": {
    • "command": "modsec_add_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Validate ModSecurity rule

This function checks a ModSecurity™ rule's validity.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
rule
required
string
Example: rule=SecAction "pass,id:1234567"

The ModSecurity rule to check.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_check_rule \
  rule='SecAction "pass,id:1234567"'

Response samples

Content type
application/json
{
  • "data": {
    • "problem": "The rule is invalid. Apache returned the following error: AH00526: Syntax error on line 1 of /var/tmp/15500._USR_LOCAL_CPANEL_WHOSTMGR_BIN_XML_API__.gl2t8wZ1.tmp/validate.conf:\nInvalid command ''OWASP'', perhaps misspelled or defined by a module not included in the server configuration\n'",
    • "valid": 0
    },
  • "metadata": {
    • "command": "modsec_check_rule",
    • "reason": "OK Invalid Rule",
    • "result": 1,
    • "version": 1
    }
}

Save ModSecurity rule copy

This function copies a ModSecurity™ rule with a new rule ID.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec2.user.conf

The rule's ModSecurity configuration file.

id
required
integer >= 1
Example: id=123456789

The existing rule's ID.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_clone_rule \
  config='modsec2.user.conf' \
  id='123456789'

Response samples

Content type
application/json
{
  • "data": {
    • "rule": {
      • "config": "modsec2.user.conf",
      • "config_active": 1,
      • "disabled": 0,
      • "id": 123456789,
      • "meta_msg": "Rejected request",
      • "rule": "SecRule REQUEST_URI \"/rejected.php\" \"deny,auditlog,msg:'Rejected request',id:'1'\"",
      • "staged": 1,
      • "vendor_active": 0,
      • "vendor_id": "YourVendor"
      }
    },
  • "metadata": {
    • "command": "modsec_clone_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable all staged ModSecurity rule changes

This function deploys the staged changes for all of the ModSecurity™ configuration files into the live configuration files. After the function deploys the configuration files, it restarts Apache. If the new configuration is invalid, the system restores the original configuration and preserves the staged changes.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_deploy_all_rule_changes

Response samples

Content type
application/json
{
  • "data": {
    • "failed": [
      • "modsec_vendor_configs/MyVendor/one.conf"
      ],
    • "outcomes": [
      • {
        • "config": "modsec_vendor_configs/MyVendor/one.conf",
        • "exception": "The system could not deploy changes for modsec_vendor_configs/MyVendor/one.conf: The system could not validate the new Apache configuration, because httpd exited with a nonzero value. Apache produced the following error: httpd: Syntax error on line 37 of /usr/local/apache/conf/httpd.conf: Syntax error on line 26 of /usr/local/apache/conf/modsec2.conf: Syntax error on line 27 of /usr/local/apache/conf/modsec2.cpanel.conf: Could not open configuration file /usr/local/apache/conf/modsec_vendor_configs/MyVendor/one.conf: No such file or directory\n\n\n",
        • "ok": 0
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_deploy_all_rule_changes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable staged ModSecurity rule changes

This function deploys staged changes to the ModSecurity™ configuration file and restarts Apache.

Note:

If the new configuration is invalid, the system will restore the original configuration and maintain the staged changes.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file's path and name, relative to the /usr/local/apache/conf/ directory.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_deploy_rule_changes \
  config='modsec_vendor_configs/example.conf'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_deploy_rule_changes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable ModSecurity rule

This function disables a ModSecurity™ rule.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file, relative to the /etc/apache2/conf.d directory.

id
required
string
Example: id=1234567890

The ModSecurity rule's ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_disable_rule \
  config='modsec_vendor_configs/example.conf' \
  id='1234567890'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "modsec_disable_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove all staged ModSecurity rule changes

This function discards the staged ModSecurity™ rule changes, if present, for all of the configuration files.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_discard_all_rule_changes

Response samples

Content type
application/json
{
  • "data": {
    • "failed": [
      • "modsec_vendor_configs/MyVendor/one.conf"
      ],
    • "outcomes": [
      • {
        • "config": "modsec_vendor_configs/MyVendor/one.conf",
        • "exception": "The system could not remove the file /usr/local/apache/conf/modsec_vendor_configs/MyVendor/one.conf.STAGE: Invalid argument\n",
        • "ok": 0
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_discard_all_rule_changes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove staged ModSecurity rule changes

This function discards staged rule changes for a ModSecurity™ configuration file. Staged rule changes reside in a .STAGE file (for example, the staged changes for the example.conf file exist in the example.conf.STAGE file). This function deletes the .STAGE file that corresponds to the configuration file that you specify.

Note:

To stage rule changes, call WHM API 1's modsec_add_rule function.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec2.example.conf

The ModSecurity configuration file in the /usr/local/cpanel/apache/conf/ directory.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_discard_rule_changes \
  config='modsec2.example.conf'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_discard_rule_changes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update staged ModSecurity rule

This function stages edits to a ModSecurity™ rule. The system does not save changes directly to the configuration file. Instead, it stages the changes to the configuration file's .STAGE file (for example, for the example.conf file, the system stages changes in the example.conf.STAGE file).

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file, relative to the /usr/local/apache/conf/ directory.

id
required
integer
Example: id=1234567

The ModSecurity rule's ID.

rule
required
string
Example: rule=SecAction "pass,id:1234567"

The new ModSecurity rule.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_edit_rule \
  config='modsec_vendor_configs/example.conf' \
  id='1234567' \
  rule='SecAction "pass,id:1234567"'

Response samples

Content type
application/json
{
  • "data": {
    • "rule": {
      • "disabled": 0,
      • "id": 1234567,
      • "meta_msg": "",
      • "rule": "SecAction \"pass,id:1234567\""
      }
    },
  • "metadata": {
    • "command": "modsec_edit_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity rules

This function retrieves the ModSecurity™ rules from one or more ModSecurity configuration files.

Important:

  • When you disable the Web Server role, the system disables this function.
  • You must include either the vendor_id or the config parameters.
Authorizations:
BasicAuth
query Parameters
config
string
Examples:
  • config=modsec_vendor_configs/SomeVendor/config.conf,modsec_vendor_configs/AnotherVendor/config.conf - Call multiple configuration files.
  • config=modsec_vendor_configs/SomeVendor/config.conf - Call a single configuration file.

The file path to the configuration file, relative to the /usr/local/apache/conf directory.

Note:

You can use a comma-delimited list for multiple configuration files.

exclude_bare_comments
integer
Default: 1
Possible Values: 1 0
Example: exclude_bare_comments=1

Whether to exclude comments that are not associated with any directives.

  • 1 — Exclude.
  • 0 — Do not exclude.
exclude_other_directives
integer
Default: 1
Possible Values: 1 0
Example: exclude_other_directives=1

Whether the function only returns the SecRule and SecAction directives from the configuration file, and comments that are not associated with a rule.

  • 1 — Only return the SecRule and SecAction directives and comments not associated with a rule.
  • 0 — Return all directives and comments.
vendor_id
string
Examples:
  • vendor_id=vendor=SomeVendor,AnotherVendor - Call multiple vendors.
  • vendor_id=SomeVendor - Call a single vendor.

The vendor's unique short name.

Note:

You can use a comma-delimited list for multiple vendors.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_rules

Response samples

Content type
application/json
{
  • "data": {
    • "chunks": [
      • {
        • "config": "modsec_vendor_configs/SomeVendor/config.conf",
        • "config_active": 0,
        • "disabled": 0,
        • "id": 662452,
        • "meta_msg": "Denied dangerous config traffic",
        • "rule": "SecRule REQUEST_FILENAME \"config\" \"deny,id:662452,msg:'Denied dangerous config traffic',severity:1,auditlog\"",
        • "staged": 0,
        • "vendor_active": 0,
        • "vendor_id": "SomeVendor"
        }
      ],
    • "staged_changes": 0
    },
  • "metadata": {
    • "command": "modsec_get_rules",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove ModSecurity rule

This function removes a rule from a ModSecurity™ configuration file.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file's path and filename, relative to the /usr/local/apache/conf/ directory.

id
required
integer >= 1
Example: id=1234567890

The rule's ID.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_remove_rule \
  config='modsec_vendor_configs/example.conf' \
  id='1234567890'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_remove_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Export ModSecurity rule error report

This function submits ModSecurity™ rule error reports to a remote receiver. The third party rule vendors use these error reports to identify problems with their rule sets.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
email
required
string <email>

The contact email address to send with the error report. This allows the rule's vendor to reply to the user directly.

message
required
string
Example: message=Hi. We're having some trouble with this rule. It seems to be blocking all requests.

A short message that explains the reason for the report.

row_ids
required
integer
Examples:
  • row_ids=794828, 794829, 794820 - Report multiple row IDs.
  • row_ids=794828 - Report a single row ID.

The MySQL® row IDs from the hits table in the modsec database for the audit log event to report.

Note:

If you specify more than one row ID:

  • You must comma-separate the rule IDs.
  • The rule IDs must all correspond to the same ModSecurity rule.
send
required
integer
Possible Values: 1 0
Example: send=1

Whether the function sends the report to the rule's vendor.

  • 1 — Send the report.
  • 0 — Do not send the report.
type
required
string
Example: type=false positive

The report's type.

Note:

This value does not use a specified format. Treat the value as freeform text.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_report_rule \
  row_ids='794828' \
  message=$'Hi. We\'re having some trouble with this rule. It seems to be
blocking all requests.' \
  email='[email protected]' \
  type='false positive' \
  send='1'

Response samples

Content type
application/json
{
  • "data": {
    • "report": [
      • {
        • "email": "[email protected]",
        • "hits": [
          • {
            • "action_desc": "Access denied with code 406 (phase 2).",
            • "handler": null,
            • "host": "example.com",
            • "http_method": "GET",
            • "http_status": 406,
            • "http_version": "HTTP/1.1",
            • "id": 794828,
            • "ip": "10.215.215.236",
            • "justification": "Unconditional match in SecAction.",
            • "meta_file": "/usr/local/apache/conf/modsec_vendor_configs/MyVendor/one.conf",
            • "meta_id": 12345694,
            • "meta_line": 1,
            • "meta_logdata": null,
            • "meta_msg": "Method is not allowed by policy",
            • "meta_offset": 0,
            • "meta_rev": 1,
            • "meta_severity": "CRITICAL",
            • "meta_uri": null,
            • "path": "/something",
            • "timestamp": "2019-10-13T07:58:04",
            • "timezone": "-300"
            }
          ],
        • "message": "Hi. We're having some trouble with this rule. It seems to be blocking all requests.",
        • "rule_text": "SecAction \"deny,auditlog,id:'12345694'\"\n",
        • "type": "false positive"
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_report_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable ModSecurity rule

This function enables a ModSecurity™ rule.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file.

id
required
string
Example: id=1234567890

The ModSecurity rule's ID.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_undisable_rule \
  config='modsec_vendor_configs/example.conf' \
  id='1234567890'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "modsec_undisable_rule",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Rule Vendor Settings

Web Server Security (ModSecurity) / Rule Vendor Settings

Add ModSecurity vendor rules

This function adds a new ModSecurity™ vendor rule set to the server.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
enabled
integer
Default: 1
Possible Values: 1 0
Example: enabled=1

Whether to enable the vendor.

  • 1 — Enabled.
  • 0 — Disabled.
url
required
string <url>
Example: url=https://example.com/update/meta_MyVendor.yaml

The YAML metadata that describes the vendor and how to obtain its rules.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_add_vendor \
  url='https://example.com/update/meta_MyVendor.yaml'

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "modsec_add_vendor",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable ModSecurity vendor configuration files

This function disables a ModSecurity™ vendor's configuration files.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=SomeVendor

The vendor's unique short name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_disable_vendor_configs \
  vendor_id='SomeVendor'

Response samples

Content type
application/json
{
  • "data": {
    • "outcomes": [
      • {
        • "active": 1,
        • "config": "modsec_vendor_configs/SomeVendor/example.conf",
        • "exception": "This is an error message.",
        • "ok": 0
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_disable_vendor_configs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable ModSecurity vendor rules

This function disables a ModSecurity™ vendor rule set.

Note:

This function will not disable vendor configuration files that you have individually enabled.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=SomeVendor

The vendor's unique short name.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_disable_vendor \
  vendor_id='SomeVendor'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_disable_vendor",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Disable ModSecurity vendor updates

This function disables automatic updates for a ModSecurity™ vendor.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=example

The vendor's unique short name.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_disable_vendor_updates \
  vendor_id='example'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_disable_vendor_updates",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable ModSecurity vendor rules

This function enables a ModSecurity™ vendor rule set.

Note:

This function will not enable vendor configuration files that you individually disable.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=SomeVendor

The vendor's unique short name.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_enable_vendor \
  vendor_id='SomeVendor'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_enable_vendor",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable ModSecurity vendor configuration files

This function enables a ModSecurity™ vendor's configuration files.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=SomeVendor

The vendor's unique short name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_enable_vendor_configs \
  vendor_id='SomeVendor'

Response samples

Content type
application/json
{
  • "data": {
    • "outcomes": [
      • {
        • "active": 1,
        • "config": "modsec_vendor_configs/SomeVendor/example.conf",
        • "exception": "This is an error message.",
        • "ok": 1
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_enable_vendor_configs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable ModSecurity vendor updates

This function enables automatic updates for a ModSecurity™ vendor.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=example

The vendor's unique short name.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_enable_vendor_updates \
  vendor_id='example'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_enable_vendor_updates",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity vendors

The function returns a list of configured ModSecurity™ vendors.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_vendors

Response samples

Content type
application/json
{
  • "data": {
    • "vendors": [
      • {
        • "archive_url": "http://www.example.com/SAMPLE_1415038544.zip",
        • "configs": [
          • {
            • "active": 1,
            • "config": "modsec_vendor_configs/SAMPLE/modsecurity_crs_10_setup.conf",
            • "vendor_id": "SAMPLE"
            },
          • {
            • "active": 0,
            • "config": "modsec_vendor_configs/SAMPLE/optional_rules/modsecurity_crs_16_session_hijacking.conf",
            • "vendor_id": "SAMPLE"
            },
          • {
            • "active": 1,
            • "config": "modsec_vendor_configs/SAMPLE/optional_rules/modsecurity_crs_46_av_scanning.conf",
            • "vendor_id": "SAMPLE"
            }
          ],
        • "cpanel_provided": 0,
        • "description": "A SAMPLE-curated ModSecurity rule set.",
        • "dist_md5": "ffbaa3a7ead8dfaf0b661a729ce6ad3b",
        • "dist_sha512": "b55c09bb1835ed4209f0f3ea4a70d099665363f23d3819c0369be429438d675ba2c749dcefdb85cee682ee0bf485558e67d0b0965fe4799865529d943e8e14cb",
        • "enabled": 1,
        • "in_use": 32,
        • "inst_dist": "SAMPLE_1415038544",
        • "installed": 1,
        • "installed_from": "http://www.example.com/meta_SAMPLE.yaml",
        • "name": "SAMPLE ModSecurity Core Rule Set",
        • "path": "/usr/local/apache/conf/modsec_vendor_configs/SAMPLE",
        • "report_url": "https://www.example.com/report",
        • "supported_versions": [
          • "2.9.1",
          • "2.9.2",
          • "2.9.3"
          ],
        • "update": 1,
        • "vendor_id": "SAMPLE",
        • "vendor_url": "https://www.example.com/index.php/Category:SAMPLE_ModSecurity_Core_Rule_Set_Project"
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_get_vendors",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity vendor rule metadata

This function returns the metadata for a ModSecurity™ vendor rule set.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
url
required
string <url>
Example: url=https://www.example.com/vendor1rules/meta_vendor1.yaml

The YAML metadata's URL, which describes the vendor and how to obtain its rules.

Note:

  • The file uses YAML format.
  • The filename must use the meta_ prefix.
  • The filename must match the vendor_id value for your vendor.
  • The filename must end with the .yaml extension.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_preview_vendor \
  url='https://www.example.com/vendor1rules/meta_vendor1.yaml'

Response samples

Content type
application/json
{}

Remove ModSecurity vendor

This function removes a ModSecurity™ vendor. When you call this function, the system removes the vendor's includes, disablement directives, configuration files, and metadata file.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
vendor_id
required
string
Example: vendor_id=SomeVendor

The ModSecurity vendor's unique short name.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_remove_vendor \
  vendor_id='SomeVendor'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "modsec_remove_vendor",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update ModSecurity vendor ruleset

This function updates a vendor with the current version of the rule set.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
url
required
string <url>
Example: url=http://example.com/update/meta_MyVendor.yaml

The vendor metadata file's URL.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_update_vendor \
  url='http://example.com/update/meta_MyVendor.yaml'

Response samples

Content type
application/json
{
  • "data": {
    • "diagnostics": {
      • "added_configs": [
        • "modsec_vendor_configs/MyVendor/three.conf"
        ],
      • "deleted_configs": [
        • "modsec_vendor_configs/MyVendor/one.conf"
        ],
      • "new_configs": [
        • {
          • "active": 0,
          • "config": "modsec_vendor_configs/MyVendor/two.conf",
          • "vendor_id": "MyVendor"
          }
        ],
      • "prev_configs": [
        • {
          • "config": "modsec_vendor_configs/MyVendor/two.conf"
          }
        ]
      },
    • "vendor": {}
    },
  • "metadata": {
    • "command": "modsec_update_vendor",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Server Settings

Web Server Security (ModSecurity) / Server Settings

Add ModSecurity configuration file text

This function adds text to a ModSecurity™ configuration file.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity™ configuration filename and file path, relative to the /etc/apache2/conf/ directory.

deploy
integer
Default: 0
Possible Values: 1 0
Example: deploy=1

Whether to deploy the new text to the system.

  • 1 — Deploy.
  • 0 — Do not deploy.
final
integer
Default: 0
Possible Values: 1 0
Example: final=1

Whether to add the text as the final upload to the configuration file.

  • 1 — Final upload.
  • 0 — Not the final upload.

Note:

  • You must use this parameter if you wish to add the text as the final change to the configuration file.
  • You must use the init parameter with this parameter if you wish to only make one change to the configuration file.
init
integer
Default: 0
Possible Values: 1 0
Example: init=1

Whether to add the text as the initial upload to the configuration file.

  • 1 — Initial upload.
  • 0 — Not the initial upload.

Note:

  • You must use this parameter if you wish to add the text as the initial change to the configuration file.
  • You must use the final parameter with this parameter if you wish to only make one change to the configuration file.
text
string
Default: ""
Example: text=newtext

The text to add to the configuration file.

Responses

Response Schema: application/json
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_assemble_config_text \
  config='modsec_vendor_configs/example.conf'

Response samples

Content type
application/json
{
  • "metadata": {
    • "command": "modsec_assemble_config_text",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Run ModSecurity batch settings

This function adds, updates, and removes global ModSecurity™ configuration directives. The function modifies these directives in the /usr/local/apache/conf/modsec2.cpanel.conf file.

Important:

When you disable the Web Server role, the system disables this function.

This function only supports the following ModSecurity™ configuration directives:

setting_idDocumentation
0SecAuditEngine
1SecConnEngine
2SecRuleEngine
3SecDisableBackendCompression
4SecGeoLookupDb
5SecGsbLookupDb
6SecGuardianLog
7SecHttpBlKey
8SecPcreMatchLimit
9SecPcreMatchLimitRecursion
Authorizations:
BasicAuth
query Parameters
remove
integer
Default: 0
Possible Values: 1 0
Examples:
  • remove=remove1=0 remove2=1 remove3=0 - Remove some settings when updating or setting multiple configuration settings. This example removes the second setting indicated in `setting_id2` and updates the other two settings.
  • remove=1 - Remove a single configuration setting requested in the `setting_id`

Whether to add or remove the configuration setting in the /usr/local/apache/conf/modsec2.cpanel.conf file.

  • 1 — Remove the configuration setting.

  • 0 — Add or update the configuration setting.

  • To remove multiple settings, increment the parameter name. For example, remove1, remove2, and remove3.

setting_id
required
integer [ 0 .. 9 ]
Examples:
  • setting_id=setting_id1=1 setting_id2=2 setting_id3=3 - Set or update multiple configuration settings, in this case: SecConnEngine, SecRuleEngine, and SecDisableBackendCompression.
  • setting_id=1 - Set or update a single configuration setting, in this case for SecConnEngine.

The configuration setting's ID.

Note:

To configure multiple IDs, increment the parameter name. For example, setting_id1, setting_id2, and setting_id3.

required
string or string or string or string or integer
Examples:
  • state=state1=On state2=On state3=Off - Set the state of multiple configuration settings.
  • state=On - Set the state of a single configuration setting.

The configuration setting's current state.

  • On
  • Off

Some settings accept additional values for this parameter. See the references above for more inforamation.

Note:

  • To configure multiple settings, increment the parameter name. For example, state1, state2, and state3.
  • state is ignored if remove is set to 1 for the setting.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_batch_settings \
  setting_id='1' \
  state='On'

Response samples

Content type
application/json
{
  • "data": {},
  • "metadata": {
    • "command": "modsec_batch_settings",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Enable staged ModSecurity configuration files

This function deploys the staged changes to your modsec2.cpanel.conf file and attempts to restart Apache. If the new settings fail validation, the system restores the /etc/apache2/conf.d/modsec/modsec2.cpanel.conf file.

Note:

Call the WHM API 1 modsec_set_setting function to prepare your changes for the modsec2.cpanel.conf file.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_deploy_settings_changes

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_deploy_settings_changes",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity configuration file

This function retrieves a ModSecurity™ configuration file's contents.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec2.example.conf

The ModSecurity configuration file's name.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_config_text \
  config='modsec2.example.conf'

Response samples

Content type
application/json
{
  • "data": {
    • "text": "SecRule REQUEST_URI \"example\" \"deny:id:123456789\" SecAction \"pass:auditlog:id:444444444\""
    },
  • "metadata": {
    • "command": "modsec_get_config_text",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return all ModSecurity configuration files

This function lists ModSecurity™ configuration files. The system stores the configuration files in the /usr/local/apache/conf/modsec_vendor_configs directory.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_configs

Response samples

Content type
application/json
{
  • "data": {
    • "configs": [
      • {
        • "active": 1,
        • "config": "modsec_vendor_configs/MyVendor/one.conf",
        • "vendor_id": "MyVendor"
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_get_configs",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return staged ModSecurity configuration files

This function lists the ModSecurity™ configuration files that have staged changes.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_configs_with_changes_pending

Response samples

Content type
application/json
{
  • "data": {
    • "configs": [
      • "modsec2.user.conf",
      • "modsec2.user1.conf",
      • "modsec2.user2.conf"
      ]
    },
  • "metadata": {
    • "command": "modsec_get_configs_with_changes_pending",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity logs

This function retrieves ModSecurity™ log entries from the modsec MySQL® database.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
Array of objects

An array of objects that contains information about the log entry.

object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_log

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "action_desc": "Access denied with code 406 (phase 1).",
      • "file_exists": 1,
      • "handler": null,
      • "host": "server.example.com",
      • "http_method": "GET",
      • "http_status": 406,
      • "http_version": "HTTP/1.1",
      • "id": 28,
      • "ip": "10.1.14.77",
      • "justification": "Match of \"within %{tx.allowed_methods}\" against \"REQUEST_METHOD\" required.",
      • "meta_file": "/usr/local/apache/conf/modsec_vendor_configs/OWASP/base_rules/modsecurity_crs_30_http_policy.conf",
      • "meta_id": 960032,
      • "meta_line": 31,
      • "meta_logdata": "GET",
      • "meta_msg": "Method is not allowed by policy",
      • "meta_offset": 0,
      • "meta_rev": 2,
      • "meta_severity": "CRITICAL",
      • "meta_uri": null,
      • "path": "/favicon.ico",
      • "reportable": 1,
      • "timestamp": "2019-10-13T07:58:04",
      • "timezone": -300
      }
    ],
  • "metadata": {
    • "command": "modsec_get_log",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity configuration

This function retrieves the server's ModSecurity™ configuration settings. The system stores these settings in the /usr/local/apache/conf/modsec2.conf file.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_get_settings

Response samples

Content type
application/json
{
  • "data": {
    • "settings": [
      • {
        • "default": "Off",
        • "description": "This setting controls the behavior of the audit engine.",
        • "directive": "SecAuditEngine",
        • "engine": 1,
        • "missing": 1,
        • "name": "Audit Log Level",
        • "radio_options": [
          • {
            • "name": "Log all transactions.",
            • "option": "On"
            },
          • {
            • "name": "Do not log any transactions.",
            • "option": "Off"
            },
          • {
            • "name": "Only log noteworthy transactions.",
            • "option": "RelevantOnly"
            }
          ],
        • "setting_id": 0,
        • "state": "",
        • "type": "radio",
        • "url": "https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secauditengine"
        },
      • {
        • "description": "Specify an external program to pipe transaction log information to for additional analysis. The syntax is analogous to the .forward file, in which a pipe at the beginning of the field indicates piping to an external program.",
        • "directive": "SecGuardianLog",
        • "missing": 1,
        • "name": "Guardian Log",
        • "setting_id": 6,
        • "state": "",
        • "type": "text",
        • "url": "https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secguardianlog",
        • "validation": [
          • {
            • "arg": "[|]",
            • "name": "startsWith"
            },
          • "path"
          ]
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_get_settings",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Return ModSecurity module status

This function checks whether the ModSecurity™ module is installed.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_is_installed

Response samples

Content type
application/json
{
  • "data": {
    • "data": {
      • "installed": 1
      }
    },
  • "metadata": {
    • "command": "modsec_is_installed",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Add ModSecurity configuration file include

This function adds an include for a ModSecurity™ configuration file to the modsec2.cpanel.conf file. This makes the ModSecurity configuration file active.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file's path and filename, relative to the /usr/local/apache/conf/ diretory.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_make_config_active \
  config='modsec_vendor_configs/example.conf'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_make_config_active",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove ModSecurity configuration file include

This function removes an include for a ModSecurity™ configuration file from the modsec2.cpanel.conf file. This makes the ModSecurity configuration file inactive.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec_vendor_configs/example.conf

The ModSecurity configuration file's path and filename, relative to the /etc/apache2/conf.d/ directory.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_make_config_inactive \
  config='modsec_vendor_configs/example.conf'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_make_config_inactive",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update ModSecurity configuration file

This function sets the contents of a specified ModSecurity™ configuration file. The system stages any changes to the configuration file. To deploy the changes, call WHM API 1's modsec_deploy_rule_changes function.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
config
required
string
Example: config=modsec2.example.conf

The configuration file name.

text
required
string
Example: text=SecRule REQUEST_URI "example" "deny,id:123456789" SecAction "pass,auditlog,id"

The configuration text.

Responses

Response Schema: application/json
data
any
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_set_config_text \
  config='modsec2.example.conf' \
  text='SecRule REQUEST_URI "example" "deny,id:123456789" SecAction "pass,auditlog,id"'

Response samples

Content type
application/json
{
  • "data": null,
  • "metadata": {
    • "command": "modsec_set_config_text",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Remove ModSecurity configuration

This function removes a global ModSecurity™ configuration directive.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
setting_id
required
integer
Example: setting_id=3

The setting's ID. For a list of available settings and their IDs, call the modsec_get_settings function.

Responses

Response Schema: application/json
data
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_remove_setting \
  setting_id='3'

Response samples

Content type
application/json
{
  • "data": { },
  • "metadata": {
    • "command": "modsec_remove_setting",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}

Update ModSecurity configuration

This function sets a global ModSecurity™ configuration directive.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:
BasicAuth
query Parameters
setting_id
required
integer >= 0
Example: setting_id=8

The setting's ID.

Note:

The WHM API 1 modsec_get_settings function returns this value.

state
required
string
Example: state=2000

The setting's new state. The function uses this as a valid argument for the directive.

Note:

For more information, read SpiderLabs' ModSecurity documentation.

Responses

Response Schema: application/json
object
object

Request samples 

whmapi1 --output=jsonpretty \
  modsec_set_setting \
  setting_id='8' \
  state='2000'

Response samples

Content type
application/json
{
  • "data": {
    • "default": "1500",
    • "description": "This setting allows you to define the match limit of the PCRE library.",
    • "directive": "SecPcreMatchLimit",
    • "name": "PCRE library match limit",
    • "radio_options": [
      • {
        • "name": "Log all transactions.",
        • "option": "On"
        }
      ],
    • "setting_id": 8,
    • "state": 2000,
    • "type": "text",
    • "url": "https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit",
    • "validation": [
      • {
        • "arg": "[Ee]xample",
        • "name": "startsWith"
        }
      ]
    },
  • "metadata": {
    • "command": "modsec_set_setting",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}