Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

List Accounts — listaccts

This function lists all accounts on the server, and also allows you to search for a specific account or set of accounts.

Calling Functions

Using the XML API

To use the XML API to perform the listaccts function from within your custom script:

  • Append the /xml-api/listaccts function call name, plus the required variables (see below), to a URL which includes the address of your server.

  • For example, on a server whose hostname is example.com, you would include the following string in your script: https://example.com:2087/xml-api/listaccts

  • You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

  • You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Using the JSON API

To use the JSON API to perform the listaccts function from within your custom script:

  • Append the /json-api/listaccts function call name, plus the required variables (see below), to a URL which includes the address of your server.

  • For example, on a server whose hostname is example.com, you would include the following string in your script: https://example.com:2087/json-api/listaccts

  • You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

  • You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Variables

Input

The listaccts function takes the following optional variables as input:

  • searchtype (string) — The type of account search. Allowed values are: domain, owner, user, ip, package
  • search (string) — Search criteria; this field takes regular expressions.

Output

Show Hide

  • listaccts — Operation container.
    • acct — Container for the account information.
      • maxaddons (integer or string) — The maximum number of addon domains available to the account.
      • ip (integer) — IP address of root domain on the account.
      • min_defer_fail_to_trigger_protection (integer) — The minimum number of failed or deferred email messages the account can send before outgoing mail is rate-limited (according to the percentage set by the max_defer_fail_percentage value). This parameter's default value is unlimited. This parameter is only available in version 11.32+.
      • legacy_backup (boolean) — Whether or not the Legacy Backups feature is used for the account. This parameter is only available in version 11.38+.
        • 1 — yes
        • 0 — no
      • diskused (string) — Current disk space usage for the account, in Megabytes. Example: 500M
      • maxftp (integer or string) — The maximum number of FTP accounts available to the account.
      • startdate (date) — Date and time of plan creation. Format: YY MMM DD HH:MM
      • max_defer_fail_percentage (integer) — The percentage of failed or deferred email messages the account can send per hour before outgoing mail is rate-limited. The system only applies this value after the min_defer_fail_to_trigger_protection value is met. This parameter's default value is unlimited. This parameter is only available in version 11.32+.
      • disklimit (string) — Disk space usage limit for the account, in Megabytes. Example: 500M
      • suspendtime (integer) — The time of the account's suspension in Unix epochal time. This XML node will appear undefined if the account is not suspended.
      • email (string) — Contact email address for the account. Example: user@example.com
      • domain (string) — Name of the root domain for the account. Example: example.com
      • unix_startdate (integer) — The date the account was created in Unix epochal time.
      • user (string) — Username associated with the account. Format: username
      • plan (string) — Hosting package associated with the account.
      • shell (string) — The path to the shell, if the cPanel account has shell access. (e.g. /bin/bash)
      • maxpop (integer or string) — The maximum number of email accounts available to the account.
      • backup (boolean) — Whether or not the Backup Configuration feature is used for the account. This parameter is only available in version 11.38+.
        • 1 — yes
        • 0 — no
      • theme (string) — cPanel interface theme associated with the account.
      • owner (string) — Reseller or root owner of the account. Example: username
      • max_email_per_hour (integer) — The maximum number of emails the account can send in an hour. This parameter's default value is unlimited. This parameter is only available in version 11.32+.
      • ipv6 (string) — The IPv6 address associated with the account. This parameter is only available in version 11.40+.
        • note Note: If no IPv6 address has been assigned to the account, this parameter is not included.
      • suspended reason (string) — A reason why the account is currently suspended.
      • maxlst (string) — The maximum number of mailing lists available to the account.
      • suspended (boolean) — Whether or not the account has been suspended.
        • 1 — yes
        • 0 — no
      • maxsql (integer or string) — The maximum number of databases available to the account.
      • maxparked (integer or string) — The maximum number of parked domains available to the account.
      • partition (string) — The disk/partition on which the user's home directory is located.
      • maxsub (integer or string) — The maximum number of subdomains available to the account.
  • metadata — The XML metadata container.
    • version — The version of the XML API used.
    • reason — A string value that contains a message of success or a reason for failure.
    • result — A boolean value that indicates the success or failure.
    • command — The XML API function that has returned the data.

Examples

XML API

Calling this function from WebHost Manager:

https://example.com:2087/xml-api/listaccts?api.version=1&search=jack

will produce output similar to the following:

<listaccts>
   <acct>
      <backup>1</backup>
      <disklimit>unlimited</disklimit>
      <diskused>14M</diskused>
      <domain>example.com</domain>
      <email>example@example.com</email>
      <ip>10.215.214.95</ip>
      <ipv6>0101:ca75:0101:ca75:0101:ca75:0101:ca75</ipv6>
      <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>
      <owner>root</owner>
      <partition>home</partition>
      <plan>x3</plan>
      <shell>/bin/bash</shell>
      <startdate>12 Sep 07 11:08</startdate>
      <suspended>0</suspended>
      <suspendreason>not suspended</suspendreason>
      <suspendtime/>
      <theme>x3</theme>
      <unix_startdate>1347034087</unix_startdate>
      <user>jack</user>
   </acct>
</listaccts>

note Note: Typing ?searchtype=user&search=jack limits the results to accounts with a username containing jack.

JSON API

Calling this function from WebHost Manager:

https://example.com:2087/json-api/listaccts?api.version=1&search=jack

will produce output similar to the following:

{
    "acct": [{
            "maxaddons": "*unknown*",
            "ip": "10.215.214.95",
            "min_defer_fail_to_trigger_protection": 5,
            "legacy_backup": 0,
            "diskused": "0M",
            "maxftp": "unlimited",
            "startdate": "13 Mar 22 11:37",
            "max_defer_fail_percentage": "*unknown*",
            "disklimit": "unlimited",
            "suspendtime": null,
            "email": "example@example.com",
            "domain": "example.com",
            "unix_startdate": 1363970238,
            "user": "jack",
            "plan": "default",
            "shell": "/bin/bash",
            "maxpop": "unlimited",
            "backup": 0,
            "theme": "x3",
            "owner": "root",
            "max_email_per_hour": "*unknown*",
            "ipv6": ["0101:ca75:0101:ca75:0101:ca75:0101:ca77"],
            "suspendreason": "not suspended",
            "maxlst": "unlimited",
            "suspended": 0,
            "maxsql": "unlimited",
            "maxparked": "*unknown*",
            "partition": "home",
            "maxsub": "unlimited"
        }
    ],
    "statusmsg": "Ok",
    "status": 1
}
note Note: Typing ?searchtype=user&search=jack limits the results to accounts with a username containing jack.

Topic revision: r14 - 23 Dec 2013 - 16:06:08 - Main.StacyWyatt