CPV Lab Pro Documentation

CPV Lab Pro API

API Start

  • The API offers endpoints for data retrieval, for Landing Pages management, for Offers management and for campaign setup management.

  • The API endpoints respond to both GET and POST requests.

API Results Format

  • The API can return results in 2 popular formats that can be easily integrated with other tools:

    • JSON (JavaScript Object Notation) – the default format
    • XML (Extensible Markup Language)

  • You can choose the desired format for results using the “format” parameter passed in the API call with one of the 2 values: “json” or “xml”.

API Authentication

  • In order to prevent unauthorized access to the API and the data from the CPV Lab Pro database the API is protected by a unique API Key that you will define in the General Settings page from the CPV Lab Pro interface.
  • By default the API is disabled, so you need to check the ‘Enable API Access’ box and then define a unique API Key. You can also click on the ‘Generate’ button to generate a new API Key.

API Access

  • If no API Key is passed in the API requests or if the API Key is incorrect, then the following response is received:

Api No Access

API Requests Structure

  • The API receives parameters that customize the results returned or that perform changes in campaigns.
  • The API listens to both GET and POST requests which means that the parameters can be passed in 2 different ways (the order of the parameters doesn’t matter):
      1. For GET requests the parameters are appended to the API URL like: -http://domain.com/api/stats/?parameter1=value1&parameter2=value2
      1. For POST requests the parameters are passed in the request body like:
      • parameter1=value1&parameter2=value2

Allowed parameters

  • Each API call must contain the API Key value passed in the “key” parameter. This is a mandatory parameter and it is needed to authenticate requests.

Each API endpoint can receive optional parameters specific to its functionality which are described below.

Data Retrieval Endpoints

1. Stats API Endpoint

  • returns the rows in the tables from the Stats page for a campaign.

  • Parameters allowed:

    • camp – the Campaign ID to get data for – mandatory parameter
    • format – the format of the results, either “json”, either “xml”
    • report – a list of the reports that can be returned separated by commas.
      • You can add one or multiple values from this list: all, target, ad, landing, thankyou, offer, campaign.
    • start – the start date for the returned records in YYYY-MM-DD format; if not passed the start date is the beginning of the current day
    • end – the end date for the returned records in YYYY-MM-DD format; if not passed the end date is the end of day today
    • qv – the ID of the Quick View that should be used to determine which columns are included in the Target Performance report returned.
      • The Target Performance report can return data grouped in multiple ways based on the visible columns, so you can control how data are returned and which columns are visible with a Quick View (exactly like in the Stats page).
      • You need to pass a valid Quick View ID corresponding to a view from the Quick-Stat Views page under the Settings menu. If no value is passed, then the default Quick-View is used.
    • grcols - a list of columns that will be used to group data after in the Target Performance report. Breakdown data by any tokens that you have captured in your campaigns.
      • For example, if you want to group data after Keyword Token and Extra Token 1, then pass in the API call: &grcols=Keyword,Extra1
      • And if you want to return data grouped by the Ad Token, then pass in the API call: &grcols=AdValue
      • Possible values that can be included in the 'grcols' parameter (multiple values should be separated by comma): Keyword, AdValue, CampaignID, Extra1, Extra2... Extra15, Offer, Offer2 (where Offer is the Landing Page and Offer2 is the Offer Page)

  • extra – when it has “1” as value, it will include the Extra Token columns in the Ad Performance report returned

  • timezone (optional) - when passed, it will return data in this timezone - By default you get data returned in the user timezone specified in the General Settings page from CPV Lab Pro. - If you want to retrieve data in a different timezone, then pass that timezone in this "timezone" parameter - Valid values for the "timezone" parameter are the ones from here: https://www.php.net/manual/en/timezones.php

  • Sample request POST method:

POST /api/stats/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&camp=271&report=target,ad,landing&start=2018-07-13&end=2018-07-15&extra=1&qv=18
  • Sample request GET method:
