Skip to main content

Subscription API guide

Version 1.9.
If you are viewing the Subscription API guide as a PDF file, you can always check for the latest version here: https://docs.safedns.com/books/subscription-api/page/subscription-api-guide


Introduction

SafeDNS Subscription API is designed to give you an easy and fast way to automatically create new user accounts in the SafeDNS cloud service from the internal systems of an ISP or a developer. Also, you can use this API to manage the base settings of a user like their email, password, and filtering policy.


Description

API developer (provider) is provided with a public key, that is used for authentication. All requests are made through HTTPS via GET requests. Each request must contain a public key with the name of a parameter key.

The public key is provided with a separate email and should not be available in open access.

API address: https://www.safedns.com/provider_api/

API call example: curl "https://www.safedns.com/provider_api/METHOD_NAME?key=PUBLIC_KEY&mandatory_parameter=VALUE&optional_parameter=VALUE"


Table of available methods

# Value Description
1 subscribe Registers a User in the system with the provided credentials and sets the expiration date of the account to +1 year from the current date.
2 subscribe_plans Lists Reseller’s available billing plans.
3 activate Sets the status of a User to "Active".
4 deactivate Sets the status of a User to "Inactive".
5 update_email Updates User’s email.
6 update_password Updates User’s password.
7 prolongate Enables and changes a paid plan for an existing User.
8 unsubscribe Switches a User to the FREE plan with the limited filtering functionality.
9 subscription_info Gets the expiration date of the account.
10 profiles Gets a list of existing filtering policies.
11 create_profile Creates a filtering policy.
12 update_profile Changes the settings of the User's filtering policy and its blockpage.
13 delete_profile Deletes one of the existing filtering policies.
14 add_ip Adds one or more IP addresses to a User.
15 clear_ip Deletes all IP addresses of a User that uses the selected filtering policy.
16 list_ip Gets a list of all User’s IP addresses.
17 remove_ip Removes specified IP address from User.
18 add_vpn Creates a VPN Configuration File for the policy and returns OpenVPN policy.
19 clear_vpn_for_profile Deletes all VPN Configuration Files that use specified filtering policy.
20

clear_vpn_for_user

Deletes all VPN Configuration Files of specified User.
21 get_vpn_list Gets a list of User’s VPN Configuration Files.
22

remove_vpn

Removes User’s VPN Configuration File.
23 update_ip Creates a ddclient record and/or updates the IP address for it.
24 update_nat Updates a filtering policy of the specified NAT DNS address.
25 get_activity Gets User’s stats for a certain date.
26 get_activity_report Gets the User's activity report for a certain time range.
27 get_popular_report Gets the User's popular requests report for a certain time range.
28 get_category_report Gets User's categories report for a certain time range.
29 send_monthly_stat Sends Monthly Stats report to User’s email.
30 get_daily_stat Gets a link to the User's Daily Stats report.
31 update_subscription Changes the billing plan and/or expiration date of Users.
32 forgot_password Sends a password reset email to a User.
33 get_blockpages Gets the list of existing BlockPages.
34 create_blockpage Creates a new blockpage.
35 update_blockpage Updates parameters of the blockpage.
36 user_list Lists all created user accounts.

Table of values for the plan parameter

Value Description
PREMIUM Safe@Home
BUSINESS-5 Safe@Office 5
BUSINESS-10 Safe@Office 10
BUSINESS-25 Safe@Office 25
BUSINESS-50 Safe@Office 50
BUSINESS-75 Safe@Office 75
BUSINESS-100 Safe@Office 100
NONPROFIT Nonprofit
EDU  Education
WIFI-1 HotSpot Edition 1
WIFI-2 HotSpot Edition 2
WIFI-3 HotSpot Edition 3
WIFI-4 HotSpot Edition 4
WIFI-5 HotSpot Edition 5
WIFI-10 HotSpot Edition 10
WIFI HotSpot Advanced Edition
ENTERPRISE Enterprise
HOME Safe Home
FAMILY Safe Family
BASIC Basic
PRO Pro
PRO-PLUS Pro Plus
CUSTOM-WIFI Wi-Fi
CUSTOM-EDU&NONPROFIT Education & Nonprofit

