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

Modify an Account — modifyacct

This function modifies settings for an account.

PICK Important: Instead of this function call, we recommend that you change the account's package with the Upgrade/Downgrade an Account feature. After you modify an account with this API function, your changes may be overwritten when you modify the account's package.

Calling Functions

Using the XML API

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

  • Append the /xml-api/modifyacct 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/modifyacct

  • 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 modifyacct function from within your custom script:

  • Append the /json-api/modifyacct 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/modifyacct

  • 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 modifyacct function takes the following required variable as input:

  • user (string) — User name of the account. Example: user

The modifyacct function takes the following optional variables as input:

  • DNS (string) — Domain name. Example: domain.tld (domain is an alias)
  • contactemail (string) — Primary contact email address for the account.
  • newuser (string) — The new username of the account.
  • owner (string) — Change the owner of the account to the specified owner. (OWNER is an alias)
    • note Note: You can designate a reseller to be the account's owner using this parameter: owner = reseller username. You must have root privileges to assign an account to a reseller other than yourself. If the requested username does not exist, the system will assign the account to the caller.
  • BWLIMIT (string) — Number of bytes in assigned to the user's bandwidth limit. Allowed values:
    • A number.
    • unlimited is unlimited.
  • HASCGI (boolean) — Whether or not the domain has CGI access.
    • 1 — yes.
    • 0 — no.
  • HASDKIM(boolean) — Whether or not the domain has DKIM enabled.
    • 1 — yes.
    • 0 — no.
  • HASSHELL (boolean) — Whether or not the domain has shell access. (SHELL is an alias)
    • 1 — yes.
    • 0 — no.
  • HASSPF (boolean) — Whether or not the domain has SPF enabled.
    • 1 — yes.
    • 0 — no.
  • LOCALE (string) — Locale to use in the account's cPanel interface. For example: en
    • note Note: This input variable is only compatible with WHM version 11.25 and later.
  • MAXFTP (string) — Maximum number of FTP accounts the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXSQL (string) — Maximum number of SQL databases the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXPOP (string) — Maximum number of email accounts the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXLST (string) — Maximum number of mailing lists the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXMONGREL (string) — Maximum number of Mongrel instances the user can run at the same time. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXSUB (string) — Maximum number of subdomains the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXPARK (string) — Maximum number of parked domains the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAXADDON (string) — Maximum number of addon domains the user can create. Allowed values:
    • A number from 0 to 999999.
    • unlimited
    • null
  • MAX_EMAIL_PER_HOUR (integer) — The maximum number of emails the account can send in an hour. This parameter's default value is unlimited. A value of 0 will result in an unlimited value.
  • 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.
  • RS (string) — cPanel theme name. Example: x3 (CPTHEME is an alias)
  • QUOTA (string) — Number of bytes in assigned to the user's disk quota. Allowed values:
    • A number.
      • 0 is unlimited.
    • unlimited is unlimited.

The following variables were introduced in version 11.40:

  • remove_missing_extensions (space delimited) — Removes missing or uninstalled extensions.
    ALERT! Warning: This parameter will remove all of the extensions that you enter from the _PACKAGE_EXTENSIONS parameter in the package file. It will not remove the associated extension variables.
  • If you have one or more package extensions associated with this account, you can also input the variables associated with the extension when you use the modifyacct function. Consult the documentation for your extension for a list of possible variables.
    • Package extensions variables are case-sensitive.

Output

note Note: The output of this function may vary depending on the version of WHM installed on your server.

  • modifyacct — Root-level XML tag for the output of the modifyacct function.
    • result (string) — Container for the results of the request.
      • messages (string) — Information about the request.
      • newcfg — Container for the new configuration options.
        • cpuser — Container for the modified account's information.
          • BWLIMIT (int) — Maximum amount of bandwidth transfer the account can use, in Megabytes. Possible values:
            • A number from 0 to 999999.
              • 0 is unlimited.
            • unlimited
            • null
          • CONTACTEMAIL (string) — Primary contact email address for the account.
          • CONTACTEMAIL2 (string) — Secondary contact email address for the account.
          • DEADDOMAINS (string) — Old domains that are associated with the account, but no longer active.
          • DEMO (boolean) — Whether or not demo mode is enabled on the account.
          • DOMAIN (string) — Main domain associated with the account.
          • DOMAINS (string) — Other domains associated with the account.
          • FEATURELIST (string) — Name of the feature list associated with the account.
          • HASCGI (string) — Whether or not the domain has CGI access.
            • y — yes.
            • n — no.
          • IP (string) — The IP address associated with the account.
          • LOCALE (string) — Locale to use in the account's cPanel interface. Example: en
            • *LANG is a deprecated alias.
          • MAXFTP (string) — Maximum number of FTP accounts the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • MAXSQL (string) — Maximum number of SQL databases the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • MAXPOP (string) — Maximum number of email accounts the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • MAXLST (string) — Maximum number of mailing lists the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • MAXSUB (string) — Maximum number of subdomains the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • MAXPARK (string) — Maximum number of parked domains the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • MAXADDON (string) — Maximum number of addon domains the user can create. Possible values:
            • A number from 0 to 999999.
            • unlimited
            • null
          • OWNER (string) — Name of the user who owns the account.
          • PLAN (string) — Name of the package associated with the account.
          • RS (string) — The cPanel theme the account uses.
          • STARTDATE (UNIX time) — Date the account was created.
          • USER (string) — Username associated with the account.
            • CPTHEME is an alias
          • MAX_EMAIL_PER_HOUR (integer) — The maximum number of emails the account can send in an hour. This parameter's default value is unlimited.
          • 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. This parameter's default value is unlimited.
        • domain (string) — Domain associated with the account.
        • setshell (string) — Location of the shell program associated with the account.
        • user (string) — Username associated with the account.
      • status (boolean) — Status of the request.
      • statusmsg (string) — Detailed message about the status of the request.

