Modify failover

Description

Modify Failover for a specific record

 Parameters

Name Data Type Status Description
auth-id or sub-auth-id or sub-auth-user Integer Required Authentication parameter
auth-password String Required Authentication parameter
domain-name String Required Domain name containing the record
record-id String Required Record ID. You can see this ID with the method List records 
check_type Integer Required

Monitoring check types for this Failover:

  • 17 - Ping
  • 18 - Web
  • 8 - TCP
  • 9 - UDP
  • 10 - DNS
  • 15 - SMTP
down_event_handler Integer Required

Event handler if Main IP is down:

  • 0 - Monitoring only, email notification
  • 1 - Deactivate DNS record
  • 2 - Replace with working Backup IP 
 up_event_handler Integer Required

Event handler if Main IP is up:

  • 0 - Monitoring only, email notification
  • 1 - Activate the Main IP for the DNS record
  • 2 - Do not monitor if it is back up
main_ip String Required Main IP address which will be monitored
backup_ip_1 String Required First Backup IP address
backup_ip_2 String Optional Second Backup IP address
backup_ip_3 String Optional Third Backup IP address
backup_ip_4 String Optional Fourth Backup IP address
backup_ip_5 String Optional Fifth Backup IP address
monitoring_region String   Optional

Parameter required if you would like to specify a monitoring region or country. Possible values:

  • global - Global
  • eur - Europe
  • nam - North America
  • asi - Asia-Pacific
  • at - Austria
  • bg - Bulgaria
  • br - Brazil
  • ca - Canada
  • de - Germany
  • es - Spain
  • fi - Finland
  • hk - Hong Kong
  • hu - Hungary
  • il - Israel
  • in - India
  • it - Italy
  • jp - Japan
  • kr - South Korea
  • mx - Mexico
  • nl - Netherlands
  • pl - Poland
  • ro - Romania
  • ru - Russian Federation
  • sg - Singapore
  • tr - Turkey
  • tw - Taiwan
  • uk - United Kingdom
  • us - United States
  • za - South Africa

You can also specify a single node to make the checks. To achieve this, you need to list the available nodes by using this API method. Find the ID of the node you want to use and write it in the monitoring_region parameter. Example: monitoring_region=270.

Disclaimer: If the node is down the check status will be Unknown!

 
host String Optional Parameter required for Web and DNS check types. It must contain a hostname (FQDN).
ping_threshold Integer Optional

Used for Ping monitoring check type. Desired ping threshold. Default value is 15 - Ping (15% threshold). Possible values:

  • 15 - Ping (15% threshold)
  • 25 - Ping (25% threshold)
  • 50 - Ping (50% threshold)
  • 100 - Ping (100% threshold)
http_protocol String Optional

Used for Web monitoring check type. Desired Web protocol. Default value is HTTPS. Possible values:

  • http - HTTP
  • https - HTTPS
port Integer Optional Parameter required for Web, TCP and UDP check types. It must contain the port of the server. For TCP/UDP is a port on the Main IP.
path String Optional Parameter for Web check types. If there is a specific path on the FQDN, it must be filled in this parameter.
content String Optional Parameter required for Web check types. In case you require a specific output to be returned, it must be filled in this parameter (e.g. OK).
query_type String Optional Parameter required for DNS check type. It must contain the record type (e.g. A).
query_response String Optional  Parameter required for DNS check type. You must fill in the response of the DNS server for this specific record.
check_period Integer Optional

Time-frame between each monitoring check. Default value is 60 (1 minute). Possible values:

  • 60 - 1 minute
  • 120 - 2 minutes
  • 300 - 5 minutes
  • 600 - 10 minutes
  • 900 - 15 minutes
  • 1200 - 20 minutes
  • 1800 - 30 minutes
  • 3600 - 1 hour
notification_mail String Optional Parameter required for email notifications. If the parameter is not added, the current notifications settings will remain the same.
state Integer Optional Optional parameter for turning your monitoring on pause and vice versa.
deactivate_record Integer Optional

Optional parameter for when down_event_handler is set to 2 and both the Main IP and the backup IPs are down. The record will be deactivated and you will receive a notification about it.The default value is 0. Possible values:

  • 0 - The record will not be deactivated
  • 1 - The record will be deactivated
latency_limit Double Optional Only for Ping monitoring checks. If the latency of the check is above the limit, the check will be marked as DOWN.
timeout Integer Optional Only for Ping monitoring checks. Seconds to wait for a response. Must be between 1 and 5. Default value is 2.
http_request_type String Optional

Only for Web monitoring checks. The request type will be used for the check. The default value is GET. Possible values:

  • GET
  • HEAD
  • POST
  • PUT
  • DELETE
connection_security Integer Optional Used for SMTP monitoring check type. What security protocol the connection to be cheked for. Default value is 1 - None. Possible values:
  • 1 - None
  • 2 - STARTTLS
  • 3 - SSL/TLS

Return: Status and message.

Errors

When the authentication of API user is not correct, any API request will fail with the following status and statusDescription:

{"status":"Failed","statusDescription":"Invalid authentication, incorrect auth-id or auth-password."}

If you have entered an invalid or non-existent domain name, the following status will be returned:

{"status":"Failed","statusDescription":"Missing domain-name"}

If the entered Record ID is invalid, the following status will be returned:

{"status":"Failed","statusDescription":"Invalid record-id param."}

If the value for "check_type" is invalid, the following status will be returned:

{"status":"Failed","statusDescription":"This is invalid monitoring type."}

Note: These are example errors in JSON format, and these are not the only errors that can be displayed.

 Example

URL JSON: https://api.cloudns.net/dns/failover-modify.json
POST/GET: auth-id=0&auth-password=password&domain-name=cloudns.net&record-id=1234&check_type=18&host=cloudns.net&port=443&down_event_handler=2&up_event_handler=2&main_ip=127.0.0.1& backup_ip_1=192.168.1.2&check_period=60&notification_mail=example@domain.com, example2@domain.com&state=1
POST/GET: sub-auth-id=0&auth-password=password&domain-name=cloudns.net&record-id=1234&check_type=18&host=cloudns.net&port=443&down_event_handler=2&up_event_handler=2&main_ip=127.0.0.1& backup_ip_1=192.168.1.2&check_period=60&notification_mail=example@domain.com, example2@domain.com&state=1

URL XML: https://api.cloudns.net/dns/failover-modify.xml
POST/GET: auth-id=0&auth-password=password&domain-name=cloudns.net&record-id=1234&check_type=18&host=cloudns.net&port=443&down_event_handler=2&up_event_handler=2&main_ip=127.0.0.1& backup_ip_1=192.168.1.2&check_period=60&notification_mail=example@domain.com, example2@domain.com&state=1
POST/GET: sub-auth-id=0&auth-password=password&domain-name=cloudns.net&record-id=1234&check_type=18&host=cloudns.net&port=443&down_event_handler=2&up_event_handler=2&main_ip=127.0.0.1& backup_ip_1=192.168.1.2&check_period=60&notification_mail=example@domain.com, example2@domain.com&state=1

Last modified: 2025-03-11
Online - Live Chat
Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more