http://cpvlabpro-domain.com/api/stats/?key=secret-key&camp=271&report=target,ad,landing&start=2018-07-13&end=2018-07-15&extra=1&qv=18

  • The parameters passed in both requests are:

    • key – the campaign secret key defined in the General Settings page
    • camp – the Campaign ID (271)
    • report – a list with the reports that will be returned (target, ad and landing)
    • start – the start date (2018-07-13)
    • start – the start date (2018-07-13)
    • end – the end date (2018-07-15)
    • extra – value of “1’ to include the extra columns
    • qv – the ID of the Quick-Stat View to use for the columns of the Target Performance report (18)

  • Such an API request will return a result like in the image below (left side is JSON, right side is XML)

API Stats Endpoint results

2. Conversion List API Endpoint

  • returns the list of conversions for a campaign or all campaigns

  • Parameters allowed:

    • camp – the Campaign ID to get data for or 0 to get conversions for all campaigns
    • format – the format of the results, either “json”, either “xml”
    • start – the start date for the returned records in YYYY-MM-DD format; if not passed the start date is the beginning of the current day
    • end – the end date for the returned records in YYYY-MM-DD format; if not passed the end date is the end of day today
    • cols – specifies which columns to return;
      • allowed values are:
        • “default” – the default columns
        • “all” – all available columns
        • “current” – the visible columns from the Conversion List page

  • Sample request POST method:

POST /api/conversions/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&camp=271&start=2016-01-01&end=2018-01-01&cols=default
  • Sample request GET method:
http://cpvlabpro-domain.com/api/conversions/?key=secret-key&camp=271&start=2016-01-01&end=2018-01-01&cols=default

  • The parameters passed in both requests are:

    • key – the campaign secret key defined in the General Settings page
    • camp – the Campaign ID (271)
    • start – the start date (2016-01-01)
    • end – the end date (2018-01-01)
    • cols – the columns to return (default)

  • Such an API request will return a result like in the image below (left side is JSON, right side is XML)

API Conversion List Endpoint

3. Visitor Stats API Endpoint

  • returns the list of the latest visitors for a campaign or all campaigns

  • Parameters allowed:

    • camp – the Campaign ID to get data for or 0 to get conversions for all campaigns
    • format – the format of the results, either “json”, either “xml”
    • start – the start date for the returned records in YYYY-MM-DD format; if not passed the start date is the beginning of the current day
    • end – the end date for the returned records in YYYY-MM-DD format; if not passed the end date is the end of day today
    • cols – specifies which columns to return;
      • allowed values are:
        • “default” – the default columns
        • “all” – all available columns
        • “current” – the visible columns from the Conversion List page
    • rec – maximum number of records to return; useful when having high traffic to limit the number of rows returned

  • Sample request POST method:

POST /api/visitorstats/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&camp=0&start=2018-07-11&end=2018-07-11&rec=100&cols=current
  • Sample request GET method:
http://cpvlabpro-domain.com/api/visitorstats/?key=secret-key&camp=0&start=2018-07-11&end=2018-07-11&rec=100&cols=current

  • The parameters passed in both requests are:

    • key – the campaign secret key defined in the General Settings page
    • camp – value of “0” means that all data from all campaign is returned
    • start – the start date (2018-07-11)
    • end – the end date (2018-07-11)
    • rec – the maximum number of records to return (100)
    • cols – the columns to return (all)

  • Such an API request will return a result like in the image below (left side is JSON, right side is XML)

API Visitor Stats

4. Subid Lookup API Endpoint

  • returns details about a specific visitor that was tracked in your campaigns based on the subID or the clickID
  • details include: Campaign Data, Geo Data, Device Data, Traffic Source Tokens, Offer Source Tokens
  • Parameters allowed:
    • Subid – the SubID (format ssssssss_ccc_nnnnnnnn) or ClickID (format nnnnnnnn) to search for
  • Sample request POST method:
POST /api/click/lookup/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&subid=ekmwpdty_5_14474
  • Sample request GET method:
http://cpvlabpro-domain.com/api/click/lookup/visitorstats/?key=secret-key&subid=ekmwpdty_5_14474

  • The parameters passed in both requests are:

    • key – the campaign secret key defined in the General Settings page
    • subid – the SubID or ClickID to retrieve data for

  • Such an API request will return a result like in the image below (left side is JSON, right side is XML)

API Subid LookupStats