Methods & parameters

Red parameters are mandatory.

Blue parameters are optional.


1. subscribe

Registers a User in the system with the provided credentials, and sets the expiration date of the account to +1 year from the current date.

1 mandatory parameter is used:

  • password - password of a newly created user.

4 optional parameters can be used:

  • login - User's account login. If not specified, a default prefix_count name will be used (e.g. ISPname_00001).
    To change the default prefix, please contact your manager or SafeDNS technical support.
    Login is the unique value in the system. We recommend using the default prefix_count naming.
  • email - User’s email. If not specified, the User will not be able to receive system notifications, or stats, and reset the password.
    Users can change the password via Dashboard.
  • plan - User's billing plan. If not specified, PREMIUM (Safe@Home) will be used.
  • customer - User's information (e.g. name).
    Please note that the latest curl update requires %20 to be used instead of spaces.

Example: curl "https://www.safedns.com/provider_api/subscribe?key=PUBLIC_KEY&password=StrongPassword123&login=ACCOUNT_NAME&email=email@example.com&plan=PREMIUM&customer=John%20Doe"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"username": "username",
          	"email": "email",
          	"plan": "tariff_name"
		}
	}
}

2. subscribe_plans

Lists Reseller’s available billing plans.

Example: curl "https://www.safedns.com/provider_api/subscribe_plans?key=PUBLIC_KEY"

The response is returned in JSON format: 

{
	"response": {
		"status": "ok",
		"data": {
			"plan1": "tariff_name1",
			"plan2": "tariff_name2"
		}
	}
}

3. activate

Sets the status of a User to "Active".

1 mandatory parameter is used:

  • ident - User's account login.

Example: curl "https://www.safedns.com/provider_api/activate?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

4. deactivate

Sets the status of a User to "Inactive".

1 mandatory parameter is used:

  • ident - User's account login.

Example: curl "https://www.safedns.com/provider_api/deactivate?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

5. update_email

Updates User’s email.

2 mandatory parameters are used:

  • ident - User's account login.
  • email - new email for a User.

An error will be returned if the user with the same email is found.

Example: curl "https://www.safedns.com/provider_api/update_email?key=PUBLIC_KEY&ident=ACCOUNT_NAME&email=email@example.com"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

6. update_password

Updates User’s password.

2 mandatory parameters are used:

  • ident - User's account login.
  • password - new password for a User.

Example: curl "https://www.safedns.com/provider_api/update_password?key=PUBLIC_KEY&ident=ACCOUNT_NAME&password=StrongPassword123"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

7. prolongate

Enables and changes a paid plan for an existing User.

1 mandatory parameter is used:

  • ident - User's account login.

1 optional parameter can be used:

  • plan - billing plan code (see "Table of values for the plan parameter" above).
    If not used, the paid plan PREMIUM will be set.
    If you use a code that is not available for your account, an error will be returned.

Example: curl "https://www.safedns.com/provider_api/prolongate?key=PUBLIC_KEY&ident=ACCOUNT_NAME&plan=ENTERPRISE"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

8. unsubscribe

Switches a User to the FREE plan with the limited filtering functionality.

1 mandatory parameter is used:

  • ident - User's account login.

Example: curl "https://www.safedns.com/provider_api/unsubscribe?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

9. subscription_info

Gets the expiration date of the account.

1 mandatory parameter is used:

  • ident - User's account login.

Example: curl "https://www.safedns.com/provider_api/subscription_info?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"date_end": 1390930655
		}
	}
}

The expiration date is in UNIX time format.


10. profiles

Gets a list of existing filtering policies.

1 mandatory parameter is used:

  • ident – User's account login.

Example: curl "https://www.safedns.com/provider_api/profiles?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"policy ID 1": "policy name",
          	"policy ID 2": "policy name",
          	"policy ID N": "policy name"
		}
	}
}

“Policy name” is returned in UTF-8 encoding.


11. create_profile

Creates a filtering policy.

2 mandatory parameters are used:

  • ident – User's account login.
  • name – the name of the User's filtering policy.

