# cPanel API 2 Functions - ZoneEdit::add_zone_record 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 adds a new zone record. Warnings: * We **strongly** recommend that you use [UAPI](/cpanel/introduction/) instead of cPanel API 2. However, no equivalent UAPI function exists. * When you disable the [*DNS* 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) ``` https://hostname.example.com:2087/cpsess###########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=ZoneEdit&cpanel_jsonapi_func=add_zone_record&domain=example.com&name=sub&type=A&txtdata=v=nonicethings&cname=example.com&address=10.10.10.10&ttl=14400&class=IN&flatten=1&flatten_to=192.168.0.20 ``` 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 ``` $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add a type "A" zone record to "example.com" $add_zone_record = $cpanel->api2( 'ZoneEdit', 'add_zone_record', array( 'domain' => 'example.com', 'name' => 'sub', 'type' => 'A', 'address' => '10.10.10.10', 'ttl' => '14400', 'class' => 'IN', ) ); $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add a type "CNAME" zone record to "example.com" $add_zone_record = $cpanel->api2( 'ZoneEdit', 'add_zone_record', array( 'domain' => 'example.com', 'name' => 'sub', 'type' => 'CNAME', 'cname' => 'example.com', 'ttl' => '14400', 'class' => 'IN', ) ); $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add a type "TXT" Zone Record to "example.com" $add_zone_record = $cpanel->api2( 'ZoneEdit', 'add_zone_record', array( 'domain' => 'example.com', 'name' => 'sub', 'type' => 'TXT', 'txtdata' => 'v=nonicethings', 'ttl' => '14400', 'class' => 'IN', ) ); $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add a type "AAAA" zone record to "example.com" $add_zone_record = $cpanel->api2( 'ZoneEdit', 'add_zone_record', array( 'domain' => 'example.com', 'name' => 'genesis', 'type' => 'AAAA', 'address' => 'abac:abab:acab:abac:abab:acab:abac:ab11:', 'ttl' => '14400', 'class' => 'IN', ) ); $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add a type "SRV" Zone Record to "example.com" $add_zone_record = $cpanel->api2( 'ZoneEdit', 'add_zone_record', array( 'domain' => 'example.com', 'name' => 'autocorrect', 'type' => 'SRV', 'txtdata' => 'v=nonicethings', 'ttl' => '14400', 'class' => 'IN', ) ); $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Add a type "CAA" Zone Record to "example.com" $add_zone_record = $cpanel->api2( 'ZoneEdit', 'add_zone_record', array( 'domain' => 'example.com', 'name' => 'autocorrect', 'type' => 'CAA', 'flag' => '0', 'tag' => 'issue', 'value' => 'totallyrealca.tld', 'ttl' => '14400', 'class' => 'IN', ) ); ``` 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 ``` my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Add a type "A" Zone Record to "example.com" my $add_zone_record = $cpliveapi->api2( 'ZoneEdit', 'add_zone_record', { 'domain' => 'example.com', 'name' => 'sub', 'type' => 'A', 'address' => '10.10.10.10', 'ttl' => '14400', 'class' => 'IN', } ); # Add a type "AAAA" Zone Record to "example.com" my $add_zone_record = $cpliveapi->api2( 'ZoneEdit', 'add_zone_record', { 'domain' => 'example.com', 'name' => 'genesis', 'type' => 'AAAA', 'address' => 'abac:abab:acab:abac:abab:acab:abac:ab11', 'ttl' => '14400', 'class' => 'IN', } ); my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Add a type "CNAME Zone Record to "example.com" my $add_zone_record = $cpliveapi->api2( 'ZoneEdit', 'add_zone_record', { 'domain' => 'example.com', 'name' => 'sub', 'type' => 'CNAME', 'cname' => 'example.com', 'ttl' => '14400', 'class' => 'IN', } ); my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Add a type "TXT" Zone Record to "example.com" my $add_zone_record = $cpliveapi->api2( 'ZoneEdit', 'add_zone_record', { 'domain' => 'example.com', 'name' => 'sub', 'type' => 'TXT', 'txtdata' => 'v=nonicethings', 'ttl' => '14400', 'class' => 'IN', } ); my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Add a type "SRV" Zone Record to "example.com" my $add_zone_record = $cpliveapi->api2( 'ZoneEdit', 'add_zone_record', { 'domain' => 'example.com', 'name' => 'autodiscover', 'type' => 'SRV', 'txtdata' => 'v=nonicethings', 'ttl' => '14400', 'class' => 'IN', } ); my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Add a type "CAA" Zone Record to "example.com" my $add_zone_record = $cpliveapi->api2( 'ZoneEdit', 'add_zone_record', { 'domain' => 'example.com', 'name' => 'autodiscover', 'type' => 'CAA', 'flag' => '0', 'tag' => 'issue' 'value' => 'totallyrealca.tld' 'ttl' => '14400', 'class' => 'IN', } ); ``` Note: For more information, read our [Guide to the LiveAPI System](/guides/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 ``` cpapi2 --user=username ZoneEdit add_zone_record domain=example.com name=sub type=A txtdata=v=nonicethings cname=example.com address=10.10.10.10 ttl=14400 class=IN flatten=1 flatten_to=192.168.0.20 ``` 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: ``` /usr/local/cpanel/bin/cpapi2 ``` br Output (JSON) ``` { "cpanelresult": { "apiversion": 2, "func": "add_zone_record", "data": [ { "result": { "newserial": 2014101603, "statusmsg": "Bind reloading on hostname using rndc zone: [example.com]\n", "status": 1 } } ], "event": { "result": 1 }, "module": "ZoneEdit" } } ``` 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 Parameters th strong Type th strong Description th strong Possible values th strong Example tbody tr td code domain td em string td p strong Required p The record's domain. td A valid domain name. td code example.com tr td code name td em string td p strong Required p The record's name, which maps to the subdomain. td p A valid string. td code sub tr td code type td em string td p strong Required p The record type. td ul li code A li code CAA li code CNAME li code TXT li code AAAA li code SRV div Note: This function can only add AAAA, CAA, and SRV record types if the cPanel account's hosting provider enables the Zone Editor (AAAA, CAA, SRV, TXT) feature in WHM's [Feature Manager](https://docs.cpanel.net/whm/packages/feature-manager/) interface (WHM >> Home >> Packages >> Feature Manager). td code A tr td code txtdata td em string td p The record's text data. p div Note: p This parameter is strong required if you use code TXT as the code type parameter's value. br td A valid string. td code v=nonicethings tr td code target td em string td The service's target host. p div Notes: p ul li This parameter is strong required if you use code SRV as the code type parameter's value. li span You strong cannot span point an SRV record at a CNAME record. br td span A valid hostname. td code subdomain.example.com tr td code weight td em integer td p span A relative weight. The system uses this value to rank entries with the same code priority span value. p div Note: p p This parameter is strong required if you use code SRV as the code type parameter's value. br td span A positive integer that represents the target host's weight against other hosts with the same code priority span value. td code 1 tr td code port td em integer td p span The target host's port. p div Note: p p This parameter is strong required if you use code SRV as the code type parameter's value. br td p A positive integer that represents a port number. div Note: For a complete list of ports, read our [How to Configure Your Firewall for cPanel Services](https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-configure-your-firewall-for-cpanel-services/) documentation. td code 443 tr td code priority td em integer td The service record's a priority value . p div Note: p This parameter is strong required if you use code SRV as the code type parameter's value. td A positive integer span that represents the target host's priority order . td code 1 tr td code cname td em string td p The record's canonical name. p div Note: p p This parameter is strong required if you use code CNAME as the code type parameter's value. br td A valid canonical name. td code example.com tr td code address td em string td p The IP address to map to the record. p div Note: p p This parameter is strong required if you use code A or code AAAA as the code type parameter's value. br td span A valid IPv4 or IPv6 address. td code 10.10.10.10 tr td code flag td em integer td p Whether the CA will issue an SSL certificate. p div Note: p ul li This parameter is strong required if you use code CAA as the code type parameter's value. li span For more information about CAA record flags, read the a RFC 6844 span documentation. li We added this parameter in cPanel & WHM version 68. br td ul li code 0 — Non-critical. If the CAA Resource Record contains unknown property tags, the CA will issue an SSL certificate. li code 1 — Critical. If the CAA Resource Record contains unknown property tags, the CA will strong not issue an SSL certificate. td code 0 tr td p code tag td em string td p The CAA record's property type. p div Note: p ul li This parameter is strong required if you use code CAA as the code type parameter's value. li We added this parameter in cPanel & WHM version 68. br td ul li code issue — Authorize a CA to issue a certificate for the domain. li code issuewild — Authorize a CA to issue a wildcard certificate for the domain. li p code iodef em — Specify a URL to which a CA may report policy violations. td code issue tr td code value td em string td p The CA's domain or URL. p div Notes: p ul li This parameter is strong required if you use code CAA as the code type parameter's value. li Enter a URL that a CA can use to report issues as this parameter's value if you use code iodef as the code tag parameter's value. li We added this parameter in cPanel & WHM version 66. br td p The CA's domain or URL. td code totallyrealca.tld tr td code ttl td em integer td p The record's time to live (TTL). p This value defaults to code 14400 . td A valid positive integer that represents the record's TTL, in seconds. td code 14400 tr td code class td em string td p The record's class. p This value defaults to code IN . td code IN td code IN tr td code flatten td em Boolean td p span Whether to resolve the specified CNAME value with the record's IP address. p span You strong must use the code flatten_to span span parameter with this parameter, or the system will attempt to resolve the CNAME span automatically . p div Notes: p ul li strong Only use this parameter for CNAME records. li strong Only use this parameter when you alter the zone's code root record. br td ul li code 1 — Flattened. li code 0 — strong Not flattened (call will fail). td code 1 tr td code flatten_to td em string td p span The IP address to which the specified CNAME will resolve. p span You strong must span use the code flatten parameter with this parameter. p div Notes: p ul li strong Only use this parameter for CNAME records. li strong Only use this parameter when you alter the zone's the code root record. br td A valid IPv4 or IPv6 address. td code 192.168.0.20 ## Returns table thead tr th strong strong Return th strong Type th strong Description th strong Possible values th strong Example tbody tr td code result td em hash td A hash of the function call's results. td This hash includes the code newserial , code statusmessage , and code status returns. td tr td p code newserial td em integer td p The new serial number of the zone file. p This function returns this value in the code result hash. td A positive integer. td code 2014101603 tr td p code statusmsg td em string td p A status message from the DNS server. p This function returns this value in the code result hash. td A valid string. td code Bind reloading on hostname using rndc zone: [example.com]\n tr td p code status td em string td p Whether the function succeeded. p This function returns this value in the code result hash. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1 tr td code reason td em string td p A reason for failure. p div Note: p p This function only returns a code reason value if it failed. br td p 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