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

Documentation Home> SoftwareDevelopmentKit>XmlApiEditAttach

Create an Account — createacct

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

Calling Functions

Using the XML API

Show Hide

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

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

  • 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

Show Hide

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

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

  • 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 createacct function takes the following variables as input.

The following variables are required:

  • username (string) — Username for the account. Example: user
    • note Note: This variable must consist of between 1 and 8 characters (letters and/or numbers). It cannot start with a number, or the string test.
  • domain (string) — Domain name. Example: domain.tld

The following variables are optional:

  • plan (string) — Package to use for account creation. Example: reseller_gold
  • pkgname (string) — Name of a new package to be created based on the settings used. Example: reseller_silver
  • savepkg (boolean) — Save the settings used as a new package.
    • 1 — yes.
    • 0 — no.
  • featurelist (string) — Name of the feature list to be used when creating a new package. Example: no_ftp_100mb_gold
  • quota (integer) — Disk space quota in Megabytes. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
  • password (string) — Password for accessing cPanel. Example: p@ss!w0rd$123
  • ip (string) — Whether or not the domain has a dedicated IP address.
    • y — yes.
    • n — no.
  • cgi (boolean) — Whether or not the domain has CGI access.
    • 1 — yes.
    • 0 — no.
  • frontpage (boolean) — Whether or not the domain has FrontPage extensions installed.
    • 1 — yes.
    • 0 — no.
  • hasshell (boolean) — Whether or not the domain has shell/SSH access.
    • 1 — yes.
    • 0 — no.
  • contactemail (string) — Contact email address for the account. Example: user@otherdomain.tld
  • cpmod (string) — cPanel theme name. Example: x3
    • If no value is provided, the function will use the cPanel default theme (set in WHM in the Basic cPanel & WHM Setup screen). This behavior only applies to version 11.36+.
  • maxftp (string) — Maximum number of FTP accounts the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • maxsql (string) — Maximum number of SQL databases the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • maxpop (string) — Maximum number of email accounts the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • maxlst (string) — Maximum number of mailing lists the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • maxsub (string) — Maximum number of subdomains the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • maxpark (string) — Maximum number of parked domains the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • maxaddon (string) — Maximum number of addon domains the user can create. Allowed values:
    • A number from 0 to 999999.
      • 0 is unlimited.
    • unlimited
    • null
  • bwlimit (string) — Bandiwdth limit in Megabytes. Must be a number from 0 to 999999.
    • 0 is unlimited.
  • customip (string) — Specific IP address for the site.
  • language (string) — Language to use in the account's cPanel interface. Example: spanish-utf8
  • useregns (boolean) — Use the registered nameservers for the domain instead of the ones configured on the server.
    • 1 — yes.
    • 0 — no.
  • hasuseregns (boolean) — Set to 1 if you are using the above option.
  • reseller (boolean) — Give reseller privileges to the account.
    • 1 — yes.
    • 0 — no.
  • forcedns (boolean) — Overwrite current DNS Zone if a DNS Zone already exists.
    • 1 — yes.
    • 0 — no.
  • mxcheck (string) — Determines how the server will handle incoming mail for this domain. This variable can be set to one of the following:
    • local — The domain will accept mail, regardless of whether a higher-priority mail exchanger has been designated on the WHM Edit MX Entry screen. (If a higher-priority mail exchanger exists, mail will be routed to both domains.)
    • secondary (or backup) — The domain will act as a backup mail exchanger, holding mail in queue if the primary exchanger becomes unavailable.
      • note Note: You will still need to use the WHM Edit MX Entry screen to configure the primary MX entry to point to the appropriate exchanger.
    • remote — The domain will not accept mail, instead sending it to the primary mail exchanger.
      • note Note: You will still need to use the WHM Edit MX Entry screen to configure the primary MX entry to point to the appropriate exchanger.
    • auto — The server will automatically detect, and use, the configuration set on the WHM Edit MX Entry screen.
  • MAX_EMAIL_PER_HOUR (integer) — The maximum number of emails the account can send in an hour. This parameter's default value is unlimited. Entering 0 here will result in an unlimited value. This variable is only accepted in version 11.32+.
  • 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 variable is only accepted in version 11.32+.
  • MIN_DEFER_FAIL_TO_TRIGGER_PROTECTION (integer) — The minimum number of failed or deferred email messages the account can send before outgoing mail is subject to rate-limiting (according to the percentage set by the MAX_DEFER_FAIL_PERCENTAGE value). This parameter's default value is unlimited. This variable is only accepted in version 11.32+.
  • uid (string) — The user ID for a new account. This must be a numeral, not already associated with disk usage, and does not pre-exist on the machine. You must be logged in as the root user. This variable is only accepted in version 11.34+.
  • gid (string) — The group ID for a new account. This must be a numeral, not already associated with disk usage, and does not pre-exist on the machine. You must be logged in as the root user. This variable is only accepted in version 11.34+.
  • homedir (string) — The home directory (HOMEDIR) to be used for a new account. You must be logged in as the root user. Example: /home/johndoe This variable is only accepted in version 11.34+.