1 optional parameter can be used:

  • blockpage_id – the id of the block page that will be set for the profile.
    At the moment, blockpage_id can be viewed only in the SafeDNS Dashboard > Settings > Advanced.

Example: curl "https://www.safedns.com/provider_api/create_profile?key=PUBLIC_KEY&ident=ACCOUNT_NAME&name=POLICY_NAME&blockpage_id=ID"

The response is returned in JSON format:

{
	"response": {
		"id": ID number
		"name": profile name
		"status": "ok"
	}
}

12. update_profile

Changes the settings of the User's filtering policy and its blockpage.

1 mandatory parameter is used:

  • profile_id – User's filtering policy ID.

1 optional parameter can be used:

  • name – new name of the User's filtering policy.
  • blockpage_id – assigns blockpage to the filtering policy. 

Example: curl "https://www.safedns.com/provider_api/update_profile?key=PUBLIC_KEY&profile_id=POLICY_ID&name=POLICY_NAME&blockpage_id=BLOCKPAGE_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
          	"name": "profile_name",
          	"tls": "True|False",
        	"id": "profile_id",
          	"blockpage_id": "blockpage_id"
		}
	}
}

13. delete_profile

Deletes one of the existing filtering policies.

1 mandatory parameter is used:

  • profile_id - filtering policy ID.

Example: curl "https://www.safedns.com/provider_api/delete_profile?key=PUBLIC_KEY&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"result": 0
      	{
		"jsonrpc": "1.9"
		}
	}
}

14. add_ip

Adds one or more IP addresses to a User.

2 mandatory parameters are used:

  • ident - User's account login.
  • ip - one or multiple IP addresses. Each address must use its own ip parameter.

2 optional parameters can be used:

  • profile - filtering policy ID. If not used, a Default policy will be used for the IP address.
  • comment - any comment.
    Please note that the latest curl update requires %20 to be used instead of spaces.

Example: curl "https://www.safedns.com/provider_api/add_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&ip=IP_ADDRESS_1&ip=IP_ADDRESS_2&profile=POLICY_ID&comment=COMMENT%20EXAMPLE"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"added_addresses": ["1.1.1.1", "1.1.1.2"],
			"invalid_adresses": [
				{"1.invalid.ip.adress": "IP address is invalid"},
				{"0.0.0.0": "This address is not public"}
			]
        }
    }
}

If one or multiple IP addresses are invalid, the list of these IP addresses will be returned.


15. clear_ip

Deletes all IP addresses of a User that uses the selected filtering policy.

2 mandatory parameters are used:

  • ident - User's account login.
  • profile - filtering policy ID.

Example: curl "https://www.safedns.com/provider_api/clear_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&profile=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

16. list_ip

Gets a list of all User’s IP addresses.

1 mandatory parameter is used:

  • ident - User's account login.

1 optional parameter can be used:

  • profile - filtering policy ID. If not specified, all IP addresses of the account will be listed.

Example: curl "https://www.safedns.com/provider_api/list_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&profile=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"ip": [
				{"address": "1.2.3.4", "comment": "example.com"},
				{"address": "1.2.3.5", "comment": "example.com"}
			],
		}
	}
}

17. remove_ip

Removes specified IP address from User.

2 mandatory parameters are used:

  • ident - User's account login.
  • ip - IP address of a User.

Example: curl "https://www.safedns.com/provider_api/remove_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&ip=IP_ADDRESS"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

18. add_vpn

Creates a VPN Configuration File for the policy and returns OpenVPN policy.

3 mandatory parameters are used:

  • ident - User's account login.
  • name - Configuration File name, unique for a current User.
  • profile_id - filtering policy ID.

Example: curl "https://www.safedns.com/provider_api/add_vpn?key=PUBLIC_KEY&ident=ACCOUNT_NAME&name=CONNECTION_NAME&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
          "ovpn": "client\nremote vpn.safedns.com 1194 udp\nnobind\ndevtun\npersist-tun\npersist-key\nverify-x509-name vpn.safedns.com name\nremote-cert-tls server\ncipher AES-128-CBC\n\n<ca>\n-----BEGIN CERTIFICATE-----\n ----- ENDCERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n</ca>\n<cert>\n----- BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n</cert>\n<key>\n-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY ---- \n</key>\n"
		}
	}
}

