Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function suspends an account. Suspension denies the user access to the account. Unlike account deletion, suspension is reversible.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/suspendacct?user=username&reason=Nonpayment
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/suspendacct?user=username&reason=Nonpayment
 Command Line
whmapi0 suspendacct user=username reason=Nonpayment

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. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
   "result":[
      {
         "status":1,
         "statusmsg":"<script>if (self['clear_ui_status']) { clear_ui_status(); }</script>
\nChanging Shell to /bin/false...Changing shell for user123.\nWarning: \"/bin/false\"
is not listed in /etc/shells\nShell changed.\nDone\nLocking Password...Locking
password for user user123.\npasswd: Success\nDone\nSuspending mysql users\n
Notification => user@example.com via EMAIL [level => 3]\nUsing Quota v3
Support\nSuspended document root /home/user123/public_html\nUsing Quota v3
Support\nSuspending FTP accounts...\nUpdating ftp passwords for user123\nFtp
password files updated.\nFtp vhost passwords synced\nuser123's account has
been suspended\n"
      }
   ]
}
 Output (XML)
<suspendacct>
    <result>
        <status>1</status>
        <statusmsg>
            <script>if (self['clear_ui_status']) { clear_ui_status(); }</script>
            Changing Shell to /bin/false...Changing shell for user123.
            Warning: "/bin/false" is not listed in /etc/shells
            Shell changed.
            Done
            Locking Password...Locking password for user user123.
            passwd: Success
            Done
            Suspending mysql users
            Notification => user@example.net via EMAIL [level => 3]
            Using Quota v3 Support
            Suspended document root /home/cpanel1/public_html
            Using Quota v3 Support
            Suspending FTP accounts...
            Updating ftp passwords for user123
            Ftp password files updated.
            Ftp vhost passwords synced
            user123's account has been suspended
        </statusmsg>
    </result>
</suspendacct>

Parameters

ParameterTypeDescriptionPossible valuesExample
userstring

Required

The account to suspend.

A valid cPanel or WHM username on the server.username
reasonstring

The reason for suspension.

Important:

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

A string value.Nonpayment
disallowunBoolean

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

This parameter defaults to 0.

  • 1 — Only the root user can unsuspend the account.
  • 0 — The root user or the account's owner can unsuspend the account.
1

Returns

ReturnTypeDescriptionPossible valuesExample
resultarray of hashesAn array of hashes of function informationThis hash includes the status and statusmsg returns. 

status

Boolean

Whether the system successfully called the function.

The function returns this value in the result hash.

  • 1 — Success.
  • 0 — Failure.

 

1

statusmsg

string

A message of success or a reason for failure.

The function returns this value in the result hash.

  • A message of success.
  • An error message.
 Click to view...
<script>if (self['clear_ui_status']) { clear_ui_status(); }</script>
             Changing Shell to /bin/false...Changing shell for user123.
             Warning: "/bin/false" is not listed in /etc/shells
             Shell changed.
             Done
             Locking Password...Locking password for user user123.
             passwd: Success
             Done
             Suspending mysql users
             Notification => user@example.net via EMAIL [level => 3]
             Using Quota v3 Support
             Suspended document root /home/cpanel1/public_html
             Using Quota v3 Support
             Suspending FTP accounts...
             Updating ftp passwords for user123
             Ftp password files updated.
             Ftp vhost passwords synced
             user123's account has been suspended