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

Table of values for the plan parameter

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:

4 optional parameters can be used:

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:

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:

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:

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:

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:

1 optional parameter can be used:

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:

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:

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:

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:

1 optional parameter can be used:

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:

1 optional parameter can be used:

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:

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:

2 optional parameters can be used:

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:

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:

1 optional parameter can be used:

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:

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:

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:

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:

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:

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:

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:

2 optional parameters can be used:

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:

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:

2 optional parameters are used:

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:

1 optional parameter is used:

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

Gets the User's popular requests report for a certain time range.

3 mandatory parameters are used:

1 optional parameter is used:

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:

1 optional parameter is used:

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:

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

1 optional parameter can be used:

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:

2 optional parameters can be used:

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:

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:

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:

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:

1 optional parameter can be used:

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:

3 optional parameters can be used:

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:

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