1.Introduction #

The UpViral API allows for a wide variety of interactions with the UpViral Platform using an application.

The API endpoint is located here: https://app.upviral.com/api/v1/

  • All API requests should use the above URL as their base url.
  • All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Responses from the UpViral API are returned in JSON format, unless otherwise stipulated.

PHP SDK Installation

composer require upviral/php-sdk

2.Contact #

To add, see or edit contacts in a campaign.

2.1Add Contact #

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'add_contact',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE',
            'email' => 'Your Email Address HERE',
            'name' => 'Joe',
            'referral_code' => 'XXXX',
            'custom_fields' => [
                'field1' => 'value1',
                'field2' => 'value2'
            ]
        ]);
        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);

                                    
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'add_contact',
                 'campaign_id':'YOUR CAMPAIGN ID HERE',
                 'email':'Your Email Address HERE',
                 'name':'Joe',
                 'referral_code':'XXXX',
                 'custom_fields[field1]':'value1',
                 'custom_fields[field2]':'value2'
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                
<?php
        $upviral = new Upviral\SDK('YOUR API KEY HERE');
                                            
        $contact = new \Upviral\Entity\Contact();
        $contact->name = 'Joe';
        $contact->email = 'Your Email Address HERE';
        $contact->campaigns = 'YOUR CAMPAIGN ID HERE';
        $contact->referred_by = 'XXXX';
        $contact->custom_fields = [
                'field1' => 'value1',
                'field2' => 'value2'
            ];
        $addContact = $upviral->addContact($contact);
        print_r($addContact);

                                

Example Response

{
        "result": "success",
        "uid": "USER ID",
        "email": "[email protected]"
        }

This POST request adds contacts in your particular campaign.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.


email

The user’s email address. This field is required.


name

The user’s name. This field is optional.


Referral Code

The unique referral code (Last part of unique Referral URL). For example - https://upvir.al/ref/XXXX, Referral Code will be XXXX.This will be the referral code of the person who referred this new contact. The original participant will get the credit for this new contact.


custom_fields

The campaign’s custom fields, which you add in your lead page editor or advance settings Click here to get more details

2.2Get Contact Details #

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'get_lead_details',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE',
            'lead_id' => 'Your Contact ID HERE'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'get_lead_details',
                 'campaign_id':'YOUR CAMPAIGN ID HERE',
                 'lead_id':'Your Contact ID HERE',
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                
<?php
        
        $upviral = new Upviral\SDK('YOUR API KEY HERE');        
        $getContact = $upviral->getContact('Your Contact ID HERE', 'YOUR CAMPAIGN ID HERE');
        print_r($getContact);

                                

Example Response

{
        "result" : "success",
        "lead_details" : 
         { 
            "id" :"3162",
            "name" : "Joe",
            "email" : "[email protected]",
            "status": "enable",
            "created_date" : "2018-05-31 16:10:26",
            "total_points" : "1",
            "is_fraud" : "0",
            "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
            "custom_fields" : 
            {
                "field1" : "value1",
                "field2" : "value2"
            },
            "campaigns" :[
             {
                "campaign_id " : "489",
                "campaign_name ": "Hosted blank template"
             }
            ],
            "referred_by ":null,
            "referrals ":[]
          }
        }

This POST request gets contact details.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.


lead_id

The user’s unique ID. This field is required.


RESPONSE PARAMETERS

is_fraud

If a lead is fraudulent, it will return 1 else it will be 0.

2.3Get All Contact Details #

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'get_leads',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE',
            'start' => 'Start limit pagination',
            'size' => 'No of contacts need to be fetch'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'get_leads',
                 'campaign_id': 'YOUR CAMPAIGN ID HERE',
                 'start': 'Start limit pagination',
                 'size': 'No of contacts need to be fetch'
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                
<?php

        $upviral = new Upviral\SDK('YOUR API KEY HERE');                                        
        
        $getContact = $upviral->getContacts('YOUR CAMPAIGN ID HERE');
        print_r($getContact);
                                

Example Response

{ 
        "data" : 
            {
                "total_size":"11",
                "page_start":1,
                "page_size":"2",
                "next_page_start":3,
                "next_page_size":"2",
                "leads":[
                { 
                    "id" :"3162",
                    "name" : "Joe",
                    "email" : "[email protected]",
                    "status": "enable",
                    "created_date" : "2018-05-31 16:10:26",
                    "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
                    "custom_fields" : 
                    {
                        "field1" : "value1",
                        "field2" : "value2"
                    }
                },
                { 
                    "id" :"3163",
                    "name" : "Joe1",
                    "email" : "[email protected]",
                    "status": "enable",
                    "created_date" : "2018-05-31 17:02:12",
                    "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
                    "custom_fields" : 
                    {
                        "field1" : "value1",
                        "field2" : "value2"
                    }
                }

            ]    
        }
                                }

This POST request gets contact details using pagination.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.


start

The start limit of pagination.


size

The number of contact for listing.

2.4Get All Contact Details Filtered By Points #

Example: Searching for people with more than 10 points

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'get_leads_points',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE',
            'operator' => 'Operator to filter',
            'points' => 'Points to filter',
            'start' => 'Start limit pagination',
            'size' => 'No of contacts need to be fetch'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'get_leads_points',
                 'campaign_id': 'YOUR CAMPAIGN ID HERE',
                 'operator' : 'Operator to filter',
                 'points' : 'Points to filter',
                 'start': 'Start limit pagination',
                 'size': 'No of contacts need to be fetch'
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                
<?php

        $upviral = new Upviral\SDK('YOUR API KEY HERE');                                        
        
        $getContact = $upviral->getContacts('YOUR CAMPAIGN ID HERE', ['operator'=>'Operator to filter', 'points'=>'Points to filter']);
        print_r($getContact);
                                