5. Campaigns List Endpoint

  • returns a list with all campaigns from your CPV Lab Pro instance and details about them: campaign URL, traffic source, tokens etc.

  • Parameters allowed:

    • active (optional) - when passed with 1 as value, the API will only return the active campaigns
      • when passed with 0 as value, the API will only return the inactive campaigns
      • when ommited, the API will return all campaigns.

  • Sample request POST method:

POST /api/campaign/list/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key
  • Sample request GET method:
http://cpvlabpro-domain.com/api/campaign/list/?key=secret-key

  • The parameters passed in both requests are:

  • Such an API request will return a result like in the image below (left side is JSON, right side is XML)

API Campaign List Response

6. Traffic Sources List Endpoint

  • returns a list with all traffic sources from your CPV Lab Pro instance and their tokens

  • There are no parameters for this endpoint.

  • Sample request POST method:

POST /api/ts/list/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key
  • Sample request GET method:
http://cpvlabpro-domain.com/api/ts/list/?key=secret-key

  • The parameters passed in both requests are:

  • Such an API request will return a result like in the image below (left side is JSON, right side is XML) API Traffic Sources List

Landing Pages Management Endpoints

  • You can add, edit landing pages and also assign landing pages to campaigns through the CPV Lab Pro API.

The following endpoints are available:

1. Add Landing Page Endpoint

  • adds a new Landing Page in your CPV Lab Pro instance.
  • The page appears in the Predefined Landing Pages section from the interface.

WARNING

Please note that the Landing Page won’t be added automatically in your campaigns using this endpoint.

URL:

