Campaign Pull API Setup

The Campaign Pull API lets AppsPrize server-to-server publishers fetch the campaigns that are currently live and available to display. Each campaign object carries everything needed to render and attribute an offer: targeting, bids, creative assets and event goals.

Endpoint

https://api.appsamurai.com/apiv2/campaign-pull/list/{API_KEY}

Authentication

API_KEY is a unique access key issued to each publisher by their technical account manager.
Keep this key secure and never expose it publicly.

Request

Method: GET

Path parameter

Parameter	Type	Description
`API_KEY`	string	Your private API key used for authentication

Headers

Header	Value
`Content-Type`	application/json

Response

A successful request returns HTTP 200 with an array of campaign objects.

Example CPI campaign response

JSON

{
    "campaign_id": 129797, 
    "app_title": "Fortune Words – Lucky Spin", 
    "app_category": "Games / Word", 
    "app_store_url": "https://play.google.com/store/apps/details?id=com.unicostudio.fortunewords", 
    "app_id": "com.unicostudio.fortunewords", 
    "app_icon": "https://play-lh.googleusercontent.com/7zMY8cxX8IMXFJZDJyVfHc-59gdyD7Jx5cUUCLJL5vN4Ub6dmT2Lx91eP7p2h0oKyw=s180", 
    "start_date": "2024-06-10 13:08:00", 
    "end_date": null, 
    "daily_install_cap": 1000, 
    "daily_event_cap": null,  
    "campaign_type": "CPI", 
    "bid": 1.45, 
    "campaign_name": "Fortune Words-125272-And_Phone-TR-12Jun24-SN",
    "platform": "android", 
    "priority": true, 
    "kpi": { 
         "roas": "1D: 10%, 7D: 20%, 30D: 30%", 
         "retention": "1D: 10%, 7D: 20%, 30D: 30%" 
    },
    "monetization_distribution": "90% IAA / 10% IAP", 
    "tracking_url": "https://click.appsamurai.com/api/callbacks/click?sub_campaign_id=SaS6qxRrE8TX4aA1-OCWPPrDpGO-mZCs", 
    "game_description": "Fortune Words – Lucky Spin brings back the good old days of television shows and trivia contests.", 
    "countries": [
      {
        "country_code": "US", 
        "name": "United States" 
      }
    ], 
    "cities": [], 
    "regions": [], 
    "creatives": {
      "images": [
        {
          "url": "https://play-lh.googleusercontent.com/aOJWWTk1dHQRgJeZE5mlrK-fRJL88QiSaYElCDyXzXQxbpFwVbtQMDVSQ_XGFZbstw=w480-h960-rw", 
          "width": 180, 
          "height": 180 
        }
      ],
      "videos": [],
      "others": []
    },
    "creative_zip": "https://api.appsamurai.com/apiv2/campaign-pull/download-creative/as9GmjkBJ2GJhJu93Y25SROYpmFgPTX356MnbNow?campaign_id=asXFZ2MdrQYF7hHC47jm7yuFjhSEG7TkFDBOiUgQc", 
    "event_goals": [
      {
        "event_description": "Complete Level 1", 
        "event_token": "level-1", 
        "bid": 0, 
        "completion_rate": "80%", 
        "average_completion_time": "2 days", 
        "suggested_reward_amount": 0.55, 
        "highlighted_event": true, 
        "time_limit": "30 days", 
        "event_type": "level" 
      },
      {
        "event_description": "Make a purchase", 
        "event_token": "af_purchase", 
        "bid": 0,
        "completion_rate": null,
        "average_completion_time": null,
        "suggested_reward_amount": null,
        "highlighted_event": false,
        "time_limit": null,
        "event_type": "purchase"
      }
    ]
  },

Example CPA campaign response

JSON

