WHM API 1 Functions - createacct

This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.

Examples

JSON API

https://hostname.example.com:2087/cpsess##########/json-api/createacct?api.version=1&username=username&domain=example.com&bwlimit=unlimited&cgi=1&contactemail=username@example.com&cpmod=paper_lantern&customip=192.0.2.0&dkim=1&featurelist=feature_list&forcedns=0&frontpage=0&gid=123456789&hasshell=1&hasuseregns=1&homedir=/home/user&ip=n&language=en&owner=root&mailbox_format=mdbox&max_defer_fail_percentage=unlimited&max_email_per_hour=unlimited&max_emailacct_quota=1024&maxaddon=unlimited&maxftp=unlimited&maxlst=unlimited&maxpark=unlimited&maxpop=unlimited&maxsql=unlimited&maxsub=unlimited&mxcheck=auto&owner=root&password=12345luggage&pkgname=my_new_package&plan=default&quota=500&reseller=0&savepkg=1&spamassassin=1&spf=1&spambox=y&uid=123456789&useregns=0

XML API

https://hostname.example.com:2087/cpsess##########/xml-api/createacct?api.version=1&username=username&domain=example.com&bwlimit=unlimited&cgi=1&contactemail=username@example.com&cpmod=paper_lantern&customip=192.0.2.0&dkim=1&featurelist=feature_list&forcedns=0&frontpage=0&gid=123456789&hasshell=1&hasuseregns=1&homedir=/home/user&ip=n&language=en&owner=root&mailbox_format=mdbox&max_defer_fail_percentage=unlimited&max_email_per_hour=unlimited&max_emailacct_quota=1024&maxaddon=unlimited&maxftp=unlimited&maxlst=unlimited&maxpark=unlimited&maxpop=unlimited&maxsql=unlimited&maxsub=unlimited&mxcheck=auto&owner=root&password=12345luggage&pkgname=my_new_package&plan=default&quota=500&reseller=0&savepkg=1&spamassassin=1&spf=1&spambox=y&uid=123456789&useregns=0username=username&domain=example.com&plan=default&featurelist=feature_list&quota=0&password=12345luggage&ip=n&cgi=1&hasshell=1&contactemail=user%40seconddomain.com&cpmod=paper_lantern&maxftp=5&maxsql=5&maxpop=10&maxlst=5&maxsub=1&maxpark=1&maxaddon=1&bwlimit=500&language=en&useregns=1&hasuseregns=1&reseller=0&forcedns=1&&mailbox_format=mdbox&mxcheck=local&max_email_per_hour=500&max_defer_fail_percentage=80&owner=root

Command Line

whmapi1 createacct username=username domain=example.com bwlimit=unlimited cgi=1 contactemail=username@example.com cpmod=paper_lantern customip=192.0.2.0 dkim=1 featurelist=feature_list forcedns=0 frontpage=0 gid=123456789 hasshell=1 hasuseregns=1 homedir=/home/user ip=n language=en owner=root mailbox_format=mdbox max_defer_fail_percentage=unlimited max_email_per_hour=unlimited max_emailacct_quota=1024 maxaddon=unlimited maxftp=unlimited maxlst=unlimited maxpark=unlimited maxpop=unlimited maxsql=unlimited maxsub=unlimited mxcheck=auto owner=root password=12345luggage pkgname=my_new_package plan=default quota=500 reseller=0 savepkg=1 spamassassin=1 spf=1 spambox=y uid=123456789 useregns=0

Notes:

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

Output (JSON)

