# Subscription API guide **Version 2.1.** 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](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%26NONPROFIT**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. The password must have: \- Between 8 and 128 characters \- At least one digit (0-9) \- At least one lowercase letter (a-z) \- At least one uppercase letter (A-Z) \- At least one special character: ~ ! ? @ # $ % ^ & \* \_ - + ( ) \[ \] { } > < / \\ | " ' . , : ;
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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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. The password must have: \- Between 8 and 128 characters \- At least one digit (0-9) \- At least one lowercase letter (a-z) \- At least one uppercase letter (A-Z) \- At least one special character: ~ ! ? @ # $ % ^ & \* \_ - + ( ) \[ \] { } > < / \\ | " ' . , : ;
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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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\n-----BEGIN CERTIFICATE-----\n ----- ENDCERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n\n\n----- BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n\n\n-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY ---- \n\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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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:
- **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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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: ```JSON { "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