API Documentation

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.1 Add Contact #

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.

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

name

The user’s name. This field is optional.

IP Address

The user’s IP Address. 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

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',
            'ip_address' => '1.1.1.1',
            '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',
                 'ip_address':'1.1.1.1',
                 'referral_code':'XXXX',
                 'custom_fields[field1]':'value1',
                 'custom_fields[field2]':'value2'
                }

        r = requests.post(address, data=data)

<?php
        $upviral = new Upviral\SDK('YOUR API KEY HERE');
                                            
        $contact = new \Upviral\Entity\Contact();
        $contact->name = 'Joe';
        $contact->email = 'Your Email Address HERE';
        $contact->ip_address = '1.1.1.1';
        $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": "example@xyz.com"
        }

2.2 Get Contact Details #

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.

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" : "example@xyz.com",
            "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 ":[]
          }
        }

2.3 Get All Contact Details #

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.

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" : "example@xyz.com",
                    "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" : "example1@xyz.com",
                    "status": "enable",
                    "created_date" : "2018-05-31 17:02:12",
                    "referral_link" : "http:\/\/upvir.al\/ref\/SWThoy3162\/",
                    "custom_fields" : 
                    {
                        "field1" : "value1",
                        "field2" : "value2"
                    }
                }

            ]    
        }
                                }

2.4 Get All Contact Details Filtered By Points #

Example: Searching for people with more than 10 points

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.

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

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()

<?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" : "example@xyz.com",
                "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" : "example1@xyz.com",
                "status": "enable",
                "total_points": "10",

2.5 Add Points #

Add other points.

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.

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"
        }

2.6Get Contact Details By Email #

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.

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.

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" : "example@xyz.com",
            "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 ":[]
          }
        }

3.Custom Fields #

This POST request gets all custom fields of campaign.

3.1Get All Custom Fields #

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.

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"
         ]
        }

4.Campaigns #

To get a list of all campaigns in your account.

4.1Get list campaigns #

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.

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"
            }
          ] 
        }

UpViral API Documentation

1.Introduction #

2.Contact #

2.1 Add Contact #

2.2 Get Contact Details #

2.3 Get All Contact Details #

2.4 Get All Contact Details Filtered By Points #

2.5 Add Points #

2.6Get Contact Details By Email #

3.Custom Fields #

3.1Get All Custom Fields #

4.Campaigns #

4.1Get list campaigns #