API Documentation Current version 1.0

The following API is recommended for any functionality needed outside of the main user interface. We provide a list of available API methods along with detailed descriptions of each parameter, as well as examples in actual code. Our API examples are using PHP but you could use virtually any programming language to interact with our API.

The general instructions of how to get started using the OSIAFFILIATE API.

Overview

The OSIAFFILIATE API is a REST implementation, and requires authentication (actual user account within the software, or valid API URL and key).

General Requirements

  1. Valid OSIAFFILIATE account (a trial account will also work fine).
  2. Familiarity with programming concepts and practices.
  3. Ability to submit HTTP requests from your server.

Obtain API Key and Subdomain Name

The first thing you will want to do is obtain your API Key and Subdomain Name.

"Admin" Group users can visit the Admin -> Profile tab:

It will take to you on the follwing page.

Once you obtain these values, you can submit API requests by looking at our examples page to see what parameters are required, and how they should be formatted.

Reset Your API Key

To reset your API key, just click the "Regenerate API Key" button next to the API Key field:

Please note: once you reset your API key, all access will be denied until you update your applications to use the new key.

To retrieve list of users.

Example Usage of list_users

Description: To retrieve list of users.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* list_users
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: User Fetched successfully.
data The result output used. Example: serialize

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'list_users';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    // pass field name and its value by getting fields using get_form_fields api
    $post_data_array = array(
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR']
    );

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

Add a new contact to the system.

Example Usage of add_user

Description: Add a new contact to the system.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* add_user
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
email* Email of the new contact. Example: 'test@example.com'
u_first_name First name of the contact. Example: 'FirstName'
u_last_name Last name of the contact. Example: 'LastName'
u_phone Phone number of the contact. Example: '+1 312 201 0300'
Similarly you can pass the field name and its value by getting the list of fields using get_form_fields api.
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: User added successfully.
data The result output used. Example: serialize

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'add_user';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    // pass field name and its value by getting fields using get_form_fields api
    $post_data_array = array(
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'],
        'u_first_name'=>'First_Name',
        'u_last_name'=>'Last_Name',
        'email'=>'test@example.com',
        'password'=>'*******',
        '5222'=>'Title',
        '5223'=>'Company Name',
        '5224'=>'www.website.com',
        '5225'=>'Address',
        '5226'=>'Address2',
        'u_state_province'=>'State',
        '5227'=>'City',
        'u_zipcode'=>'Zip_Code'
    );

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

Update User.

Example Usage of update_user

Description: Update existing user in the system.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* update_user
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
email* Email of the new contact. Example: 'test@example.com'
u_first_name First name of the contact. Example: 'FirstName'
u_last_name Last name of the contact. Example: 'LastName'
u_phone Phone number of the contact. Example: '+1 312 201 0300'
Similarly you can pass the field name and its value by getting the list of fields using get_form_fields api.
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: User updated successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'update_user';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    // pass field name and its value by getting fields using get_form_fields api
    $post_data_array = array(
        /* Pass u_id or email */
        //'u_id'=> 'USER_ID',
        'email'=>'EMAIL_OF_USER', 
        'ip'=>$_SERVER['REMOTE_ADDR'],
        'subdomain_name'=>$subdomain_name,
        'u_first_name'=>'First_Name',
        'u_last_name'=>'Last_Name', 
        'password'=>'*******',
        '5222'=>'Title',
        '5223'=>'Company Name',
        '5224'=>'www.website.com',
        '5225'=>'Address',
        '5226'=>'Address2',
        'u_state_province'=>'State',
        '5227'=>'City',
        'u_zipcode'=>'Zip_Code'
    ); 

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

Delete User.

Example Usage of delete_user

Description: Delete existing user in the system.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* delete_user
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
email* Email of the new contact. Example: 'test@example.com'
u_id* User Id of the user.
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: User deleted successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'delete_user';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    $post_data_array = array( 
        //'u_id'=> '123',          // Pass User Id or email
        'email'=>'test@example.com',
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR']
    );
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

Get User details.

Example Usage of get_user

Description: Get details of existing user from the system.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* get_user
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
email* Email of the new contact. Example: 'test@example.com'
u_id* User Id of the user.
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: User details fetched successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'get_user';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    
    $post_data_array = array( 
        //'u_id'=> '123',          // Pass User Id or email
        'email'=>'test@example.com',
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR']
    );
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

Get Form Fields.

Example Usage of get_form_fields

Description: Get list of form fields from the system.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* get_form_fields
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: User details fetched successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'get_form_fields';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    $post_data_array = array(  
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR']
    );
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