{
   "data":{
      "nameserver2":"ns2.example.com",
      "nameservera4":null,
      "nameserverentry3":null,
      "nameservera":null,
      "nameserver3":"",
      "nameserver":"ns1.example.com",
      "nameserver4":"",
      "nameservera3":null,
      "nameserverentry2":null,
      "nameserverentry":null,
      "nameserverentry4":null,
      "nameservera2":null,
      "ip":"192.0.2.0",
      "package":"default"
   },
   "metadata":{
      "result":1,
      "output":{
         "raw":"Checking input data...Forced Dns is enabled.\nValidating Username......Done\nValidating IP......Done\nValidating Contact Email......Done\n...Done\nValidating system setup......Done\nChecking for database conflicts......Done\nWWWAcct 12.6.0 (c) 2019 cPanel, Inc....\n\n+===================================+\n| New Account Info                  |\n+===================================+\n| Domain: example.com\n| Ip: 192.0.2.0 (n)\n| HasCgi: y\n| UserName: username\n| PassWord: 12345luggage\n| CpanelMod: paper_lantern\n| HomeRoot: /home\n| Quota: 0 bytes\n| NameServer1: ns1.dev.cpanel.net\n| NameServer2: ns2.dev.cpanel.net\n| NameServer3: \n| NameServer4: \n| Contact Email: user@seconddomain.com\n| Package: default\n| Feature List: default\n| Language: en\n+===================================+\n...Done\nCustom Account Data Provided: no\nRunning pre creation script (/usr/local/cpanel/scripts/prewwwacct)......Done\nAdding User...Adding Shell Access (y)\nSuccess...Done\nAdding Entries to userdata......Done\nSetting up Mail & Local Domains...localdomains...valiases ...vdomainaliases ...vfilters ......Done\nConfiguring DNS...Zone example.com has been successfully added\n...Done\nVerifying MX Records and Setting up Databases...Reconfiguring Mail Routing:\nLOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.:\n This configuration has been manually selected.\n\n...Done\nSetting up Service Subdomains......Done\nBind reloading on ashley using rndc zone: [example.com]\nUpdating Authentication Databases......Done\nSetting passwords......Done\nUpdating the userdata cache......Done\nSetting up Horde database in the background.......Done\nCreating bandwidth datastore......Done\nUpdating the dedicated IP address usage cache......Done\nGenerating and installing DKIM keys......Done\nEnabling Apache SpamAssassin™......Done\nEnabling Apache SpamAssassin™ Spam Box......Done\nSending Account Information......Done\nRunning post creation scripts (/usr/local/cpanel/scripts/legacypostwwwacct, /usr/local/cpanel/scripts/postwwwacct, /usr/local/cpanel/scripts/postwwwacctuser)......Done\nwwwacct creation finished\nSetting up Domain Pointers......Done\nSetting Reseller Privs......Done\nAccount Creation Complete!!!...Account Creation Ok...Done\n"
      },
      "command":"createacct",
      "reason":"Account Creation Ok",
      "version":1
   }
}