Examples

XML API

Calling this URL from WebHost Manager:

https://example.com:2087/xml-api/modifyacct?user=user&domain=domain.com&HASCGI=0&CPTHEME=x3 &LANG=english&MAXPOP=3&MAXFTP=0&MAXLST=1&MAXSUB=3&MAXPARK=4&MAXADDON=5&MAXSQL=6&shell=1

will produce output similar to the following:

<modifyacct>
     <result>
            <messages>Changing shell for user.
            Shell changed.</messages>
             <newcfg>
                  <cpuser>
                        <BWLIMIT>5242880000</BWLIMIT>
                         <CONTACTEMAIL>owner@domain.com</CONTACTEMAIL>
                         <CONTACTEMAIL2></CONTACTEMAIL2>
                         <DEADDOMAINS>oldsub.domain.com</DEADDOMAINS>
                         <DEMO>0</DEMO>
                         <DOMAIN>domain.com</DOMAIN>
                         <DOMAINS>sub.domain.com</DOMAINS>
                         <DOMAINS>addondomain.com</DOMAINS>
                         <FEATURELIST>reseller_gold</FEATURELIST>
                         <HASCGI>0</HASCGI>
                         <IP>208.77.188.166</IP>
                         <LANG>english</LANG>
                         <LOCALE>en</LOCALE>
                         <MAXADDON>5</MAXADDON>
                         <MAXFTP>0</MAXFTP>
                         <MAXLST>1</MAXLST>
                         <MAXPARK>4</MAXPARK>
                         <MAXPOP>3</MAXPOP>
                         <MAXSQL>6</MAXSQL>
                         <MAXSUB>3</MAXSUB>
                         <OWNER>root</OWNER>
                         <PLAN>reseller_gold</PLAN>
                         <RS>x3</RS>
                         <STARTDATE>1175808157</STARTDATE>
                         <USER>user</USER>
                   </cpuser>
                   <domain>domain.com</domain>
                   <setshell>/bin/bash</setshell>
                   <user>user</user>
             </newcfg>
              <status>1</status>
              <statusmsg>Account Modified</statusmsg>
      </result>
</modifyacct> 

JSON API

Calling this URL from WebHost Manager:

https://example.com:2087/json-api/modifyacct?user=gus&domain=example.com&HASCGI=0&CPTHEME=x3 &LANG=english&MAXPOP=3&MAXFTP=0&MAXLST=1&MAXSUB=3&MAXPARK=4&MAXADDON=5&MAXSQL=6&shell=1

will produce output similar to the following:

{
   "result":[
      {
         "newcfg":{
            "setshell":"/bin/bash",
            "domain":"example.com",
            "user":"gus",
            "cpuser":{
               "DEADDOMAINS":[

               ],
               "IP":"127.0.0.1",
               "MAXSUB":"3",
               "DOMAIN":"example.com",
               "CONTACTEMAIL":"",
               "MAXSQL":"6",
               "MAXFTP":"0",
               "LOCALE":"en",
               "HASCGI":0,
               "CONTACTEMAIL2":"",
               "DEMO":"0",
               "USER":"gus",
               "FEATURELIST":"default",
               "BWLIMIT":"5242880",
               "DOMAINS":[

               ],
               "STARTDATE":"1242737345",
               "OWNER":"gus",
               "MAXPARK":"4",
               "RS":"x3",
               "PLAN":"level3 ",
               "MAXADDON":"5",
               "MAXPOP":"3",
               "MAXLST":"1",
               "LANG":"english"
            }
         },
         "status":1,
         "statusmsg":"Account Modified",
         "warnings":[

         ],
         "messages":[
            "Changing shell for gus.\nShell changed.\n"
         ]
      }
   ]
}

Topic revision: r19 - 07 Oct 2013 - 21:12:50 - Main.SarahHaney