If the limit of VPN connections for an account is exceeded, a "Limit is reached" message will be shown.


19. clear_vpn_for_profile

Deletes all VPN Configuration Files that use specified filtering policy.

1 mandatory parameter is used:

  • profile_id - numeric profile ID you need to delete VPN connections for.

Example: curl "https://www.safedns.com/provider_api/clear_vpn_for_profile?key=PUBLIC_KEY&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

20. clear_vpn_for_user

Deletes all VPN Configuration Files of specified User.

1 mandatory parameter is used:

  • ident - User's account login.

Example: curl "https://www.safedns.com/provider_api/clear_vpn_for_user?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

21. get_vpn_list

Gets a list of User’s VPN Configuration Files.

1 mandatory parameter is used:

  • ident - User's account login.

Example: curl "https://www.safedns.com/provider_api/get_vpn_list?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": [
			{"id": "vpn_id1", "profile": "profile_name", "ip": "vpn_hostname1", "name": "vpn_name1"},
			{"id": "vpn_id2", "profile": "profile_name", "ip": "vpn_hostname2", "name": "vpn_name2"}
		]
	}
}

22. remove_vpn

Removes User’s VPN Configuration File.

1 mandatory parameter is used:

  • id - id of the VPN Configuration File.

Example: curl "https://www.safedns.com/provider_api/remove_vpn?key=PUBLIC_KEY&id=VPN_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

23. update_ip

Creates a ddclient record and/or updates the IP address for it.

2 mandatory parameters are used:

  • ident - User's account login.
  • ip - new dynamic IP address of a User.
    If the IP address is already in use by another ddclient record, it will be removed and assigned to this User.

2 optional parameters can be used:

  • hostname - the custom name of the ddclient record (e.g. John Doe).
    Must be specified in order to update the IP address of a certain ddclient record. 
    If not used, the hostname will be empty. You can have only one hostname with an empty name.
  • profile - filtering policy ID.
    If not used, the Default filtering policy will be assigned.

Example: curl "https://www.safedns.com/provider_api/update_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&ip=IP_ADDRESS&hostname=John Doe&profile=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

24. update_nat

Updates a filtering policy of the specified NAT DNS address.

2 mandatory parameters are used:

  • profile_id - filtering policy ID.
  • address - NAT DNS IP address.

Example: curl "https://www.safedns.com/provider_api/update_nat?key=PUBLIC_KEY&profile_id=POLICY_ID&address=NAT_DNS_IP"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

25. get_activity

Gets User’s stats for a certain date.

1 mandatory parameter is used:

  • ident - User's account login.

2 optional parameters are used:

  • date - date, for which a User’s activity report is required, in YYYY-MM-DD format.
    If not used, the report will be formed for the current date.
  • profile_id - filtering policy ID.
    If not used, the report will be formed of all policies.

If no optional parameter is used, a report will be formed for the current date and of all policies.

Example: curl "https://www.safedns.com/provider_api/get_activity?key=PUBLIC_KEY&ident=ACCOUNT_NAME&date=YYYY-MM-DD&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"requests": "2600",
			"blocks": "581"
		}
	}
}

Where requests is the total number of requests for a given date, and blocks is the number of blocks out of total requests.


26. get_activity_report

Gets User's activity report for a certain time range.

3 mandatory parameters are used:

  • ident - User's account login.
  • start - start date (inclusive), in YYYY-MM-DD format.
  • end - end date (inclusive), in YYYY-MM-DD format.

1 optional parameter is used:

  • profile_id - filtering policy ID.
    If not used, the report will be formed of all policies.

If the range start end is more than 30 days, then only the last 30 days will be included in the report.