{
    "campaign_id": 129797, 
    "app_title": "Fortune Words – Lucky Spin", 
    "app_category": "Games / Word", 
    "app_store_url": "https://play.google.com/store/apps/details?id=com.unicostudio.fortunewords", 
    "app_id": "com.unicostudio.fortunewords", 
    "app_icon": "https://play-lh.googleusercontent.com/7zMY8cxX8IMXFJZDJyVfHc-59gdyD7Jx5cUUCLJL5vN4Ub6dmT2Lx91eP7p2h0oKyw=s180", 
    "start_date": "2024-06-10 13:08:00", 
    "end_date": null, 
    "daily_install_cap": null, 
    "daily_event_cap": 111,  
    "campaign_type": "CPA", 
    "bid": 10.45, 
    "campaign_name": "Fortune Words-125272-And_Phone-TR-12Jun24-SN",
    "platform": "android", 
    "priority": false, 
    "kpi": { 
         "roas": "1D: 10%, 7D: 20%, 30D: 30%", 
         "retention": "1D: 10%, 7D: 20%, 30D: 30%" 
    },
    "monetization_distribution": "90% IAA / 10% IAP", 
    "tracking_url": "https://click.appsamurai.com/api/callbacks/click?sub_campaign_id=SaS6qxRrE8TX4aA1-OCWPPrDpGO-mZCs", 
    "game_description": "Fortune Words – Lucky Spin brings back the good old days of television shows and trivia contests.", 
    "countries": [
      {
        "country_code": "US", string
        "name": "United States" 
      }
    ], 
    "cities": [], 
    "regions": [], 
    "creatives": {
      "images": [
        {
          "url": "https://play-lh.googleusercontent.com/aOJWWTk1dHQRgJeZE5mlrK-fRJL88QiSaYElCDyXzXQxbpFwVbtQMDVSQ_XGFZbstw=w480-h960-rw", 
          "width": 180, 
          "height": 180 
        }
      ],
      "videos": [],
      "others": []
    },
    "creative_zip": "https://api.appsamurai.com/apiv2/campaign-pull/download-creative/as9GmjkBJ2GJhJu93Y25SROYpmFgPTX356MnbNow?campaign_id=asXFZ2MdrQYF7hHC47jm7yuFjhSEG7TkFDBOiUgQc", 
    "event_goals": [
      {
        "event_description": "Complete Level 1", 
        "event_token": "level-1", 
        "bid": 0.45, 
        "completion_rate": "80%", 
        "average_completion_time": "2 days", 
        "suggested_reward_amount": 0.55, 
        "highlighted_event": true, 
        "time_limit": "30 days", 
        "event_type": "level" 
      },
      {
        "event_description": "Make a purchase",
        "event_token": "af_purchase",
        "bid": 10,
        "completion_rate": null,
        "average_completion_time": null,
        "suggested_reward_amount": null,
        "highlighted_event": false,
        "time_limit": null,
        "event_type": "purchase"
      }
    ]
  },

Field descriptions

Field	Type	Description
`campaign_id`	integer	Unique identifier for the campaign
`app_title`	string	Title of the advertised app
`app_category`	string	Store category of the advertised app
`app_store_url`	string	Link to the app on the app store (Google Play or iOS App Store)
`app_id`	string	App Store ID (iOS) or Package Name (Android)
`app_icon`	string	URL to the app’s icon image
`start_date`	string	ISO 8601 format start date of the campaign
`end_date`	string	ISO 8601 format end date of the campaign (can be null if open-ended)
`daily_install_cap`	integer	Maximum number of installs allowed per day (null means no cap)
`daily_event_cap`	integer	Maximum number of events allowed per day (null means no cap)
`campaign_type`	string	Campaign pricing model, e.g., CPA, CPI
`bid`	float64	Payment per conversion in CPI or total payment for all event flow's in CPA(typically in USD)
`campaign_name`	string	Full descriptive name of the campaign
`platform`	string	Platform targeted: ios or android
`priority`	Boolean	Indicates whether the campaign should be prioritized for display (true or false)
`kpi[].roas`	string	Expected Return on Ad Spend (ROAS) KPI for the campaign (null means no roas kpi)
`kpi[].retention`	string	Expected user retention KPI for the campaign (null means no retention kpi)
`monetization_distribution`	string	Indicates monetization strategy or split (e.g., in-app action (IAA) or in-app purchase (IAP)) (null means no distribution)
`tracking_url`	string	Click tracking URL with dynamic placeholders
`game_description`	string	Short description or promotional text for the app
`countries[].country_code`	string	ISO Alpha-2 country code (e.g., US, TR)
`countries[].name`	string	Full name of the target country
`cities`	string	Comma-separated list of target cities (optional)
`regions`	string	Comma-separated list of target regions (optional)
`creatives[].images`	string	List of image creative URLs
`creatives[].videos`	string	List of video creative URLs
`creatives[].others`	string	List of other types of creatives (e.g., HTML, GIF)
`creative_zip`	string	URL to download all creatives in a ZIP archive (includes app icon)
`event_goals[].event_description`	string	Description of the event the user must complete
`event_goals[].event_token`	string	Event token used for postback tracking
`event_goals[].bid`	float64	Payout for completing the event (USD)
`event_goals[].completion_rate`	string	Average completion rate percentage of the event (null means no completion rate)
`event_goals[].average_completion_time`	string	Average time it takes users to complete the event (e.g., "15 minutes", “2 hours”, “1 day”) (null means no completion time)
`event_goals[].suggested_reward_amount`	float64	Suggested reward amount in USD (for rewarded campaigns) (null means no suggestion)
`event_goals[].highlighted_event`	boolean	Marks this event as the primary or most important goal (true or false)
`event_goals[].time_limit`	string	Time limit to complete the event after install (e.g., “7 days”) (null means no time limit)
`event_goals[].event_type`	string	Type of event (e.g., level, purchase)

tracking_url is determined during your S2S integration. It is generated per campaign and returned to you in this field.

Respect daily_event_cap, daily_install_cap and the start_date / end_date boundaries so your delivery stays within the campaign's limits. Always check platform so you only show campaigns compatible with the user's device.

Error codes

Code	Message	Description
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Access to the requested resource is denied
`500`	Internal Server Error	Something went wrong on our side

For questions, troubleshooting, or integration help, contact your technical account manager.