Skip to main content
Campaign Pull - API Document

App Samurai “Campaign Pull API” is designed for our traffic partners to pull campaigns which are made available for that specific partner.

Furkan BUKAN avatar
Written by Furkan BUKAN
Updated over a week ago

The endpoint you use to pull campaign details is the unique URL as shown below:

You will be given your unique API TOKEN for endpoint URL from your account manager at App Samurai. This URL will be valid as long as you do not request a new URL.

After a request on pull API, output will include all available and active campaigns opened for you. An example of output for CPI campaigns will be as follows:

{
    "campaign_id": 1235,
    "type": "non-incent",
    "app_title": "Climbing Pirates",
    "app_category": "Games / Casual",
    "app_store_url": "https://play.google.com/store/apps/details?id=com.sickkogames.pirates",
    "app_id": "com.sickkogames.pirates",
"app_icon": "https:\/\/play-lh.googleusercontent.com\/Vt_eizbSd5GvaIwGUeL3XKaxIve682kwfWG6S5SJfsSBcQX0lQHjM6rz_mYVM8A8IAo=s180",
    "end_date": "No End Date",
    "daily_cap": 100,
    "payout_type": "cpi",
    "cpi": 1.5,
    "campaign_name": "Climbing Pirates-iOS-AE",
    "tracking_url": "TRACKING URL",
    "country": "US",
    "countries": ["US", "TR"],
    "countries_with_cities": {
      "US": {
        "cities": ["New York", "Los Angeles"]
      },
      "TR": {
        "cities": ["Ankara", "Bursa"]
      },
    },
    "platform": "android",
    "creatives": {
      "images": [
        {
          "url": "CREATIVE URL",
          "width": null,
          "height": null
        },
        {
          "url": "CREATIVE URL",
          "width": null,
          "height": null
        },
      ],
      "videos": [],
      "others": []
    },
    "creative_zip": "CREATIVE ZIP URL",
    "devices": "Both",
    "required_fields": ["ref_id"],
    "blacklisted_subpublishers": [],
    "whitelisted_subpublishers": []
  }

And for CPA campaigns will be as follows:

{
    "campaign_id": 1235,
    "type": "non-incent",
    "app_title": "Climbing Pirates",
    "app_category": "Games / Casual",
    "app_store_url": "https://play.google.com/store/apps/details?id=com.sickkogames.pirates",
    "app_id": "com.sickkogames.pirates",
"app_icon": "https:\/\/play-lh.googleusercontent.com\/Vt_eizbSd5GvaIwGUeL3XKaxIve682kwfWG6S5SJfsSBcQX0lQHjM6rz_mYVM8A8IAo=s180",
    "end_date": "No End Date",
    "daily_cap": 100,
    "payout_type": "cpa",
    "cpa_event": "purchase",
    "cpi": 1.5,
    "campaign_name": "Climbing Pirates-iOS-AE",
    "tracking_url": "TRACKING URL",
    "country": "US",
    "countries": ["US", "TR"],
    "countries_with_cities": {
      "US": {
        "cities": ["New York", "Los Angeles"]
      },
      "TR": {
        "cities": ["Ankara", "Bursa"]
      },
    },
    "platform": "android",
    "creatives": {
      "images": [
        {
          "url": "CREATIVE URL",
          "width": null,
          "height": null
        },
        {
          "url": "CREATIVE URL",
          "width": null,
          "height": null
        },
      ],
      "videos": [],
      "others": []
    },
    "creative_zip": "CREATIVE ZIP URL",
    "devices": "Both",
    "required_fields": ["ref_id"],
    "blacklisted_subpublishers": [],
    "whitelisted_subpublishers": []
  }

For multi-rewarded campaigns, it will be like below:

{
"campaign_id": 120254,
"type": "incent",
"app_title": "Sling Plane 3D",
"app_category": "Games \/ Simulation",
"app_store_url": "https:\/\/play.google.com\/store\/apps\/details?id=com.panteon.slingplane\u0026referrer=utm_source%3D42matters.com%26utm_medium%3Dapi",
"app_id": "com.panteon.slingplane",
"app_icon": "https:\/\/play-lh.googleusercontent.com\/1ou1lb0lsImbDe_zB-MGOcfEpNecMEPBS6Qu-YrCFHxvsW8oWiTt37nmfkiAANofCg=s180",
"start_date": "2023-02-07 10:56:00",
"end_date": "No End Date",
"daily_cap": 200,
"payout_type": "cpa",
"cpa_event": "multi-rewardd",
"revenue": 1.9199999999999999,
"campaign_name": "Sling Plane-120254-And_Phone-US-17Feb23-ADRP",
"tracking_url": "https:\/\/click.appsamurai.com\/api\/callbacks\/click?sub_campaign_id=-QgfS_K1qCUvn5PP_vEmq-6E_kcvaJbe\u0026extra_1={userid}",
"offer_name": "Reach Distance 1200, 4200, 8200 and 10200 m",
"conversion_requirement": "Reach Distance 1200, 4200, 8200 and 10200 m",
"country": "US",
"countries": [
"US"
],
"countries_with_cities": {
"US": {
"cities": [

]
}
},
"platform": "play",
"devices": "Phone",
"required_fields": [
"ref_id"
],
"currency_multiplier": 50,
"in_app_title": "Reach Distance 1200, 4200, 8200 and 10200 m",
"event_goal": [
{
"event_name": "max_distance_reached_1000",
"cpi_bid": "0.35",
"event_token": "Reach distance 1200m"
},
{
"event_name": "max_distance_reached_4000",
"cpi_bid": "0.36",
"event_token": "Reach distance 4200m"
},
{
"event_name": "max_distance_reached_8000",
"cpi_bid": "0.5",
"event_token": "Reach distance 8200m"
},
{
"event_name": "max_distance_reached_10000",
"cpi_bid": "0.72",
"event_token": "Reach distance 10200m"
}
],
"received_events": [

],
"pin": false
},

Definition of parameters

campaign_id: App Samurai internal campaign ID
type: Campaign type (incent OR non-incent)
app_title: Store title of the application
app_category: Store category and subcategory (If Available)
app store url: App Store or Google Play url of the application
app_id: Unique store ID
end_date: Campaign end date
daily_cap: Max number of cap available to the partner
cpi: Cost per install bid that you can charge for each install+first open you deliver
campaign_name: Name of the campaign at App Samurai
tracking_url: Tracking URL for this specific campaign generated by App Samurai
country: First value of the “countries” parameter.
countries: Target GEO(s) of the campaign, which can include multiple or single country code.

platform: Campaign's target device platform (play OR ios)
creative_zip: URL that you will use to download available creatives for the specific campaign
devices: Campaign's target device type (Phone OR Tablet OR Both)
required fields: Mandatory parameters to be passed on tracking url. It always includes ref_id(unique click ID). It can also include device_id (GAID or IDFA) when it is MANDATORY to
open this campaign ONLY on sources that can pass 100% IDFA & GAID.

currency_multiplier: Currency multiplier for direct offerwalls

event_name: Event tokens coming from AppSamurai servers

event_token: Event definitions coming from AppSamurai servers

conversion_requirement: Requirements definition for the rewarded campaigns' tasks

offer_name: Requirements definition for the rewarded campaigns' tasks

Important Notes

In order to keep your campaigns updated (daily cap, payout, status, creatives etc.) were commend you to regularly fetch details on an hourly basis. 

If a specific campaign that you currently run is not visible on API anymore, it means that this campaign is disabled by the advertiser. 

For the multi-rewarded campaigns, you will receive events on postback as well.

Please contact your account manager if you need any additional support.

For the further details

 

Did this answer your question?