Follow

Caps Management via API

Time to read: 10 min.

topic.pngThe article covers the following topics:

General Info

First of all, to get started with API, you need to find your API-key. To do it, just navigate to the 'Users' Tab - > 'Users management' -> 'User edit page':

CommonAPI.png

import.pngOnly the General manager has permission to get the 'User edit page'. 

Next thing you need is API URL, you can find it in the 'Settings' Tab -> 'Settings' -> 'Tracking domains' -> 'URLs' section:

API_link.png

click__1_.pngFind out more about where you can find your/Affiliate's API-key and API URL here

API Request Structure: GET/POST + api domain + path + ? + api-key=189471975956279174174.

It should be noted that header content-type - application/x-www-form-urlencoded is used on an ongoing basis.

How to create an offer with caps: general rules

To create a new offer with Caps via API, you need to navigate to the 'Offers' section in the API Doc and choose the 'Add offer' method (follow the link):

APIdoc.gif

Here you may see many parameters that you can use to create a new offer.

These parameters are required:

  • title - Offer title
  • advertiser - Advertiser ID
  • url - Tracking URL
  • payout - at least one general payout. Check this article out to learn how to do it.

Example on how to add a new offer with Caps via API:

1) First of all, make sure that headers are entered correctly: 

Capcreation1.png

2) Enter required and all needed parameters in the body section: 

Capcreation2.png

Where, 

  • caps[0][period] - a timeframe when the cap option is enabled. Possible values: hour (if enabled), day, month, all;
  • caps[0][type] - a parameter that denotes the value, which the cap is limited by. Possible values:  budget, conversions, clicks;
  • caps[0][value] - the actual limit’s measure;
  • caps[0][goal_type] - a parameter, that is used for determination when cap’s limit is reached. It may be:  “all”, “each”, “exact”;

import.png  For [goal_type] = exact it is mandatory to specified [goals][] = your_goal_value_here parameter with a specific goal value.

  • caps[0][affiliate_type] -  an affiliate, the cap is chosen for. It may be: “all”, “each”, “exact”;

import.png  For [affiliate_type] = exact it is mandatory to specified [affiliates][] = affiliate's_id_here parameter with a specific Affiliate's ID.

  • caps[0][country_type] - specific country which cap settings should be applied to. It may be: “all” , “each”, “exact”;

import.png  For [country_type] = exact it is mandatory to specified [country][] = country_code_here parameter with a specific country code. To Get countries list you may use GET /3.1/countries method. 

  • caps_status[0] - conversion status for cap count;
  • is_redirect_overcap -  allow overcap. Possible values: 0 - logical "no", 1- logical "yes".

cURL Request

The expample of offer creation with caps via cURL request:

curl --location --request POST 'https://api-rocketcompany.affise.com/3.0/admin/offer' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api-key: bf09c801ff9b95b14ac8e17d6e4904b6' \
--data-urlencode 'title=OFFER WITH Caps' \
--data-urlencode 'advertiser=5e39279bac611cda7e5765ab' \
--data-urlencode 'url=https://track.gjane.com/hc/click?afclick={clickid}&afpid={pid}&afoffer={offer_id}' \
--data-urlencode 'caps[0][period]=day' \
--data-urlencode 'caps[0][type]=conversions' \
--data-urlencode 'caps[0][value]=150' \
--data-urlencode 'caps[0][goal_type]=all' \
--data-urlencode 'caps[0][affiliate_type]=all' \
--data-urlencode 'caps[0][country][]=DE' \
--data-urlencode 'caps[0][country_type]=exact' \
--data-urlencode 'caps_status[0]=confirmed' \
--data-urlencode 'caps_status[1]=pending' \
--data-urlencode 'caps_status[2]=hold' \
--data-urlencode 'is_redirect_overcap=1'

Cap Settings: Overcap

Overcap allows managing traffic flow when the cap is reached. It is located here in the UI:

Overcap.png

To turn Overcap on/off use the is_redirect_overcap parameter:

image.png

  • 0 - the overcap is OFF
  • 1 - the overcap is ON

