API Documentation Current version 1.0

Introduction

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.

List Users

To retrieve list of users.

<?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 User

Add a new contact to the system.

<?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

Update User.

<?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

Delete User.

<?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

Get User details.

<?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

Get Form Fields.

<?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;
?>

Unapprove Sale

To Unapprove Sale.

<?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;
?>

Add Sale

To Add Sale Record.

<?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;  
?>

Edit Sale

To Edit Sale Record.

<?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;  
?>

Delete Sale

To Delete Sale Record.

<?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;  
?>

Turn Off Recurring

To Turn off Recurring Sale.

<?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;
?>

Send Recurring Sale

To Send Recurring Sale Record to our system.

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

Edit Recurring Sale

To Edit Recurring Sale Record.

<?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;  
?>

Delete Recurring Sale

To Delete Recurring Sale Record.

<?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;  
?>

Setup Webhook

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: