WHM API 0 Functions - listaccts

Guide to WHM API 0

Return Data

Accounts

accountsummary

DNS

IP Addresses

Mail

deliver_messages_mail_queue

exim_configuration_check

fetch_doc_key

purge_mail_queue

remove_in_progress_exim_config_edit

remove_messages_mail_queue

unfreeze_messages_mail_queue

validate_current_installed_exim_config

validate_exim_configuration_syntax

Packages

Resellers

setresellernameservers

setresellerpackagelimit

Server Administration

SSL

Updates

Description

This function queries the accounts on the server.

Examples

JSON API

https://hostname.example.com:2087/cpsess##########/json-api/listaccts?search=username&searchtype=user

XML API

https://hostname.example.com:2087/cpsess##########/xml-api/listaccts?search=username&searchtype=user

Command Line

whmapi0 listaccts search=username searchtype=user

Notes:

You must URI-encode values.
For more information and additional output options, read our Guide to WHM API 0 documentation or run the whmapi0 --help command.
If you run CloudLinux™, you must use the full path of the whmapi0 command:
```
/usr/local/cpanel/bin/whmapi0
```

Output (JSON)

{  
   "acct":[  
      {  
         "maxaddons":"unlimited",
         "ip":"10.0.0.1",
         "outgoing_mail_suspended": 0,
         "outgoing_mail_hold": 0,
         "min_defer_fail_to_trigger_protection":"5",
         "legacy_backup":0,
         "diskused":"14M",
         "maxftp":"unlimited",
         "startdate":"13 May 22 16:03",
         "max_defer_fail_percentage":"unlimited",
         "disklimit":"500M",
         "is_locked":0,
         "suspendtime":null,
         "email":"user@example.com",
         "domain":"example.com",
         "unix_startdate":1369256589,
         "user":"username",
         "plan":"extensions_username_username",
         "shell":"/bin/bash",
         "maxpop":"unlimited",
         "backup":0,
         "theme":"paper_lantern",
         "owner":"root",
         "max_email_per_hour":"unlimited",
         "ipv6":[  

         ],
         "suspendreason":"not suspended",
         "maxlst":"unlimited",
         "suspended":0,
         "maxsql":"unlimited",
         "maxparked":"unlimited",
         "partition":"home",
         "maxsub":"unlimited"
      }
   ],
   "statusmsg":"Ok",
   "status":1
}

Output (XML)

<listaccts>
    <acct>
        <backup>0</backup>
        <disklimit>500M</disklimit>
        <diskused>14M</diskused>
        <domain>example.com</domain>
        <email>user@example.com</email>
        <ip>10.0.0.1</ip>
        <ipv6></ipv6>
        <is_locked>0</is_locked>
        <legacy_backup>0</legacy_backup>
        <max_defer_fail_percentage>unlimited</max_defer_fail_percentage>
        <max_email_per_hour>unlimited</max_email_per_hour>
        <maxaddons>unlimited</maxaddons>
        <maxftp>unlimited</maxftp>
        <maxlst>unlimited</maxlst>
        <maxparked>unlimited</maxparked>
        <maxpop>unlimited</maxpop>
        <maxsql>unlimited</maxsql>
        <maxsub>unlimited</maxsub>
        <min_defer_fail_to_trigger_protection>5</min_defer_fail_to_trigger_protection>
        <outgoing_mail_suspended>0</outgoing_mail_suspended>
        <outgoing_mail_hold>0</outgoing_mail_hold>
        <owner>root</owner>
        <partition>home</partition>
        <plan>extensions_username_username</plan>
        <shell>/bin/bash</shell>
        <startdate>13 May 22 16:03</startdate>
        <suspended>0</suspended>
        <suspendreason>not suspended</suspendreason>
        <suspendtime/>
        <theme>paper_lantern</theme>
        <unix_startdate>1369256589</unix_startdate>
        <user>username</user>
    </acct>
    <status>1</status>
    <statusmsg>Ok</statusmsg>
</listaccts>

Parameters

Parameter Type Description Possible values Example

searchtype

string

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.

domain

search

string

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 returns all of the server's accounts.

A valid PCRE.

username

Returns