Example: curl "https://www.safedns.com/provider_api/get_activity_report?key=PUBLIC_KEY&ident=ACCOUNT_NAME&start=YYYY-MM-DD&end=YYYY-MM-DD&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"labels": [
				"2016-06-29 14:00:00",
				"2016-06-29 15:00:00"
			],
			"datasets": [
				{
					"label": "Requests",
					"data": [375, 275]
				},
				{
					"label": "Blocks",
					"data": [13, 0]
              }
			]
		}
	}
}

labels - a list of values for the timestamp.
datasets - a list of dictionaries containing datasets of specific report parameters:
label - the name of a report parameter,
data - a list of parameters corresponding to dates from the labels list.


27. get_popular_report

3 mandatory parameters are used:

  • ident - User's account login.
  • start - start date (inclusive), in YYYY-MM-DD format.
  • end - end date (inclusive), in YYYY-MM-DD format.

1 optional parameter is used:

  • profile_id - filtering policy ID.
    If not used, the report will be formed of all policies.

If the range start end is more than 30 days, then only the last 30 days will be included in the report.

Example: curl "https://www.safedns.com/provider_api/get_popular_report?key=PUBLIC_KEY&ident=ACCOUNT_NAME&start=YYYY-MM-DD&end=YYYY-MM-DD&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"labels": [
				"example.com",
            	"google.com",
            	"asdfg.com"
			],
			"datasets": [
				{
					"label": "Requests",
					"data": [630, 474, 290]
				},
				{
					"label": "NXdomain",
					"data": [0, 0, 290]
				},
				{
					"label":"Blocks",
					"data":[630, 0, 0]
				}
			]
		}
	}
}

labels - a list of values for the timestamp.
datasets - a list of dictionaries containing datasets of specific report parameters:
label - the name of a report parameter,
data - a list of parameters corresponding to dates from the labels list.


28. get_category_report

Gets User's categories report for a certain time range.

3 mandatory parameters are used:

  • ident - User's account login.
  • start - start date (inclusive), in YYYY-MM-DD format.
  • end - end date (inclusive), in YYYY-MM-DD format.

1 optional parameter is used:

  • profile_id - filtering policy ID.
    If not used, the report will be formed of all policies.

If the range start end is more than 30 days, then only the last 30 days will be included in the report.

Example: curl "https://www.safedns.com/provider_api/get_category_report?key=PUBLIC_KEY&ident=ACCOUNT_NAME&start=YYYY-MM-DD&end=YYYY-MM-DD&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"Movies & Video": "5",
			"File Storage": "2",
			"Home & Family": "3"
		}
	}
}

data is a dictionary:
key - category name.
value - number of visits.


29. send_monthly_stat

Sends Monthly Stats report to User’s email.

3 mandatory parameters are used:

  • ident - User's account login.
  • year - year, in YYYY format.
  • month - month, in MM format.

The user must have an email address attached to the account.

1 optional parameter can be used:

  • profile_id - filtering policy ID.
    If not used, the report will be formed of all policies.

User will receive a report in CSV format with stats for the specified month on their email.
The report has the following columns: “Timestamp”, “Domain name”, “Visits”, “Blocks”, “Profile”, and “Categories”.

Example: curl "https://www.safedns.com/provider_api/send_monthly_stat?key=PUBLIC_KEY&ident=ACCOUNT_NAME&year=YYYY&month=MM&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

30. get_daily_stat

Gets a link to the User's Daily Stats report.

2 mandatory parameters are used:

  • date - date, in YYYY-MM-DD format.
  • ident - User's account login.

2 optional parameters can be used:

  • email_to - email generated report to a specified email address.
    If not used, a download link will be returned.
  • profile_id - filtering policy ID.
    If not used, the report will be generated for all policies.

Example: curl "https://www.safedns.com/provider_api/get_daily_stat?key=PUBLIC_KEY&date=YYYY-MM-DD&ident=ACCOUNT_NAME&email_to=EMAIL&profile_id=POLICY_ID"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"result": "link for download"
		}
	}
}

31. update_subscription

Changes the billing plan and/or expiration date of Users.