Output

Show Hide

  • createacct — Root-level XML tag for the output of the createacct function.
    • result — Operation results container.
      • options — Domain options container.
        • ip (string) — IP address with which the the domain is associated. Example: 123.456.789.10
        • nameserver or nameserverx — Nameserver for the domain.
          • nameserver may be appended by an integer (x) between 1 and 5. Example: nameserver1
        • nameservera or nameserverax — IP address of the nameserver.
          • nameservera may be appended by an integer (x) between 1 and 5. Example: nameservera1
        • nameserverentry or nameserverentryx — DNS name of the namservers (if using registered nameservers).
          • nameserverentry may appear appended by an integer (x) between 1 and 5. Example: nameserverentry1
      • rawout (HTML) — Raw output of the account creation operation.
      • status (boolean) — Status of the operation.
        • 1 — success.
        • 0 — failure.
      • statusmsg (string) — Status or error message.

Examples

XML API

Show Hide

Calling the following function in WebHost Manager:

https://example.com:2087/xml-api/createacct?username=myuser&plan=basic &ip=n&cpmod=x3&password=h@rd2gu3ss!p@ss&contact email=username @domain.tld&domain=domain.tld&useregns=0&reseller=0

will produce output similar to: 

<createacct>
     <result>        
          <options>
                  <ip>192.168.1.1</ip>
                  <nameserver>ns1.domain.tld</nameserver>
                  <nameserver2>ns2.domain.tld</nameserver2>
                  <nameserver3/>
                  <nameserver4/>
                  <nameservera/>
                  <nameservera2/>
                  <nameservera3/>
                  <nameservera4/>
                  <nameserverentry/>
                  <nameserverentry2/>
                  <nameserverentry3/>
                  <nameserverentry4/>
                  <package>basic</package>
           </options>
           <rawout>
Checking input data...The ProFTPd configuration file /etc/proftpd.conf appears to be ok!
System has 0 free ips.
...Done

WWWAcct 12.1.0 (c) 1997-2008 cPanel, Inc....

Dns Zone check is enabled.
+===================================+
| New Account Info                  |
+===================================+
| Domain: domain.tld
| Ip: 208.77.188.166 (n)
| HasCgi: y
| UserName: myuser
| PassWord: h@rd2gu3ss!p@ss
| CpanelMod: x3
| HomeRoot: /home
| Quota: 0 Meg
| NameServer1: ns1.example.com
| NameServer2: ns2.example.com
| NameServer3: ns1.domain.com
| NameServer4: 
| Contact Email: username@domain.tld
| Package: basic
| Feature List: default
| Language: english
+===================================+
...Done

Running pre creation script (/scripts/prewwwacct)......Done
Adding User...Removing Shell Access (n)
...Done
Copying skel files from /root/cpanel3-skel/ to /home/myuser/......Done
Adding Entries to httpd.conf......Done
Setting up Mail and Local Domains...localdomains...
valiases ...vdomainaliases...vfilters......Done
Configuring DNS...Bind reconfiguring on server1 using rndc
...Done
Restarting apache......Done
Changing password for myuser Password for myuser has been changed
Updating Authentication Databases...Updating ftp passwords for myuser
Ftp password files updated.
Ftp vhost passwords synced
...Done
Verifying MX Records and Setting up Databases......Done
Setting up Proxy Subdomains......Done
Bind reloading on server1 using rndc zone: [domain.tld]
Sending Account Information......Done
System has 0 free ips.
Running post creation scripts (/scripts/legacypostwwwacct, 
/scripts/postwwwacct, /scripts/postwwwacctuser)......Done
wwwacct creation finished
Setting up Domain Pointers......Done
Setting Reseller Privs......Done
Account Creation Complete!!!...Account Creation Ok...Done
            </rawout>
            <status>1</status>
            <statusmsg>Account Creation Ok</statusmsg>
     </result>
</createacct>

note Note: Submit the entire request as a single string. For display purposes, the examples above may be wrapped.

JSON API

Show Hide

Calling the following function in WebHost Manager:

https://example.net:2087/json-api/createacct?username=user123&plan=level3 &ip=n&cpmod=x3&password=h@rd2gu3ss!p@ss&contact%20email=username @example.com&domain=example.com&useregns=0&reseller=0

will produce output similar to: 