To Unapprove Sale.

Example Usage of unapprove_sale

Description: To Unapprove Sale.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* unapprove_sale
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sale_id* Comma seperated Ids of the sale for which you want to unapprove
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Sale Unapproved.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'unapprove_sale';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    $post_data_array = array(  
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'],
        'sale_id'=>SALE_ID
    );
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

To Add Sale Record.

Example Usage of sale_add

Description: To Add Sale Record.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* sale_add
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sr_u_id* Id of the user.
sr_ap_id* Id of the Referral Program.
sr_transaction_id* Transaction Id. It is the unique Id which will be used to update the sale record.
sr_sale_amount* Sale Amount
sr_setdata* Extra set of data with keys setdata1, setdata2, setdata3, setdata4, setdata5. This must be in array format. Example: 'sr_setdata' = array('setdata1'=>'value1','setdata2'=>'value2'....and so on)
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Sale Added Successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'sale_add';
    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
      
    $post_data_array = array(
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'],
        'sr_u_id'=>4847, //Id of the User
        'sr_ap_id'=>1181, // Id of the Referral Program
        'sr_transaction_id'=>'1001', // Transaction Id
        'sr_sale_amount'=>50.00, // Amount of Sale 
        'sr_setdata'=>array(
            'setdata1'=>'value1',
            'setdata2'=>'value2',
            'setdata3'=>'value3',
            'setdata4'=>'value4',
            'setdata5'=>'value5'
        )
    );  

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, http_build_query($post_data_array)); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle); 
    echo $response;  
?>

To Edit Sale Record.

Example Usage of sale_edit

Description: To Edit Sale Record.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* sale_edit
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sr_transaction_id* Transaction Id. It is the unique Id used to update the sale record.
sr_sale_amount Sale Amount
sr_added_date Date of Sale
sr_next_reoccurring_date Next Recurring date(If sale is of recurring type)
sr_is_approved Status of sale Record. (1=Approved, 0=Not Approved)
sr_setdata* Extra set of data with keys setdata1, setdata2, setdata3, setdata4, setdata5. This must be in array format. Example: 'sr_setdata' = array('setdata1'=>'value1','setdata2'=>'value2'....and so on)
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Sale Added Successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'sale_edit';
    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
      
    $post_data_array = array(
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'],
        'sr_transaction_id'=>'1001', // Transaction Id
        'sr_sale_amount'=>50.00, // Amount of Sale
        'sr_added_date'=>'2015-09-29 15:08:21', // in Y-m-d H:i:s Format
        'sr_next_reoccurring_date'=>'2015-10-29 15:08:21', // in Y-m-d H:i:s Format
        'sr_setdata'=>array(
            'setdata1'=>'value1',
            'setdata2'=>'value2',
            'setdata3'=>'value3',
            'setdata4'=>'value4',
            'setdata5'=>'value5'
        ),
        'sr_is_approved'=>1
    );  

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, http_build_query($post_data_array)); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle); 
    echo $response;  
?>

To Delete Sale Record.

Example Usage of sale_delete

Description: To Delete Sale Record.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* sale_delete
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sr_id* Sale Id. It is the unique Id used to delete the sale record.
sr_transaction_id* Transaction Id. It is the unique Id used to delete the sale record.
Note: Pass sr_id(Sale Id) Or sr_transaction_id(Transaction Id) Or both
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Sale Deleted Successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'sale_delete';
    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
      
    $post_data_array = array(
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'],
        'sr_transaction_id'=>'1001', // Transaction Id 
        'sr_id'=>4847, // Sale Id pass sale id or transaction id
    );  

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, http_build_query($post_data_array)); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle); 
    echo $response;  
?>

To Turn off Recurring Sale.

Example Usage of turn_off_recurring

Description: To Turn off Recurring Sale.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* turn_off_recurring
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sale_id* Comma seperated Ids of the sale for which you want to turn off recurring.
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Recurring Sale Turned Off.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'turn_off_recurring';

    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
    
    $post_data_array = array( 
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'], 
        'sale_id'=>SALE_ID
    );
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, $post_data_array); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle);
    if ( !$response ) {
      die('Nothing was returned. Do you have a connection to our server?');
    }
    echo 'The entire result printed out:<br />';
    echo $response;
?>

To Send Recurring Sale Record to our system.

Example