Output (XML)

	<data>
		<ip>10.0.0.1</ip>
		<nameserver>ns1.example.com</nameserver>
		<nameserver2>ns2.example.com</nameserver2>
		<nameserver3></nameserver3>
		<nameserver4></nameserver4>
		<nameservera />
		<nameservera2 />
		<nameservera3 />
		<nameservera4 />
		<nameserverentry />
		<nameserverentry2 />
		<nameserverentry3 />
		<nameserverentry4 />
		<package>default</package>
	</data>
	<metadata>
		<command>createacct</command>
		<output>
			<raw>
				Checking input data...Dns Zone check is enabled.
				Validating Username......Done
				Validating IP......Done
				Validating Contact Email......Done
				...Done
				Validating system setup......Done
				Checking for database conflicts......Done
				WWWAcct 12.6.0 (c) 2018 cPanel, Inc....
				
				+===================================+
				| New Account Info                  |
				+===================================+
				| Domain: example.com
				| Ip: 192.0.2.0 (n)
				| HasCgi: y
				| UserName: username
				| PassWord: 12345luggage
				| CpanelMod: paper_lantern
				| HomeRoot: /home
				| Quota: unlimited
				| NameServer1: ns1.example.com
				| NameServer2: ns2.example.com
				| NameServer3:
				| NameServer4:
				| Contact Email: user@seconddomain.com
				| Package: default
				| Feature List: default
				| Language: en
				+===================================+
				...Done
				Custom Account Data Provided: no
				Running pre creation script (/usr/local/cpanel/scripts/prewwwacct)......Done
				Adding User...Removing Shell Access (n)
				Success...Done
				Adding Entries to userdata......Done
				Setting up Mail &amp; Local Domains...localdomains...valiases ...vdomainaliases ...vfilters ......Done
				Configuring DNS...Zone example.com has been successfully added
				...Done
				Verifying MX Records and Setting up Databases...Reconfiguring Mail Routing:
				LOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.:
				 This configuration has been manually selected.
				...Done
				Setting up Service Subdomains......Done
				Updating Authentication Databases......Done
				Setting passwords......Done
				Updating the userdata cache......Done
				Setting up Horde database in the background.......Done
				Creating bandwidth datastore......Done
				Updating user’s Apache jail filesystem......Done
				Updating the dedicated IP address usage cache......Done
				Generating and installing DKIM keys......Done
				Enabling Apache SpamAssassin™......Done
				Enabling Apache SpamAssassin™ Spam Box......Done
				Sending Account Information......Done
				Running post creation scripts (/usr/local/cpanel/scripts/legacypostwwwacct, /usr/local/cpanel/scripts/postwwwacct, /usr/local/cpanel/scripts/postwwwacctuser)......Done
				wwwacct creation finished
				Setting up Domain Pointers......Done
				Setting Reseller Privs......Done
				Account Creation Complete!!!...Account Creation Ok...Done
			</raw>
		</output>
		<reason>Account Creation Ok</reason>
		<result>1</result>
		<version>1</version>
	</metadata>

Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

Parameter Type Description Possible values Example

username

string

Required

The new account's username.

A valid cPanel username. cPanel usernames must adhere to the following criteria:

The first eight characters of a username must be unique.
A username cannot begin with a number or the test string.

A username's character limits depend on the cPanel & WHM version of the server:

Version	Characters
11.38 and earlier	Eight characters or less.
11.40 through 11.42	Eight characters or less with database prefixing. 16 characters or less without database prefixing.
11.44 and later	16 characters or less.

Note:

Use the Cpanel::Validate::Username Perl module to validate usernames before you call this function. For more information, read the /usr/local/cpanel/Cpanel/Validate/Username.pod file.
The system will automatically convert this value to all lowercase letters.
In cPanel & WHM version 11.56 and later, MySQL's unique character limitations do not exist on servers that use MariaDB.

username

domain

string

Required

The account's main domain.

A valid domain name.

example.com

bwlimit

string

The account's maximum bandwidth use.

This parameter defaults to unlimited.

A positive integer between one and 999,999 that represents the maximum bandwidth use, in Megabytes (MB).
0, unlimited, or null — The account possesses unlimited bandwidth.

unlimited

cgi

Boolean

Whether the account has Common Gateway Interface (CGI) access enabled.

This parameter defaults to 1.

1 — Enabled.
0 — Disabled.

1

contactemail

string

The account's contact email address.

This parameter defaults to an empty string.

A valid email address.

username@example.com

cpmod

string

The account's cPanel theme.

This parameter defaults to the server's default cPanel theme.

paper_lantern
A valid theme on the server.

paper_lantern

customip

string

The account's IP address.

If you do not specify this parameter, the system will determine the account's IP address.

A valid IP address.

192.0.2.0

dkim

Boolean

Whether DomainKeys Identified Mail (DKIM) is enabled for the account.

This parameter defaults to the Enable DKIM on domains for newly created accounts setting's value in WHM's Tweak Settings interface (WHM >> Home >> System Configuration >> Tweak Settings).

1 — Enabled.
0 — Disabled.

1

featurelist

string

The account's assigned feature list.

If you do not use this parameter, the function assigns the default feature list to the account.

A valid feature list name on the server.

feature_list

forcedns

Boolean

Whether to overwrite an existing DNS zone with the new account's information. The system performs this action if a matching DNS zone currently exists.

This parameter defaults to 0.

1 — Overwrite.
0 — Do not overwrite.

0

frontpage