{
   "result":[
      {
         "status":1,
         "statusmsg":"Account Creation Ok",
         "rawout":"<table style=\"border- bottom: 1px #ccc dotted;\"><tr><td width=\"100%\">
<pre>Checking input data...System  has 2 free ips.\n...Done</pre></td><td width=\"30\">
<img align=absmiddle  src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td>
</tr></table>\n<table  style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\">
<pre>WWWAcct 12.1.0  (c) 1997-2008 cPanel, Inc....\n\nDns Zone check is  enabled.
\n+===================================+\n| New Account Info                   
|\n+===================================+\n| Domain: example.com\n| Ip: 127.0.0.1  
(n)\n| HasCgi: y\n| UserName: user123\n| PassWord: h@rd2gu3ss!p@ss\n| CpanelMod:  
x3\n| HomeRoot: /home\n| Quota: 0 Meg\n| NameServer1: ns1.example.net\n|  
NameServer2: ns2.example.net\n| NameServer3: ns1.example.com\n|  NameServer4: 
ns2.example.com\n| Contact Email: \n| Package: level3==\n|  Feature List: default\n|  
Language: english\n+===================================+\n...Done</pre> 
</td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\">
</td></tr></table>\n<table  style=\"border-bottom: 1px #ccc dotted;\"><tr><td 
width=\"100%\"><pre>Running pre  creation script 
(/scripts/prewwwacct)......Done</pre></td><td width=\"30\"><img  
align=absmiddlesrc=\"/cPanel_magic_revision_ 1181098607/icons/good.gif\"> 
</td></tr></table>\n<table 
style=\"border-bottom: 1px #ccc dotted;\"><tr> <td 
width=\"100%\"><pre>Adding User...Removing Shell Access (n)\n...Done</pre> 
</td><td width=\"30\"><img align=absmiddle 
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\">
</td></tr></table>\n<table  style=\"border-bottom: 1px #ccc dotted;\">
<tr><td width=\"100%\"><pre>Copying skel  files from /root/cpanel3-skel/ to 
/home/user123/......Done</pre></td><td width=\"30\"> <img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Adding Entries  
to httpd.conf......Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Setting up Mail  
& Local Domains...localdomains...valiases ...vdomainaliases...vfilters......Done</pre></td> 
<td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Configuring  
DNS...Bind reconfiguring on publicdocs using rndc\n...Done</pre></td><td width=\"30\"> 
<img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Restarting  
apache......Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\nChanging  
password for user123\nPassword for user123 has been changed\n<table style=\"border- 
bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Updating Authentication  
Databases...Updating ftp passwords for user123\nFtp password files updated.\nFtp vhost  
passwords synced\n...Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\">
</td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Verifying MX  
Records and Setting up Databases......Done</pre></td><td width=\"30\"><img  
align=absmiddle src=\"/cPanel_magic_revision_1181098607/icons/good.gif\">
</td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Setting up 
Proxy  Subdomains......Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\nBind  
reloading on publicdocs using rndc zone: [example.com]\n<table style=\"border-bottom:  
1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Sending Account  
Information......Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td>
</tr></table>\nSystem  has 2 free ips.\n<table style=\"border-bottom: 1px #ccc dotted;\">
<tr><td  width=\"100%\"><pre>Running post creation scripts (/scripts/legacypostwwwacct,  
/scripts/postwwwacct, /scripts/postwwwacctuser)......Done</pre></td><td width=\"30\"> 
<img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr>
</table>\nwwwacct  creation finished\n<table style=\"border-bottom: 1px #ccc dotted;\">
<tr><td  width=\"100%\"><pre>Setting up Domain Pointers......Done</pre></td><td 
width=\"30\"> <img align=absmiddle 
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>
\n<table  style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\">
<pre>Setting Reseller Privs......Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\n<table  
style=\"border-bottom: 1px #ccc dotted;\"><tr><td width=\"100%\"><pre>Account Creation  
Complete!!!...Account Creation Ok...Done</pre></td><td width=\"30\"><img align=absmiddle  
src=\"/cPanel_magic_revision_1181098607/icons/good.gif\"></td></tr></table>\n",
         "options":{
            "nameserver4":"ns2.example.com",
            "nameserver":"ns1.example.net",
            "nameserverentry2":null,
            "nameserverentry3":null,
            "nameserverentry4":null,
            "nameserverentry":null,
            "ip":"127.0.0.1",
            "nameservera2":null,
            "nameservera3":null,
            "package":"level3==",
            "nameservera4":null,
            "nameserver2":"ns2.cpanelrocks.net",
            "nameservera":null,
            "nameserver3":"ns1.example.com"
         }
      }
   ]
}

note Note: Submit the entire request as a single string. For display purposes, the examples above may be wrapped.

Edit | Attach | Print version | History: r18 < r17 < r16 < r15 < r14 | Backlinks | Raw View | More topic actions
Topic revision: r18 - 24 Jan 2013 - 22:21:14 - Main.JenniferDoubrava