The example as cUrl:

  --data is_redirect_overcap=1 \

import.png It is not possible to save the offer with 'Overcap' flag ON if there are no cap rules at all.

Cap Settings: Default goal cap

Default goal Overcap allows managing traffic flow when the desired goal is reached. It is located here in the UI:

Default_goal.png

To indicate the default goal use the caps_goal_overcap parameter:

image__1_.png

You need to indicate the goal value (not title). The goal must be presented in the offer.

The example as cUrl:

    --data caps_goal_overcap=install \

Cap Settings: Hide caps in partner interface

Hide caps in partner interface flag allows you to hide all cap rules on the offer page in the Affiliate (Partner) panel. It is located here in the UI:

Hide_caps.png

To turn the flag on/off use the hide_caps parameter:

image__2_.png

  • 0 - the flag is OFF
  • 1 - the flag is ON

The example as cUrl:

  --data hide_caps=1 \

Cap Settings: Timezone

Timezone is a time zone the cap is selected for.  It is located here in the UI:

Timezone.png

To enable Timezone for caps via API is possible to use caps_timezone parameter:

image__3_.png

You need to insert the timezone as continent/city: 'Africa/Accra' or 'Asia/Dubai'

The example as cUrl:

  --data caps_timezone=Europe/Moscow \

 

Cap Settings: Conversion status for caps count

The option allows us to set up conversions' statuses for caps. It is located here in the UI:

ConvStatus.png

To indicate conversions status, which will be counted for caps use the caps_status parameter:

image__4_.png

  • Confirmed = Approved
  • Declined = Declined
  • Hold = Hold
  • Pending = Pending

The example as cUrl:

  --data 'caps_status[0]=confirmed' \
  --data 'caps_status[1]=pending' \
  --data 'caps_status[2]=hold' \
  --data 'caps_status[3]=declined' \

Caps and API for affiliates

Affiliates can get the list of offers via two methods:

https://api.affise.com/docs3.1/#offer-list
https://api.affise.com/docs3.1/#live-offer-list

The first one allows getting the whole list of active offers with Public and Premoderation statuses. The second one allows getting the list of offers already used by a particular affiliate (it means the affiliate has at least 1 click for the last 30 days for all of those offers).

However, if offers available via both methods have caps, then not all of them may be depicted in the response.

The affiliate will get offers, where:

  • Cap for All affiliates isn't reached
  • Cap for Each affiliate isn't reached for this particular affiliate
  • Cap for Select affiliate isn't reached

This logic works in case if there are several cap rules - then several points can be applied at once.

There are also two parameters, which allows him to limit the number of received offers according to whether relevant caps are reached or not:

  • caps_types
  • caps_countries

Caps types

The parameter filters offers according to the types of cap rules: clicks/conversions/budget.

The affiliate will get only offers, where:

  1. Filter by one type: 
    1. Offers, which don't contain this type of cap.
    2. Offers, which contain this type, but this cap isn't reached.
  2. Filter by two types:
    1. Offers, which don't contain these types of cap.
    2. Offers, which contain both types, but both ones aren't reached.
  3. Filter by three types:
    1. Offers, which don't contain all types of cap.
    2. Offers, which contain cap rules with any types and all of them aren't reached.

Caps countries

The parameter filters offers according to the countries existent in cap rules.

The affiliate will get only offers, where:

  1. Cap for All countries isn't reached.
  2. Cap for a chosen country (US, RU, FR, etc.) isn't reached. If the parameter contains 2 or more countries, then caps for all of them should not be reached.

If the affiliate uses only one parameter and can get offers, however, the second parameter would not allow receiving them, he will do it anyway. For example: the filter by country is applied and 1000 offers are available. If the affiliate has applied filter by caps types also, he would have received only 500 offers, however, he didn't apply the second filter, so totally he has 1000 offers available.

article.pngYou may also find the following articles helpful:

If you still have any questions left on Cap management via API, feel free to address them to Affise Technical Support Team via support@affise.com  as long as to contact your Dedicated Account Manager.  

Written by Lizaveta Talkachova

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.