3 optional parameters can be used:

  • ident - User's account login.
    If not used, all users of the Reseller account will be updated.
  • plan - billing plan code (see Table of values for the plan parameter).
    If not used, the billing plan will not be updated.
  • date - expiration date, in YYYY-MM-DD format. Must be greater than the current date.
    If not used, the expiration date will not be updated.

If no parameters are used, users will not be updated.

Examples:

A specified User is updated with a billing plan and gets the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&ident=ACCOUNT_NAME&plan=BILLING_PLAN&date=YYYY-MM-DD"

A specified User is updated with a billing plan.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&ident=ACCOUNT_NAME&plan=BILLING_PLAN"

A specified User gets the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&ident=ACCOUNT_NAME&date=YYYY-MM-DD"

All Users are updated with a billing plan and get the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&plan=BILLING_PLAN&date=YYYY-MM-DD"

All Users are updated with a billing plan.
​curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&plan=BILLING_PLAN"

All Users get the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&date=YYYY-MM-DD"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"result": 0
      	{
		"jsonrpc": "1.9"
		}
	}
}

32. forgot_password

Sends a password reset email to a User.

1 mandatory parameter is used:

  • ident – User's account login.

Example: curl "https://www.safedns.com/provider_api/forgot_password?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"result": 0
      	{
		"jsonrpc": "1.9"
		}
	}
}

If the User does not have an email attached to the account, the error message "Email not set" will be shown.

The User must have a unique email.


33. get_blockpages

Gets the list of existing BlockPages.

1 mandatory parameter is used:

  • ident – User's account login.

Example: curl "https://www.safedns.com/provider_api/get_blockpages?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"name": "blockpage 1 name",
          	"id": "blockpage 1 id",
          	"profiles": ["filtering policy id 1 that uses blockpage 1", "policy id 2 that uses blockpage 1"],
          	"type": "blockpage 1 type"
		}
	}
}

34. create_blockpage

Creates a new blockpage.

3 mandatory parameters are used:

  • ident - User's account login.
  • name - blockpage name.
  • type - blockpage type (standard, personal, HTML, error, empty).

1 optional parameter can be used:

  • description - description for the personal or HTML blockpages.
    Please note that the latest curl update requires %20 to be used instead of spaces.

Example: curl "https://www.safedns.com/provider_api/create_blockpage?key=PUBLIC_KEY&ident=ACCOUNT_NAME&name=BLOCKPAGE_NAME&type=BLOCKPAGE_TYPE&description=BLOCKPAGE_DESCRIPTION"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
          	"user_id": "user id",
          	"name": "blockpage name",
          	"username": "user account name",
          	"id": "blockpage id",
          	"type": "blockpage type"
		}
	}
}

35. update_blockpage

Updates parameters of the blockpage.

2 mandatory parameters are used:

  • ident - User's account login.
  • blockpage_id - blockpage ID.

3 optional parameters can be used:

  • name - blockpage name.
  • type - blockpage type (standard, personal, HTML, error, empty).
  • description - blockpage description.
    Please note that the latest curl update requires %20 to be used instead of spaces.

Example: curl "https://www.safedns.com/provider_api/update_blockpage?key=PUBLIC_KEY&ident=ACCOUNT_NAME&blockpage_id=BLOCKPAGE_ID&name=BLOCKPAGE_NAME&type=BLOCKPAGE_TYPE&description=BLOCKPAGE_DESCRIPTION"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
          	"type": "blockpage type",
          	"username": "user account name",
          	"name": "blockpage name",
          	"description": "blockpage description",
          	"id": "blockpage id",
          	"user_id": "user id"
		}
	}
}

36. user_list

Lists all created user accounts.

1 optional parameter can be used:

  • activity_status - additional filter.
    True displays all user accounts except inactive and with the "Paid period ended" plan.
    False displays all inactive and "Paid period ended" plan accounts.
    If not used, all created user accounts will be displayed.

Example: curl "https://www.safedns.com/provider_api/user_list?key=PUBLIC_KEY&activity_status=TRUE/FALSE"

The response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": [{
          	"is_active": "activity status of the account",
          	"plan": "billing plan",
          	"username": "account username"
        }]
	}
}

see the Table of values at the beginning of the article for the billing plan codes