Description: You can pass the following parameters in URL to send Recurring Sale.
Parameters:
* indicates requirement. Underlined params include in URL.
Variable Description
action* send_recurring
key* Your API key
customer_email* Customer Email which is to be matched.
amount* Sale Amount.
transaction Transaction ID
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Recurring Sale Added Successfully.

Example

Call Following URL with your values

https://www.ositracker.com/sales/send_recurring?key=YOUR_API_KEY&customer_email=example@xyz.com&amount=20&transaction=10012

To Edit Recurring Sale Record.

Example Usage of recurringsale_edit

Description: To Edit Recurring Sale Record.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* recurringsale_edit
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sr_id* Recurring Sale Id. It is the unique Id used to update the sale record.
sr_commission_amount Commission Amount
sr_added_date Date of Sale
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Sale Added Successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'recurringsale_edit';
    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
      
    $post_data_array = array(
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'], 
        'sr_id'=>'1001', // Recurring Sale Id 
        'sr_commission_amount'=>5.00, // Commission Amount
        'sr_added_date'=>'2015-09-29 15:08:21', // in Y-m-d H:i:s Format
    );  

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL,$url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, http_build_query($post_data_array)); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle); 
    echo $response;  
?>

To Delete Recurring Sale Record.

Example Usage of recurringsale_delete

Description: To Delete Recurring Sale Record.
HTTP method: POST
Supported formats: json
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body.
Variable Description
api_action* recurringsale_delete
api_key* Your API key
subdomain_name* Your Subdomain. Example: test.example.com
sr_id* Sale Id. It is the unique Id used to delete the recurring sale record.
Example response:
Variable Description
code Whether or not the response was successful. Examples: 1 = yes, 0 = no
message A custom message that appears explaining what happened. Example: Sale Deleted Successfully.

Example in PHP


<?php
    $api_key = 'YOUR_API_KEY'; 
    $subdomain_name = 'YOUR_SUBDOMAIN'; // eg. test.example.com
    $api_action = 'recurringsale_delete';
    $url = 'http://newapi.omnistarhost.com/api/'.$api_action.'/'.$api_key;
      
    $post_data_array = array( 
        'subdomain_name'=>$subdomain_name,
        'ip'=>$_SERVER['REMOTE_ADDR'], 
        'sr_id'=>4847, // Sale Id
    );  

    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL, $url);
    curl_setopt($handle, CURLOPT_POST, true);
    curl_setopt($handle, CURLOPT_POSTFIELDS, http_build_query($post_data_array)); 
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    curl_close($handle); 
    echo $response;  
?>

Osiaffiliate Software provides web hook functionality to greatly increase the capabilities of the platform. Web hooks, also known as "service hooks", also known as "reverse API", also known as "callbacks", also known as "silent postbacks" are messages sent by Osiaffiliate to external services. Web hooks are triggered by various events within Osiaffiliate.

Events

Many events occur within Osiaffiliate as a natural part of performing its duties. Below is a list of events which are "actionable" via the Service Hooks system.

  1. New Sale
  2. New Recurring Sale
  3. Delete Sale
  4. Delete Recurring Sale

1. New Sale

This event occurs when a new sale is generated via any one of several possible actions: API call, From Admin, Any other Hosted Page.

2. New Recurring Sale

This event occurs when a new recurring sale is generated via any one of several possible actions: API call, From Admin, Any other Hosted Page.

3. Change in Sale

This event occurs when a sale is updated via any one of several possible actions: API call, From Admin.

4. Change in Recurring Sale

This event occurs when a recurring sale is updated via any one of several possible actions: API call, From Admin

5. Delete Sale

This event occurs when a sale is deleted via any one of several possible actions: API call, From Admin.

6. Delete Recurring Sale

This event occurs when a recurring sale is deleted via any one of several possible actions: API call, From Admin.

7. New User

This event occurs when a new affiliate user is added via any one of several possible actions: API call, From Admin.

8. Modify User

This event occurs when an affiliate user details are modified via any one of several possible actions: API call, From Admin.

9. Delete User

This event occurs when an affiliate user is deleted via any one of several possible actions: API call, From Admin.

Use SSL

You may use a HTTP or a HTTPS url. HTTPS can be useful to protect your data or if you wish to protect against replay attacks for example.

Security

