Publisher API v2
Introduction Requirements Access and Authorization Models

Introduction

This API is intended for customers that want an integrated access with our platform.

The information presented in this documentation should help specialized personnel from the concerned party to:

  • Connect to the platform and provide credentials for authorization purposes
  • Present and describe the various data sets available
  • Obtain information and examples on how to query these data sets
  • Obtain information and examples on how to query these data sets

Requirements

  • Ability to connect through HTTPS
  • An API Key (Secret), which is a randomly generated unique string and a Client Id. They will be issued to you through the Qverse Portal or by contacting your Account Manager.

Access and Authorization

Connect to the API endpoint using the following base address: https://pub-api.qverseads.com/v2

Authorization can be achieved using two query string parameters that you have to insert in every request: apiClientId and secret, that are issued to you through the Qverse Portal or by contacting your Account Manager.

Example:

https://pub-api.qverseads.com/v2/get-campaigns?apiClientId=qvapi&secret=vA6VSwGS1TTqGKq8WDFhk_aziSMVp0_vxIRqrankZKM

API Constraints

Requests Limit

The API is limited to 50 requests per 10 seconds, if you exceed this rate limit you will receive a text response: API calls quota exceeded! maximum admitted 50 per 10s and 429 HTTP status code.

If this error is a regular occurrence, you can contact your account manager to discuss increasing your rate limit.

Response Limit

By default, the number of campaigns returned in a response is 50. To modify this limit, see Filtering, Sorting and Paging section.

Using Qverse Publisher API

Response Structure

The HTTPS response to an API call is a JSON object containing:

