# cPanel API 2 Functions - AddonDomain::addaddondomain Warning: The cPanel API 2 system is deprecated. We **strongly** recommend that you use [UAPI](/cpanel/introduction) instead of cPanel API 2. ## Description This function creates an addon domain, its subdomain, and its DNS zone. Warning: We **strongly** recommend that you use [UAPI](/cpanel/introduction/) instead of cPanel API 2. However, no equivalent UAPI function exists. Important: When you disable the [*Web Server* role](https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-use-server-profiles/#roles), the system **disables** this function. ## Examples WHM API (JSON) ```undefined syntaxhighlighter-pre https://hostname.example.com:2087/cpsess###########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=AddonDomain&cpanel_jsonapi_func=addaddondomain&dir=addondomain%2Fhome%2Fdir&newdomain=addondomain.com&subdomain=subdomain.example.com ``` Note: For more information, read our [Calls from the WHM API](/whm/use-whm-api-to-call-cpanel-api-and-uapi) documentation. LiveAPI PHP Class ```undefined syntaxhighlighter-pre $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add the "addondomain.com" addon domain. $add_addon = $cpanel->api2( 'AddonDomain', 'addaddondomain', array( 'dir' => 'addondomain/home/dir', 'newdomain' => 'addondomain.com', 'subdomain' => 'subdomain', ) ); ``` Note: For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). LiveAPI Perl Module ```undefined syntaxhighlighter-pre my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Add the "addondomain.com" addon domain. my $add_addon = $cpliveapi->api2( 'AddonDomain', 'addaddondomain', { 'dir' => 'addondomain/home/dir', 'newdomain' => 'addondomain.com', 'subdomain' => 'subdomain', } ); ``` Note: For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). cPanel Tag System (deprecated) Warnings: - cPanel tags are **deprecated**. We **strongly** recommend that you **only** use the [LiveAPI](/guides/guide-to-the-liveapi-system) system to call the cPanel APIs. Examples are **only** present in order to help developers move from the old cPanel tag system to our [LiveAPI](/guides/guide-to-the-liveapi-system). - cPanel API 2 calls that use cPanel tags vary in code syntax and in their output. - For more information, read our [Deprecated cPanel Tag Usage](/cpanel-api-2/cpanel-api-2-deprecate-cpanel-tag-usage/) documentation. Command Line ```undefined syntaxhighlighter-pre cpapi2 --user=username AddonDomain addaddondomain dir=addondomain%2Fhome%2Fdir newdomain=addondomain.com subdomain=subdomain ``` div Notes: - You **must** URI-encode values. - `username` represents your account-level username. - You **must** include the `--user=username` option. - For more information and additional output options, read our [Guide to cPanel API 2](/cpanel-api-2/) documentation or run the `cpapi2 --help` command. - If you run CloudLinux™, you **must** use the full path of the `cpapi2` command: ```undefined syntaxhighlighter-pre /usr/local/cpanel/bin/cpapi2 ``` br Output (JSON) ```undefined syntaxhighlighter-pre { "cpanelresult": { "apiversion": 2, "func": "addaddondomain", "data": [ ], "event": { "result": 1 }, "module": "AddonDomain" } } ``` Note: Use cPanel's *[API Shell](https://docs.cpanel.net/cpanel/advanced/api-shell-for-cpanel)* interface (*cPanel >> Home >> Advanced >> API Shell*) to directly test cPanel API calls. ## Parameters table thead tr th strong Parameter th strong Type th strong Description th strong Possible values th strong Example tbody tr td code create_temporary_domain td em Boolean td p strong Required p Whether to create a temporary domain. p This parameter is required if you do not provide the code newdomain or code subdomain parameter. p This parameter defaults to code 0 . td ul li code 1 — Create a temporary domain. li code 0 — Do strong not create a temporary domain. td code 1 tr td code dir td em string td p The path to the addon domain's home directory. p If you use the code create_temporary_domain parameter, the system ignores this parameter. It automatically generates the directory name. p If you do strong not span specify a value, this parameter defaults to the user's document root. td p A valid path relative to the cPanel user's home directory. ul li In WHM API calls, replace the forward slash ( code / ) with code %2F . li You strong cannot use the following directories as a document root: ul li The account's home directory itself ( code / ) li Directories outside of the account's home directory ( code ./ and code ../ ) li code .cpanel li code .trash li code etc li code mail li code ssl li code tmp li code logs li code .cphorde li code .spamassassin li code .htpasswds li code var li code cgi-bin li code .ssh li code perl5 td code addondomain/home/dir tr td code newdomain td em string td p strong Required p The addon domain name. td p A valid domain name that does strong not already exist. td code addondomain.com tr td code subdomain td em string td p strong Required p The addon domain's subdomain name. td p A valid subdomain name that does strong not already exist. For example, for the code subdomain.example.com subdomain, specify code subdomain . p span The cPanel user strong must own the subdomain's main domain. For example, for the code subdomain.example.com subdomain, the cPanel user strong must already own code example.com . td code subdomain tr td code ftp_is_optional td em Boolean td p Whether the system performs an FTP quota check on the cPanel account before it adds the addon domain. p This parameter defaults to code 0 . td ul li code 1 — Doesn't perform the FTP quota check. li code 0 — Performs the FTP quota check. td code 1 ## Returns table thead tr th strong Return th strong Type th strong Description th strong Possible values th strong Example tbody tr td code domain td em string td p The domain you created. p If you used the code create_temporary_domain parameter, the system will automatically generate a temporary domain name. td p A valid domain name. td code example.com tr td code reason td em string td p A message of success or a reason for failure. td ul li code addondomain.com was successfully parked on top of subdomain.example.com — This message indicates that the system successfully added the addon domain. li A string that describes the error. td code This is an error message. tr td code result td em Boolean td p Whether the function succeeded. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1