Return	Type	Description	Possible values	Example
`acct`	array of hashes	A hash of account data.	This hash includes the `backup`, `disklimit`, `diskused`, `domain`, `email`, `ip`, `is_locked`, `legacy_backup`, `max_defer_fail_percentage`, `max_email_per_hour`, `maxaddons`, `maxftp`, `maxlst`, `maxparked`, `maxpop`, `maxsql`, `maxsub`, `min_defer_fail_to_trigger_protection`, `owner`, `partition`, `outgoing_mail_suspended, outgoing_mail_hold, plan`, `shell`, `startdate`, `suspended`, `suspendreason`, `suspendtime`, `theme`, `unix_startdate`, and `user` returns.
`backup`	Boolean	Whether backups are enabled. The function returns this value in the `acct` hash.	`1` — Enabled. `0` — Disabled.	`0`
`disklimit`	string	The account's disk space quota. The function returns this value in the `acct` hash.	`unlimited` A maximum amount of disk space, in Megabytes (MB).	`unlimited`
`diskused`	string	The account's current disk space usage. The function returns this value in the `acct` hash.	An integer that represents an amount of disk space, in Megabytes (MB). For example, `14M` represents 14 MB of disk space.	`14M`
`domain`	string	The account's main domain. The function returns this value in the `acct` hash.	A valid domain name on the account.	`example.com`
`email`	string	The account's contact email address. The function returns this value in the `acct` hash.	A valid email address.	`username@example.com`
`ip`	string	The account's main domain's IP address. The function returns this value in the `acct` hash.	A valid IPv4 address.	`192.168.0.128`
`ipv6`	string	The account's main domain's IPv6 address The function returns this value in the `acct` hash.	A valid IPv6 address.	0101:ca75:0101:ca75:0101:ca75:0101:ca77
`is_locked`	Boolean	Whether the account is currently locked. The function returns this value in the `acct` hash.	`1` — The account is locked. `0` — The account is not locked.	`0`
`legacy_backup`	Boolean	Whether legacy backups are enabled. The function returns this value in the `acct` hash.	`1` — Enabled. `0` — Disabled.	`0`
`max_defer_fail_percentage`	string	The percentage of failed or deferred email messages that the account can send per hour before the system rate-limits outgoing mail. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a percentage of messages.	`unlimited`
`max_email_per_hour`	string	The maximum number of emails that the account can send in one hour. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a number of sent emails.	`unlimited`
`maxaddons`	string	The account's maximum number of addon domains. The function returns this value in the `acct` hash.	`unlimited` `unknown` — The account cannot use addon domains. An integer that represents a number of addon domains.	`unlimited`
`maxftp`	string	The account's maximum number of FTP accounts. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a number of FTP accounts.	`unlimited`
`maxlst`	string	The account's maximum number of mailing lists. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a number of mailing lists.	`unlimited`
`maxparked`	string	The account's maximum number of parked domains (aliases). The function returns this value in the `acct` hash.	`unlimited` `unknown` — The account cannot use parked domains. An integer that represents a number of parked domains.	`unlimited`
`maxpop`	string	The account's maximum number of email addresses. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a number of email accounts.	`unlimited`
`maxsql`	string	The account'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. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a number of SQL databases.	`unlimited`
`maxsub`	string	The account's maximum number of subdomains. The function returns this value in the `acct` hash.	`unlimited` `unknown` — The account cannot use subdomains. An integer that represents a number of subdomains.	`unlimited`
`min_defer_fail_to_trigger_protection`	string	The minimum number of failed or deferred messages that the account can send before outgoing mail is subject to rate-limiting. The function returns this value in the `acct` hash.	`unlimited` An integer that represents a number of failed or deferred messages.	`5`
`outgoing_mail_suspended`	Boolean	Whether to suspend outgoing email from the account's users and force failure of any of their mail currently in the mail queue. Note: If mail for a cPanel user's account is suspended, the system will reject their email before the system puts it in the mail server queue. The function returns this value in the `acct` hash. Note: We added this parameter in cPanel & WHM version 56.	`1` — Suspend and force failure of outgoing email. `0` — Do not suspend and force failure of outgoing email.	`0`
`outgoing_mail_hold`	Boolean	Whether to retain outgoing mail in the mail queue for the account's users. The function returns this value in the `acct` hash. Note: We added this parameter in cPanel & WHM version 56.	`1` — Retain outgoing email in the mail queue. `0` — Do not retain outgoing email in the mail queue.	`0`
`owner`	string	The account's owner. The function returns this value in the `acct` hash.	`root` A reseller account's username.	`root`
`partition`	string	The partition that contains the account's home directory. The function returns this value in the `acct` hash.	The name of a partition on the server.	`home`
`plan`	string	The account's hosting package. The function returns this value in the `acct` hash.	The name of a package on the server.	`packagename`
`shell`	string	The account's shell. The function returns this value in the `acct` hash.	The absolute path of a shell location on the server.	`/bin/bash`
`startdate`	string	The account creation date. The function returns this value in the `acct` hash.	The date in `YYYY-MM-DD HH-mm-SS` human-readable format, where: `YYYY` represents the year. `MM` represents the month. `DD` represents the date. `HH` represents the hour. `mm` represents the minute. `SS` represents the second.	`13 May 22 16:03`
`suspended`	Boolean	Whether the account is currently suspended. The function returns this value in the `acct` hash.	`1` — Suspended. `0` — Not suspended.	`0`
`suspendreason`	string	The reason for account suspension, if the suspender provided one. The function returns this value in the `acct` hash.	`null` — The account is not currently suspended. A blank value, if the suspender did not provide a reason. A message that explains the suspension.	`not suspended`
`suspendtime`	string	The time of suspension. The function returns this value in the `acct` hash.	`null` — The account is not currently suspended. The time at which the account became suspended.	`null`
`theme`	string	The account's cPanel interface theme. The function returns this value in the `acct` hash.	`paper_lantern` Another valid theme on the server.	`paper_lantern`
`unix_startdate`	string	The account creation date. The function returns this value in the `acct` hash.	The account creation date and time, in Unix time format.	`1369256589`
`user`	string	The account username. The function returns this value in the `acct` hash.	The `user` parameter's value.	`username`
`status`	Boolean	Whether the system successfully called the function.	`1` — Success. `0` — Failure.	`1`
`statusmsg`	string	A message of success or a reason for failure.	`Ok` An error message.	`Ok`

Function information

API Version:

WHM API 0

WHM API 1 Equivalent:

listaccts

Important:

We strongly recommend that you use WHM API 1. WHM API 0 is deprecated.

Available in:

WHM 11+

Methods:

GET, POST

Required Parameters:

(none)

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

About WHM API 0

WHM API 0 performs functions and accesses data in WHM.

Warning:

WHM API 0 is deprecated. We strongly recommend that you use the equivalent WHM API 1 function instead.