KingSide Resellers' Guide v0.1
1. Definitions
- Included SMS: Number of SMS messages given to sub-users each month after they pay for their subscription and the reseller renews their account.
- Included Contacts: Number of contacts that sub-users can insert into their accounts.
- SMS Cost: Sub-users can buy additional SMS (in addition to their included SMS) at this cost.
- Contact Cost: Sub-users can buy additional contacts (in addition to their included Contacts) at this cost.
- Reseller: You.
2. API Methods
- The API supports HTTP GET requests.
- Response is encoded in JSON and indicates whether the request was successful or not.
A successful request returns this sample response
{ "status" : "success", "message" : "sample message" }
An unsuccessful request returns this sample response
{ "status" : "error", "message" : "sample message" }
2.1. Create sub-user account
- Creates a new sub-user account.
- Sub-users are instantly emailed after an account is created, they receive an email with their username and password.
- The amount of SMS/Contacts that is set for sub-user accounts when they are created, will be deducted instantly from the reseller's account, if there is not enough SMS/Contacts in the reseller's account then the reseller's payment method will be charged an amount equal to the reseller's additional SMS/Contacts cost times the number of SMS/Contacts set for created sub-user account.
- There are 2 ways of creating a sub-user, one of them is by choosing custom values for sms/contact cost, included sms/contacts. And the other way is by just setting the 'plan' parameter which is the name of any plan you have created before from the white label admin dashboard.
https://api.kingside.com/reseller/create.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&password=[]&first_name=[]&last_name=[]&plan_cost=[]&sms_cost=[]&included_sms=[]&contact_cost=[]&included_contacts=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: email of the sub-user to be created
password: sub-user's password, should be at least 6 characters
first_name: sub-user's valid first name
last_name: sub-user's valid last name
plan_cost: the monthly subscription paid by sub-user, should be a positive integer
sms_cost: cost of additional sms that sub-user purchases (range is 0.01 to 0.1)
included_sms: number of sms given to sub-user each month (range is 1 to 25000)
contact_cost: cost of additional contacts that sub-user purchases (range is 0.003 to 0.02)
included_contacts: number of contacts included in plan. a sub-user will be able to add contacts up to this number + any additional purchased contacts (range is 0 to 100000)
OR
https://api.kingside.com/reseller/create.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&password=[]&first_name=[]&last_name=[]&plan=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: email of the sub-user to be created
password: sub-user's password, should be at least 6 characters
first_name: sub-user's valid first name
last_name: sub-user's valid last name
plan: the name of any plan that you have been created using the white label admin dashboard
2.2. Renew sub-user account
- This method is called after a sub-user pays the monthly subscription successfully.
- When a sub-user account is renewed, their remaining SMS will be increased by their included SMS. And the sub-user will be able to login for another 1 month.
- Normally, all accounts expire after 1 month (on their billing date). 'Expire' means sub-users are no longer able to login to their accounts. This happens when their monthly subscription is not paid.
https://api.kingside.com/reseller/renew.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
amount: the amount of payment made by sub-user in integers
2.3. Adjust included SMS for sub-user
- Included SMS is the amount of SMS that sub-users receive each month after successful renewal of their subscriptions.
https://api.kingside.com/reseller/adjust-sms.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&type=included&value=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
type: should be 'included'
value: this is the desired value to set for the included sms (range is 1 to 25000)
2.4. Adjust included contacts for sub-user
- Contact limit is the maximum number of contacts that sub-users can insert into their accounts.
https://api.kingside.com/reseller/adjust-contacts.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&type=included&value=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
type: should be 'included'
value: this is the desired value to set for the remaining contacts (range is 1 to 100000)
2.5. Adjust remaining SMS for sub-user
- In case you increased the number of SMS for a sub-user then the difference of this increase will be deducted from the reseller's SMS credit, if there is enough SMS credit, if not then the reseller's (your) payment method will be charged an amount equal to the reseller's (your) additional SMS cost times the number of SMS given to sub-user.
- In case you decreased the number of SMS for a sub-user then the difference of this decrease will be returned back to the reseller's (your) account as SMS credit.
https://api.kingside.com/reseller/adjust-sms.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&type=remaining&value=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
type: should be 'remaining'
value: this is the desired value to set for the remaining sms (range is 1 to 25000)
2.6. Adjust remaining contacts for sub-user
- In case you increased the number of contacts for a sub-user then the difference of this increase will be deducted from the reseller's contacts credit, if there is enough contacts credit, if not then the reseller's (your) payment method will be charged an amount equal to the reseller's (your) additional contacts cost times the number of contacts given to sub-user.
- In case you decreased the number of contacts for a sub-user then the difference of this decrease will be returned back to the reseller's (your) account as contacts credit.
https://api.kingside.com/reseller/adjust-contacts.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&type=remaining&value=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
type: should be 'remaining'
value: this is the desired value to set for the remaining contacts (range is 1 to 100000)
2.7. Adjust SMS cost for sub-user
- The amount that sub-users are charged when purchasing additional SMS.
https://api.kingside.com/reseller/adjust-sms.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&type=cost&value=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
type: should be 'cost'
value: cost of additional sms that sub-user purchases (range is 0.01 to 0.1)
2.8. Adjust contact cost for sub-user
- The amount that sub-users are charged when purchasing additional contacts.
https://api.kingside.com/reseller/adjust-contacts.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]&type=cost&value=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
type: should be 'cost'
value: cost of additional contacts that sub-user purchases (range is 0.003 to 0.02)
2.9. Delete sub-user account
- Deletes a sub-user account and refunds remaining SMS and contacts to the reseller's account.
https://api.kingside.com/reseller/delete.php?username=[USERNAME]&secret_key=[SECRET_KEY]&subuser=[]
username: your username which is [USERNAME]
secret_key: your secret_key which is [SECRET_KEY]
subuser: username of the sub-user
3. Plans Management
3.1. When creating a new sub-user account through the API, you can manually specify the different parameters like SMS cost, contact cost, included SMS, included contacts. Or - instead - you can create your own plans with pre-set values and just pass the plan name in your sub-user creation request.
3.2. To create plans, go to the the white label admin dashboard, then select the 'Plans Management' tab. Then create your plan.
3.3. After creating plans, you will be able to generate a pricing table - if needed - to be used in your website. To generate a pricing table, simply go to the the white label admin dashboard, then select the 'Plans Management' tab. You will see a pricing table that is already generated for your current plans, at the top of every pricing column you can select which plan to display. Then click 'Get Pricing Table Code' to be able to get the necessary code/css.
4. API Usage Examples
If you are using PayPal or any other service and would like to completely control sub-user creation/billing using the API then here is a sample scenario.
4.1. Login to KingSide using your reseller account and create your plans (refer to 3.2).
4.2. Create your pricing tables and signup forms on your website. You can generate a pricing table for your plans using KingSide (refer to 3.3).
4.3. Connect your signup form to KingSide sub-user creation API method (refer to 2.1). So that when sub-users sign up using your form, an account is created for them instantly. Please note that you can either, also include your own payment form during the signup process if you want to create an account for them after they pay the subscription.
4.4. Sub-users will be sent an email with their login details and they will be able to login and start using their account.
4.5. After 1 month, a created account will be suspended if not paid for. So you need to make an API request to renew the subscription of sub-users (refer to 2.2). Ideally, this request is made after the monthly payment callback (automated recurring billing) for each sub-user.
4.6. If a sub-user pays you for additional sms/contacts, you can then make an API request to adjust the sub-user's remaining sms/contacts (refer to 2.5 & 2.6).
4.7. If a sub-user needs to change plans (i.e.: have more or less sms/contacts, higher or lower sms/contact cost) then you can make an API request to adjust the sub-user's included sms/contacts (refer to 2.3 & 2.4) and also another API request to adjust sms/contact cost (refer to 2.7 & 2.8).
5. Subscribe Leads
To subscribe leads to your campaigns, you will need to issue an HTTP GET Request per lead to:
http://api.kingside.com/subscribe.php
The following parameters are required in your request to subscribe a lead:
| Parameter |
Description |
| username |
Your account username |
| secret_key |
Your unique secret key |
| campaign |
Campaign name you want the lead to be added to. This should be one of your previously created campaigns. |
| email |
Email address of lead. |
You may include the following parameters:
| Parameter |
Description |
| name |
Name of lead, could be a single name or the full name. It should be no longer than 30 characters.
Note: Pleae note that the full name would be split into first name and last name on the occurence of the first "space". Also You should either use name=FULL_NAME or fname=FIRST_NAME along with lname=LAST_NAME. |
| fname |
First name of lead. It should be no longer than 15 characters. |
| lname |
Last name of lead. It should be no longer than 15 characters. |
| source |
It is the source or where the lead is coming from, this should be no longer than 20 characters. |
| Custom Parameters |
You could add special parameters to the subscribed lead info by adding "&p1=[PARAMETER1]&p2=[PARAMETER2]&p3=....." to your GET Request. |
http://api.kingside.com/subscribe.php?username=[]&secret_key=[]&campaign=[CAMPAIGN_NAME]&name=[NAME]&email=[EMAIL]&p1=[Custom_Parameter1]&p2=[Custom_Parameter2]