Hook requests are signed for additional security. You may wish to validate a request's signature to ensure that the hook is coming from Osiaffiliate and is well formed. This is not a requirement but is highly recommended. HTTP POST requests from Osiaffiliate's Custom URL hooks include a special header: X-OSI-SIGNATURE. The value of this header is a HMAC sha256 keyed hex hash of an MD5 hash of the request body using your product secret key as the key. Exciting, right? Here are the generic steps to validate a request:

  1. Get the raw body of the request.
    • This is the raw content of the HTTP POST request not including the headers
  2. Calculate the MD5 of the raw request body (we refer to this as the "request token")
    • The MD5 hash should be a 32-character hexadecimal number
  3. Use the sha256 algorithm to generate an HMAC hash of the request token
    • use your product secret key as the salt
    • The hash should result in a 64-character hexadecimal number
  4. Compare the result from step 3 to the value of the X-OSI-SIGNATURE header in the request.
    • If they match, the request can be considered well-formed and from the expected source.

A raw PHP example for validating a request:

<?php
if (empty($_SERVER['HTTP_X_OSI_SIGNATURE'])) {
  //invalid
}
$rawBody = file_get_contents('php://input');
$token = md5($rawBody);
$productKey = 'xxxxxxxxxxxxxxxx'; // API KEY
// check signature
if ($_SERVER['HTTP_X_OSI_SIGNATURE'] == hash_hmac('sha256',$token,$productKey)) {
  echo $rawBody; // It is the json response
} else {
  // invalid
}
?>

Sample Output from Webhook


{
    "activityType": "NewSale",
    "activityDatetime": "2015-10-05 14:27:27",
    "activityActor": "adminuser@example.com",
    "SalesRecord": {
        "sr_id": "4513",
        "sr_u_id": "5901",
        "sr_sale_id": null,
        "sr_sale_amount": "15.00",
        "sr_commission_type": "1",
        "sr_commission_type_value": "5.00",
        "sr_commission_amount": "0.75",
        "sr_is_approved": "1",
        "sr_added_date": "2015-10-05 14:27:26",
        "sr_next_reoccurring_date": "2015-11-05 14:27:26",
        "sr_level": "1",
        "sr_setdata": "[]",
        "sr_status": "1"
    },
    "User": {
        "u_id": "5901",
        "u_subdomain_name": "subdomain.ositracker.com",
        "email": "user@ositracker.com",
        "u_first_name": "FirstName",
        "u_last_name": "LastName"
    },
    "AffiliateProgram": {
        "ap_id": "1208",
        "ap_name": "Test Affiliate Program",
        "ap_link": "http:\/\/example.com"
    }
}

To test if our webhook is working and to email yourself an output of what the webhook output will be you can use the sample php code below. Make sure where it says: youremail@yourdomain.com you put your actual email.

Here are the steps to run a test webhook and to email yourself the results:

  1. Add the webhook in our backend and have it go to your server. Use a link like: http://www.yourserver.com/testwebhook.php
    Note: Do not use this actual like. Setup a test file on your server and enter that test URL when you setup the webhook. As you keep reading, you will see what to enter for this test URL. Since you added this webhook, this means that this URL, will be called when something happens within our software. For example, if there is a new sale, we will call this URL.
  2. Now at the test URL that you set up in the previous step, move the following code:
    <?php
    if (empty($_SERVER['HTTP_X_OSI_SIGNATURE'])) {
      mail('youremail@yourdomain.com', 'Invalid Webhook Call', 'Invalid Webhook Call');
    }
    $rawBody = file_get_contents('php://input');
    $token = md5($rawBody);
    $productKey = 'xxxxxxxxxxxxxxxx'; // API KEY
    // check signature
    if ($_SERVER['HTTP_X_OSI_SIGNATURE'] == hash_hmac('sha256',$token,$productKey)) {
      mail('youremail@yourdomain.com', 'Valid Webhook Call', $rawBody);
    } else {
      mail('youremail@yourdomain.com', 'Invalid Webhook Call', 'Invalid Webhook Call');
    }
    ?>
    
    Note: Make sure you replace youremail@yourdomain.com which your actual email.

Now you have to make our software do something that will initiate this webhook. Therefore, if you have set the webhook to initiate when a new sale is made, then go ahead and put through a new test sale. In this case, the webhook should be called and you will receive output of the data we would pass you. Now that you see the data and the output, you can figure out how you will use it with your third party software.

For each webhook, you will get the response regarding sales or user details, the event can be recognised by the value of activityType. Following are the activityType you will get:

Webhook Event activityType
New Sale NewSale
New Recurring Sale NewRecurringSale
Change in Sale UpdateSale
Change in Recurring Sale UpdateRecurringSale
Delete Sale SaleDeleted
Delete Recurring Sale RecurringSaleDeleted
New User NewUser
Modify User UpdateUser
Delete User DeleteUser