{
   "responseCode": 0,
   "message": "Success",
   "data": null,
   "errorDetails": null
}
  • responseCode: Code (integer value) corresponding to the success/error response (see API Error Messages
  • message: Text description of the response code
  • data: Object representing the result data of the call (see Making API Calls for possible values of the data object)
  • errorDetails: Text providing extra details for error result codes

API Error Messages

Requests made to our API can result in a number of different error responses. The following topic describes and provides a list of response codes.

The following represents a common error response resulting from a failed API request:

{
   "responseCode": 2,
   "message": "Parse Error",
   "data": null,
   "errorDetails": "Parse Error: No filter value for status field"
}
Code Message
0 Success
1 Internal Error
2 Parse Error
3 Sorting Error
4 Pagination Error
5 Invalid Operation
6 Campaign IDs Required

Filtering, Sorting and Paging

Filtering

You can use filtering to restrict the results returned to those which meet certain criteria. Not all fields can be filtered (see Models).

The default operator for filters is an equality filter that limits results to those models with a field matching a single value. For example, if you wish to retrieve Campaigns whose status is ‘active’ and whose country is USA the following filters can be used:

                    &filters[status]=active&filters[country]=US
                

The default behavior for filters is to ‘AND’ the conditions. It is possible to make an ‘OR’ operation, but it applies only to operands of the same type. For example, if you wish to retrieve Campaigns whose country is USA or Germany you must add the ‘[OR]’ block to the filters:

                   &filters[country][OR]=US&filters[country][OR]=DE
                

NOTE: For filtering by properties that are specified in Models section as dictionaries (have a predefined list of accepted values) please use only values from the associated table. Example:

                  &filters[restriction]=Fraud / Bot
                

Other Filter Operators:

  • LESS_THAN – Finds campaigns which have a value less than the provided value
                               &filters[payout][LESS_THAN]=3
                             
  • LESS_THAN_OR_EQUAL – Finds campaigns which have a value less than or equal to the provided value
                              &filters[payout][LESS_THAN_OR_EQUAL]=3
                             
  • GREATER_THAN – Finds campaigns which have a value greater than the provided value
                              &filters[payout][GREATER_THAN]=3
                             
  • GREATER_THAN_OR_EQUAL – Finds campaigns which have a value greater than or equal to the provided value
                                 &filters[payout][GREATER_THAN_OR_EQUAL]=3
                             
  • LIKE – Returns campaigns which have a value that matches the provided string of the filter. LIKE operator supports ‘%’ wildcard: used at the beginning of the string will find values ending in that string, at the end of the string will find values beginning with that string, at both the beginning and the ending of the string will find values that contains that string.

    Example: Returns Campaigns whose names begin with ‘Golden Knights’:

                               &filters[name][LIKE]=Golden Knights%
                             

    Example: Returns Campaigns whose names have ‘Knights’ in them:

                               &filters[name][LIKE]=%Knights%
                             

NOTE: Search using LIKE operator is case-insensitive and if you don’t use a wildcard, the call returns only values that match the provided string.

Sorting

Sorting is determined using the ‘sort’ query string parameter. The format of a sort parameter is an object having keys identifying the model field name and values specifying the direction, either ‘asc’ for ascending or ‘desc’ for descending.

Example:

                      &sort[payout]=desc
                

NOTE: Not all fields are sortable. (see Models)

Paging

Pagination can be implemented using one or both of two query parameters:

  • limit – number of items returned in the response; must be an integer
  • page – the result set to return; must be an integer

Example:

                 &limit=50&page=2
             

NOTE: By default, the response limit is 50 campaigns per call.

Making API Calls

API calls are handled as HTTPS requests returning JSON response objects.

An API call consists of the version of the API (currently version 2), the endpoint you want to call, the authentication details and optionally, the parameters you want to pass. Example:

https://pub-api.qverseads.com/v2/get-campaigns?apiClientId=CLIENTID&secret=SECRET

This call returns first 50 (default limit) available campaigns.

Retrieve available campaigns

API calls to get all our available campaigns are performed according to the actions and formats below:

You can add parameters to specify what values to filter for or sort by. For example, if you wish to return the first ten active campaigns that have a payout greater than 2.5 form the call like so:

https://pub-api.qverseads.com/v2/get-campaigns?apiClientId=CLIENTID&secret=SECRET&filters[status]=active&filters[payout][GREATER_THAN]=2.5&limit=10

NOTE: If a campaign is no longer available, it will disappear from the feed.

The HTTPS response to a call that retrieves our available campaigns is a JSON object containing:

{
   "responseCode": 0,
   "message": "Success",
   "data": {
      "campaigns":[],
      "blacklistedSubPublishers":[]
   },
   "errorDetails": "Parse Error: No filter value for status field"
}

The data object contains a list of campaigns and a list of blacklisted Sub-Publishers (all their traffic is being rejected). See Models section for more information.

Apply for Campaigns

API calls to to apply for our campaigns are performed according to the actions and formats below:

To be able to apply for specific campaigns you must provide in the request body a JSON array of one or more integers representing the campaign IDs you want to apply for.

Example of such an array:

NOTE: The Content-Type entity header must be set to application/json.

To be able to apply for a filtered subset of our available campaigns you must add filter parameters to specify the subset of campaigns you want to apply for.

Example: Apply for all campaigns that have a payout greater than 2 and whose country is USA:

https://pub-api.qverseads.com/v2/apply-for-all-campaigns?apiClientId=CLIENTID&secret=SECRET&filters[payout][GREATER_THAN]=2&filters[country]=US

If no filters are provided the default action is to apply for all available campaigns.

NOTE: After you apply using one of the methods presented above, some of your applications will be directly approved, denied or sent to be approved by your account manager. To see this information please see the HTTPS response from that call.

The HTTPS response to a call to apply for our available campaigns is a JSON object containing:

{
   "responseCode": 0,
   "message": "Success",
   "data": {
      "approvedCampaignIds":[],
      "deniedCampaignIds":[],
      "pendingApprovalCampaignIds":[]
   },
   "errorDetails": null
}

The data object contains:

  • approvedCampaignIds – list of campaign IDs that were directly approved
  • deniedCampaignIds – list of campaign IDs that were denied
  • pendingApprovalCampaignIds – list of campaign IDs that were sent to approval

Models

Campaign Model:

Name Type Filter Name Sortable Description
campaignId Integer campaign_id The unique identifier of the campaign
name String name Campaign name
thumbnail String - The URL to download the campaign thumbnail
previewLink String - The URL of the app
impressionTrackingLink String - Impression tracking link of approved application
payoutType String payout_type The type of conversion event; See payout type info
vertical String vertical See vertical info
payouts Dictionary(String, Decimal) payout Campaign payouts for all the events
dailyCap Integer daily_cap Number of installs allowed per day
dailyCapPercentage Decimal daily_cap_percentage Campaign daily cap percentage
dailyCapReached Boolean daily_cap_reached Representing if a campaign reached its daily cap
totalCap Nullable Integer total_cap Campaign total number of installs allowed
description String - Campaign description
trackingLink Nullable String - Tracking link of approved application
dateAdded DateTime - Creation date of the campaign in the Qverse system
dateApproved Nullable DateTime - Date of your approved application
status String status See statuses info
countries Array country Array of ISO ALPHA-2 campaign country codes
cities Array - Array of campaign cities
operatingSystems Array operating_system See operating systems info
restrictions Array restriction See restrictions info
categories Array category See categories info
creatives Array - Creatives URLs
banners Array - Banners URLs

Vertical values:

Name
Adult
Mainstream

Campaign status values:

Name Description
Active Campaign is active, no application
Approved You have been approved on that campaign
Pending Your application on that campaign is being verified by your account manager
Denied Your application on that campaign has been denied

Restriction values:

Name
All
Incent
Adult
Fraud / Bot
Pop (Up/Under)
Auto Redirects
Email
Invalid / Duplicate Leads
App Discovery
App Wall
Wifi
Re-brokering
Own Creatives
App Discovery
Misleading Advertising

Payout Type values:

Name
CPA
CPI
CPL
CPM
CPR
CPE

Category values:

Name
Mainstream
Adult
Dating
CPI
CPA
CPR
CPE
CPL
Incent
Non-Incent
Android
iOS
Windows
Mobile
Desktop
All Devices

Operating System values:

Name
Feature Phone
Android
iOS
Windows Phone
Blackberry
Windows PC
Mac
Linux
All
Other