http://cpvlabpro-domain.com/api/lp/add/

  • Allowed Parameters (name and url are required, the others are optional):

    • name - the landing page name
    • url – the complete landing page URL (should start with http:// or https://)
    • inactive – whether the page is active or inactive (pass 0 for active and 1 for inactive)
    • notes – details or description of the landing page

  • Returns the internal landing page ID on success or an error message on failure.

  • Sample request POST method:

POST /api/lp/add/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&name=LP-from-API&url=https://lp-domain.com?page.html&inactive=0
  • Sample request GET method:
http://cpvlabpro-domain.com/api/lp/add/?key=secret-key&name=LP-from-API&url=https://lp-domain.com?page.html&inactive=0
  • Such an API request will return the internal landing page ID which can be later used to add landing pages to campaigns, like in the image below (left side is JSON, right side is XML)

API Add LP Endpoint

2. Edit Landing Page Endpoint

URL:

http://cpvlabpro-domain.com/api/lp/edit/

  • Allowed Parameters (id is required, the others are optional):

    • id – required, represents the internal Landing Page ID to edit
    • name – the landing page name
    • url – the complete landing page URL (should start with http:// or https://)
    • inactive – whether the page is active or inactive (pass 0 for active and 1 for inactive)
    • notes – details or description of the landing page

  • Returns the internal landing page ID on success or an error message on failure.

  • Sample request POST method:

POST /edit/lp/edit/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&id=6&name=LP-from-API&url=https://lp-domain.com?page.html&inactive=0
  • Sample request GET method:
http://cpvlabpro-domain.com/api/lp/edit/?key=secret-key&id=6&name=LP-from-API&url=https://lp-domain.com?page.html&inactive=0
  • Such an API request will return the internal landing page ID on success, like in the image below (left side is JSON, right side is XML)

API Edit LP Endpoint

3. Add Landing Page to Campaign Endpoint

  • adds an existing Predefined Landing Page or a new Landing Page to an existing CPV Lab Pro campaign.

URL:

http://cpvlabpro-domain.com/api/lp/addtocamp/

  • Allowed Parameters:

    • campaignid – the ID of the campaign to add the landing page to;
    • id – if adding an existing Predefined Landing Page, then pass its internal ID in this parameter;
    • name – the landing page name (only if adding a new LP);
    • url – the complete landing page URL (should start with http:// or https://) (only if adding a new LP)
    • inactive – whether the page is active or inactive (pass 0 for active and 1 for inactive) (only if adding a new LP)
    • share – the share percentage of the LP
    • pageid – the given ID for the LP in this campaign
    • level – the level for the LP, only if adding in a Landing Page Sequence campaign
    • path – the path for the LP, only if adding in a Multiple Path Campaign or Email FollowUp campaign

  • Sample request POST method:

    1. add a Predefined Landing Page
POST /api/lp/addtocamp/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&campaignid=1&id=6&share=10
    1. add a new Landing Page
POST /api/lp/addtocamp/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&campaignid=1&name=LP-from-API&url=https://lp-domain.com?page.html&inactive=0&share=10
  • Sample request GET method:
    1. add a Predefined Landing Page
http://cpvlabpro-domain.com/api/lp/addtocamp/?key=secret-key&campaignid=1&id=6&share=10
    1. add a new Landing Page
http://cpvlabpro-domain.com/api/lp/addtocamp/?key=secret-key&campaignid=1&name=LP-from-API&url=https://lp-domain.com?page.html&inactive=0&share=10
  • Such an API request will return OK on success or an error message if something isn’t correct, like in the image below (left side is JSON, right side is XML)

API add LP to campaign Endpoint

Offers Management Endpoints

  • You can add, edit offers and also assign offers to campaigns through the CPV Lab Pro API.

The following endpoints are available:

1. Add Offer Endpoint

  • adds a new Offer in your CPV Lab Pro instance.
  • The page appears in the Predefined Offers section from the interface. Please note that the Offer won’t be added automatically in your campaigns using this endpoint.

URL:

http://cpvlabpro-domain.com/api/offer/add/
  • Allowed Parameters (name and url are required, the others are optional):
    • name – the offer page name
    • url – the complete offer URL (should start with http:// or https://)
    • inactive – whether the offer is active or inactive (pass 0 for active and 1 for inactive)
    • source – the offer source (affiliate network), should be one of the available Offer Sources in your CPV Lab Pro instance
    • payout – the payout (revenue) of your offer
    • notes – details or description of the offer
  • Returns the internal offer ID on success or an error message on failure.
  • Sample request POST method:
POST /api/offer/add/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&name=Offer-from-API&url=https://offer-domain.com?page.html&payout=11.50
  • Sample request GET method:
http://cpvlabpro-domain.com/api/offer/add/?key=secret-key&name=Offer-from-API&url=https://offer-domain.com?page.html&payout=11.50
  • Such an API request will return the offer ID which can be later used to add offers to campaigns, like in the image below (left side is JSON, right side is XML)

API add Offer Endpoint

2. Edit Offer Endpoint

URL:

http://cpvlabpro-domain.com/api/offer/edit/

  • Allowed Parameters (id is required, the others are optional):

    • id – required, represents the internal Offer ID to edit
    • name – the offer page name
    • url – the complete offer URL (should start with http:// or https://)
    • inactive – whether the offer is active or inactive (pass 0 for active and 1 for inactive)
    • source – the offer source (affiliate network), should be one of the available Offer Sources in your CPV Lab Pro instance
    • payout – the payout (revenue) of your offer
    • notes – details or description of the offer

  • Returns the internal offer ID on success or an error message on failure.

  • Sample request POST method:

POST /api/offer/edit/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&id=6&name=Offer-from-API&url=https://offer-domain.com?page.html&payout=11.50
  • Sample request GET method:
http://cpvlabpro-domain.com/api/offer/edit/?key=secret-key&id=6&name=Offer-from-API&url=https://offer-domain.com?page.html&payout=11.50
  • Such an API request will return the internal offer ID on success, like in the image below (left side is JSON, right side is XML)

API add Offer Endpoint

3. Add Offer Page to Campaign Endpoint

  • adds an existing Predefined Offer or a new Offer to an existing CPV Lab Pro campaign. URL:
http://cpvlabpro-domain.com/api/offer/addtocamp/

  • Allowed Parameters:

    • campaignid – the ID of the campaign to add the offer to
    • id – if adding an existing Predefined Offer, then pass its internal ID in this parameter
    • name – the offer page name (only if adding a new Offer)
    • url – the complete offer URL (should start with http:// or https://) (only if adding a new Offer)
    • source – the offer source (affiliate network), should be one of the available Offer Sources in your CPV Lab Pro instance (only if adding a new Offer)
    • payout – the payout (revenue) of your offer (only if adding a new Offer)
    • inactive – whether the page is active or inactive (pass 0 for active and 1 for inactive) (only if adding a new Offer)
    • share – the share percentage of the Offer
    • pageid – the given ID for the Offer in this campaign
    • path – the path for the Offer, if adding in a Multiple Path Campaign or Email FollowUp campaign, or the Option Group, if adding in a Landing Page Sequence or Multiple Option campaign

  • Returns OK on success or an error message on failure.

  • Sample request POST method:

    1. add a Predefined Offer
POST /api/offer/addtocamp/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&campaignid=1&id=8&share=10
    1. add a new Offer
POST /api/offer/addtocamp/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&campaignid=1&name=Offer-from-API&url=https://offer-domain.com?page.html&payout=11.50&share=10
  • Sample request GET method:
    1. add a Predefined Offer
http://cpvlabpro-domain.com/api/offer/addtocamp/?key=secret-key&campaignid=1&id=8&share=10
    1. add a new Offer
http://cpvlabpro-domain.com/api/offer/addtocamp/?key=secret-key&campaignid=1&name=offer-from-API&url=https://offer-domain.com?page.html&payout=11.50&share=10
  • Such an API request will return OK on success or an error message if something isn’t correct, like in the image below (left side is JSON, right side is XML)

API add Offer Endpoint

Campaign Management Endpoints

  • You can edit the campaign options or the pages (landing pages and offers) from a campaign through the CPV Lab Pro API.

The following endpoints are available:

1. Edit Campaign Options Endpoint

  • allows changing the options of an existing campaign

URL:

http://cpvlabpro-domain.com/api/campaign/edit/
  • Parameters allowed (all parameters except campaignid are optional):
    • campaignid – required, the ID of the campaign to edit
    • engage – the new Engage Rate
    • bid – the new Bid/Cost
    • priority – the new campaign Priority
    • passsubidlp – whether to pass the subID to the Landing Page or not (1 to pass, 0 to not pass)
    • passsubidoffer – whether to pass the subID to the Offer or not (1 to pass, 0 to not pass)
  • Returns OK on success or an error message on failure.
  • Sample request POST method:
POST /api/campaign/edit/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&campaignid=1&engage=5&bid=0.25
  • Sample request GET method:
http://cpvlabpro-domain.com/api/campaign/edit/?key=secret-key&campaignid=1&engage=5&bid=0.25
  • Such an API request will return OK on success or an error message if something isn’t correct, like in the image below (left side is JSON, right side is XML)

API add Offer Endpoint

2. Edit Page from Campaign Endpoint

  • allows editing a landing page or an offer from an existing campaign

URL:

http://cpvlabpro-domain.com/api/campaign/editpage/

  • Parameters allowed (all parameters except campaignid and pageid are optional):

    • campaignid – required, the ID of the campaign to edit
    • pageid – required, the given ID of the page to edit from the campaign specified in the campaignid parameter
    • name – the new page name
    • url – the complete landing page URL (should start with http:// or https://)
    • inactive – whether the page is active or inactive (pass 0 for active and 1 for inactive)
    • share – the share percentage of the page
    • level – the level for the page, only if you want to move the landing page on another level
    • path – the path for the LP, only if you want to move the landing page or offer in a new path in a Multiple Path Campaign or Email FollowUp campaign, or if you want to move the offer in a new option group in a Landing Page Sequence or Multiple Option campaign
    • source – the offer source (affiliate network), should be one of the available Offer Sources in your CPV Lab Pro instance
    • payout – the payout (revenue) of the offer
    • newpageid – the new give Landing Page or Offer ID, only if you want to change the existing ID

  • Returns OK on success or an error message on failure.

  • Sample request POST method:

POST /api/campaign/editpage/ HTTP/1.1
Host: cpvlabpro-domain.com
key=secret-key&campaignid=1&pageid=6&url=http://lp-domain/new-lp.html&share=20
  • Sample request GET method:
http://cpvlabpro-domain.com/api/campaign/editpage/?key=secret-key&campaignid=1&pageid=6&url=http://lp-domain/new-lp.html&share=20
  • Such an API request will return OK on success or an error message if something isn’t correct, like in the image below (left side is JSON, right side is XML)

API add page from campaign Endpoint

Last Updated: 10/11/2023, 10:35:00 AM

← “Templating” Campaigns →