Example Response

{ 
        "data" : 
         {
            "total_size":"11",
            "page_start":1,
            "page_size":"2",
            "leads":[
            { 
                "id" :"3162",
                "name" : "Joe",
                "email" : "[email protected]",
                "status": "enable",
                "total_points": "10",
                "created_date" : "2018-05-31 16:10:26",
                "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
                "custom_fields" : 
                {
                    "field1" : "value1",
                    "field2" : "value2"
                }
            },
            { 
                "id" :"3163",
                "name" : "Joe1",
                "email" : "[email protected]",
                "status": "enable",
                "total_points": "10",
                "created_date" : "2018-05-31 17:02:12",
                "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
                "custom_fields" : 
                {
                    "field1" : "value1",
                    "field2" : "value2"
                }
            }
         ]    
        }
                                }

This POST request gets contact details using pagination.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.


operator

The operator for searching( e.g. <,>,= ). This field is required.


points

The point for searching(e.g. 1,100)


start

The start limit of pagination. This field is required.


size

The number of contact for listing. This field is required.

2.5Add Points #

Add other points.

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'add_points',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE',
            'lead_id' => 'User id to add points',
            'points' => 'Points to add'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'add_points',
                 'campaign_id': 'YOUR CAMPAIGN ID HERE',
                 'lead_id' : 'User id to add points',
                 'points' : 'Points to add',
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                
<?php

        $upviral = new Upviral\SDK('YOUR API KEY HERE');                                        
        
        $addPoints = $upviral->addPoints('User id to add points', 'YOUR CAMPAIGN ID HERE', 'Points to add');
        print_r($addPoints);
                                

Example Response

{
        "result": "success",
        "message": "Point is successfully added"
        }

This POST request adds points in user profile.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.


lead_id

The lead ID is user ID to whom you want to add points. This field is required.


points

The points to add. This field is required.

2.6Get Contact Details By Email #

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'get_lead_details_by_email',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE',
            'email' => 'Your Email Address HERE'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'get_lead_details_by_email',
                 'campaign_id': 'YOUR CAMPAIGN ID HERE',
                 'email' : 'Your Email Address HERE',
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                    
<?php

        $upviral = new Upviral\SDK('YOUR API KEY HERE');                                        
        
        $getContact = $upviral->getContact('Your Email Address HERE', 'YOUR CAMPAIGN ID HERE');
        print_r($getContact);
                                

Example Response

{
        "result" : "success",
        "lead_details" : 
         { 
            "id" :"3162",
            "name" : "Joe",
            "email" : "[email protected]",
            "status": "enable",
            "created_date" : "2018-05-31 16:10:26",
            "total_points" : "1",
            "is_fraud" : "0",
            "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
            "custom_fields" : 
            {
                "field1" : "value1",
                "field2" : "value2"
            },
            "campaigns" :[
             {
                "campaign_id " : "489",
                "campaign_name ": "Hosted blank template"
             }
            ],
            "referred_by ":null,
            "referrals ":[]
          }
        }

This POST request gets contact details.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.


email

The email address. This field is required.


RESPONSE PARAMETERS

is_fraud

If a lead is fraudulent, it will return 1 else it will be 0.

3.Custom Fields #

To get a list of available custom fields in a campaign.

3.1Get All Custom Fields #

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'get_custom_fields',
            'campaign_id' => 'YOUR CAMPAIGN ID HERE'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'get_custom_fields',
                 'campaign_id': 'YOUR CAMPAIGN ID HERE',
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                    
<?php

        $upviral = new Upviral\SDK('YOUR API KEY HERE');                                        
        
        $getCustomFields = $upviral->geCustomFields('YOUR CAMPAIGN ID HERE');
        print_r($getCustomFields);
                                

Example Response

{
        "result" : "success",
        "custom_fields" : [
            "Field1",
            "Field2",
            "Field3"
         ]
        }

                                

This POST request gets all custom fields of campaign.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.


campaign_id

The Campaign ID. This field is required.

4.Campaigns #

To get a list of all campaigns in your account.

4.1Get list campaigns #

Example Request

<?php
        //Set up API path and method
        $url = "https://app.upviral.com/api/v1/";
        //Create request data string
        $data = http_build_query([
            'uvapikey' => 'YOUR API KEY HERE',
            'uvmethod' => 'lists'
        ]);


        //Execute cURL request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_exec($ch);
        curl_close($ch);
                                    
        
        import requests

        address = 'https://app.upviral.com/api/v1/'
        data = { 'uvapikey': 'YOUR API KEY HERE',  
                 'uvmethod': 'lists',
                }

        r = requests.post(address, data=data)
        dt = r.json()
        print(dt['status'])

                                    
<?php

        $upviral = new Upviral\SDK('YOUR API KEY HERE');                                        
        
        $campaigns = $upviral->getCampaigns();
        print_r($campaigns);
                                

Example Response

{
        "result" : "success",
        "data" : [
            {
                "id":"520",
                "name":"Automatic winner check"
            },
            {
                "id":"462",
                "name":"Autoresponder only"
            }
          ] 
        }

                                

This POST request gets the campaign list.

ARGUMENTS

uvapikey

The unique UpViral API Key. This field is required.


uvmethod

The method name. This field is required.