Boolean

Whether the account has Microsoft^® FrontPage Extensions enabled.

Note:

cPanel & WHM ignores all FrontPage settings and parameters if either statement is true:

The server runs cPanel & WHM version 11.44 and FrontPage Extensions are not installed.
The server runs cPanel & WHM version 11.46 or later.

This parameter defaults to undef.

1 — Enabled.
0 — Disabled.

0

gid

string

The account's group ID.

Note:

To use this parameter, the function's caller must authenticate as the root user.

If you do not specify this parameter, the system generates a group ID.

A positive integer that is not currently associated with disk usage and does not exist on the server.

123456789

hasshell

Boolean

Whether the account has shell (SSH) access enabled.

This parameter defaults to 1.

1 — Enabled.
0 — Disabled.

1

hasuseregns

Boolean

A legacy parameter.

Important:

Only include this parameter if you set a useregns value of 1.

This parameter defaults to 0.

1

homedir

string

The account's home directory.

Note:

To use this parameter, the function's caller must authenticate as the root user.
We introduced this parameter in cPanel & WHM version 11.34.

If you do not specify a value, the system uses the /home/user directory, where user is the account's username.

The absolute path to a location on the server.

/home/user

ip

string

Whether the account has a dedicated IP address.

This parameter defaults to n.

y — The account possesses a dedicated IP address.
n — The account does not possess a dedicated IP address.

n

language

string

The account's default locale.

This parameter defaults to the server's default locale.

A valid ISO 639-1 code.

Note:

This value is case-sensitive.
For region-specific locales, use the ISO 639-1 code, an underscore (_), and the ISO 3166-1 code.

en

owner

string

The name of the account owner.

This parameter defaults to the authenticated user.

root
A valid reseller account username on the server.

root

mailbox_format

string

A mailbox format to use, if you do not wish to use the system's default mailbox format.

Note:

Use this parameter when you transfer between servers with different mailbox formats.
We introduced this parameter in cPanel & WHM version 62.

This parameter defaults to equal the The mailbox storage format for new accounts setting in the Mail section of WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

mdbox
maildir

mdbox

max_defer_fail_percentage

string

The percentage of failed or deferred email messages that the account can send per hour. If the account exceeds this value its outgoing mail is rate-limited.

This parameter defaults to 0 (unlimited).

A positive integer.
0 or unlimited — The account can send an unlimited number of failed or deferred messages.

unlimited

max_email_per_hour

string

The maximum number of emails that the account can send in one hour.

This parameter defaults to unlimited.

A positive integer.
0 or unlimited — The account can send an unlimited number of emails.

unlimited

max_emailacct_quota

string

The maximum size that the account can define when it creates an email account.

Important:

This value applies to each email account, not each cPanel account.
If you define this parameter it overwrites the hosting plan's defined value for the account.
We recommend that you allow the account's plan to determine this value.

Note:

We introduced this parameter in cPanel & WHM version 70.

This parameter defaults to 1024.

A positive integer between one and 4,294,967,296, in MB.
unlimited — The account possesses an unlimited quota.

1024

maxaddon

string

The account's maximum number of addon domains.

This parameter defaults to 0.

An integer between zero and 999,999.
unlimited or null — The account possesses unlimited addon domains.

unlimited

maxftp

string

The account's maximum number of FTP accounts.

This parameter defaults to unlimited.

A positive integer between one and 999,999.
0, unlimited, or null — The account possesses unlimited FTP accounts.

unlimited

maxlst

string

The account's maximum number of mailing lists.

This parameter defaults to unlimited.

A positive integer between one and 999,999.
0, unlimited, or null — The account possesses unlimited mailing lists.

unlimited

maxpark

string

The account's maximum number of parked domains (aliases).

This parameter defaults to 0.

An integer between zero and 999,999.
unlimited or null — The account possesses unlimited parked domains.

unlimited

maxpop

string

The account's maximum number of email accounts.

This parameter defaults to unlimited.

A positive integer between one and 999,999.
0, unlimited, or null — The account possesses unlimited email accounts.

unlimited

maxsql

string

The account's maximum number of each available type of SQL database.

For example, this parameter has a 5 value and the system administrator allows MySQL^® and PostgreSQL^® databases. Users can create up to five MySQL databases and up to five PostgreSQL databases.

This parameter defaults to unlimited.

A positive integer between one and 999,999.
0, unlimited, or null — The account possesses unlimited databases.

unlimited

maxsub

string

The account's maximum number of subdomains.

This parameter defaults to unlimited.

An integer between zero and 999,999.
unlimited or null — The account possesses unlimited subdomains.

unlimited

mxcheck

string

The account's main mail exchanger's type.

Note:

The function does not configure the primary MX entry to point to the appropriate exchanger. You must perform this function separately.

This parameter defaults to local.

local
secondary
remote
auto

auto

owner

string

The name of the account owner.

This parameter defaults to the authenticated user.

root
A valid reseller account username on the server.

root

password

string

The account's password.

If you don't specify this value, the system generates a secure password.

A secure password.

12345luggage

pkgname

string

A new plan name. Use this parameter to save unique account settings as a new plan.

Note:

If you do not use this parameter but specify 1 for the savepkg value, the system will generate a plan name.
If you do not use this parameter and specify 0 or do not use the savepkg parameter, the function does not save a new plan.

If you do not use this parameter, the function will not save the new account settings.

A valid plan name.

my_new_package

plan

string

The account's hosting plan (package).

Important:

If you provide this value, do not use the optional quota-related parameters below. Instead, we recommend that you allow the account's plan to determine these values.

This parameter defaults to the default plan.

A hosting plan name on the server.

default

quota

integer

The account's disk space quota.

This parameter defaults to 0 (unlimited).

A positive integer between one and 999,999 representing the total disk space the account can use, in MB.
0 — The account's disk space is unlimited.

500

reseller

Boolean

Whether to grant reseller privileges to the account.

This parameter defaults to 0.

1 — Grant reseller privileges.
0 — Do not grant reseller privileges.

0

savepkg

Boolean

Whether to save the account's settings as a new plan.

This parameter defaults to 0.

1 — Save.
0 — Do not save.

1

spamassassin

Boolean

Whether the account has Apache SpamAssassin™ enabled.

Note:

We introduced this parameter in cPanel & WHM version 70.

This parameter defaults to 1.

1 — Enabled.
0 — Disabled.

1

spf

Boolean

Whether Sender Policy Framework (SPF) is enabled for the account.

This parameter defaults to the Enable SPF on domains for newly created accounts setting's value in WHM's Tweak Settings interface (WHM >> Home >> System Configuration >> Tweak Settings).

1 — Enabled.
0 — Disabled.

1

spambox

string

Whether to enable spam box filtering for the account.

Note:

You must enable Apache SpamAssassin™ to use the Spam Box feature.
We introduced this parameter in cPanel & WHM version 80.

This parameter defaults to y (enabled).

y — Enable spam box filtering.
n — Disable spam box filtering.

y

uid

string

The account's user ID.

Note:

To use this parameter, the function's caller must authenticate as the root user.

If you do not specify this parameter, the system generates a user ID.

A positive integer that is not currently associated with disk usage and does not exist on the server.

123456789

useregns

Boolean

Whether to use registered nameservers for the domain.

Important:

If you set this parameter to 1, you must also include the hasuseregns parameter with a value of 1.

This parameter defaults to 0.

1 — Use registered nameservers.
0 — Use the server's default nameservers.

0

Returns

Return	Type	Description	Possible values	Example
`ip`	string	The account's primary nameserver's IP address.	A valid IP address.	192.0.2.0
`nameserver`	string	The account's primary nameserver.	A valid nameserver.	`ns1.example.com`
`nameserver*`	string	The account's additional nameservers. The `*` character is a number indicating the nameserver priority number.	A valid nameserver.	`ns2.example.com`
`nameservera*`	string	The account's nameservers' IP addresses. The `*` character is a number indicating the nameserver priority order.	A valid IP address.	192.0.2.0
`nameserverentry*`	string	The nameserver's DNS name. The `*` character is a number indicating the nameserver priority number.	A valid DNS entry name.	`dnsentry1`
`package`	string	The account's plan (package) name.	A valid package name.	`default`
`output`	hash	A hash that contains the function's output information.	This hash contains the `raw` return.
`raw`	string	The raw output from the account creation operation. The function returns this value in the `output` hash.	One or more messages that may contain HTML code.	Click to view... Checking input data...Forced Dns is enabled.\nValidating Username......Done\nValidating IP......Done\nValidating Contact Email......Done\n...Done\nValidating system setup......Done\nChecking for database conflicts......Done\nWWWAcct 12.6.0 (c) 2019 cPanel, Inc....\n\n+===================================+\n\| New Account Info \|\n+===================================+\n\| Domain: example.com\n\| Ip: 192.0.2.0 (n)\n\| HasCgi: y\n\| UserName: username\n\| PassWord: 12345luggage\n\| CpanelMod: paper_lantern\n\| HomeRoot: /home\n\| Quota: 0 bytes\n\| NameServer1: ns1.dev.cpanel.net\n\| NameServer2: ns2.dev.cpanel.net\n\| NameServer3: \n\| NameServer4: \n\| Contact Email: user@seconddomain.com\n\| Package: default\n\| Feature List: default\n\| Language: en\n+===================================+\n...Done\nCustom Account Data Provided: no\nRunning pre creation script (/usr/local/cpanel/scripts/prewwwacct)......Done\nAdding User...Adding Shell Access (y)\nSuccess...Done\nAdding Entries to userdata......Done\nSetting up Mail & Local Domains...localdomains...valiases ...vdomainaliases ...vfilters ......Done\nConfiguring DNS...Zone example.com has been successfully added\n...Done\nVerifying MX Records and Setting up Databases...Reconfiguring Mail Routing:\nLOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.:\n This configuration has been manually selected.\n\n...Done\nSetting up Service Subdomains......Done\nBind reloading on ashley using rndc zone: [example.com]\nUpdating Authentication Databases......Done\nSetting passwords......Done\nUpdating the userdata cache......Done\nSetting up Horde database in the background.......Done\nCreating bandwidth datastore......Done\nUpdating the dedicated IP address usage cache......Done\nGenerating and installing DKIM keys......Done\nEnabling Apache SpamAssassin™......Done\nEnabling Apache SpamAssassin™ Spam Box......Done\nSending Account Information......Done\nRunning post creation scripts (/usr/local/cpanel/scripts/legacypostwwwacct, /usr/local/cpanel/scripts/postwwwacct, /usr/local/cpanel/scripts/postwwwacctuser)......Done\nwwwacct creation finished\nSetting up Domain Pointers......Done\nSetting Reseller Privs......Done\nAccount Creation Complete!!!...Account Creation Ok...Done\n

Function information

API Version:

WHM API 1

Available in:

WHM 11.32+

Methods:

GET, POST

Required Parameters:

username, domain

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

About WHM API 1

WHM API 1 performs functions and accesses data in WHM.

Notes:

Some functions and parameters may require that you authenticate as the root user.
You must use the appropriate WHM ports (2086 or 2087) to call WHM API functions.

Find a function

Related functions

Page:

WHM API 0 Functions - setresellermainip — This function assigns a main IP address to a reseller's account.
Page:

WHM API 0 Functions - setresellernameservers — This function assigns nameservers to a reseller's account.
Page:

WHM API 1 Sections - Accounts — Account functions allow you to manage cPanel accounts, WHM accounts, and their settings.
Page:

WHM API 1 Functions - accountsummary — This function retrieves a summary of a user's account.
Page:

WHM API 1 Functions - domainuserdata — This function retrieves domain data.

Child pages

WHM API 1 Functions - createacct

Description

Examples

Parameters

Returns

Function information

About WHM API 1

Find a function

Related functions