How to fetch offers from the Offer API

• A publisher API key. An owner or admin of your account makes one under My Profile, then API Keys. It starts with pk_ and is shown once.
• A server to call from. The key lives in your server’s environment, never in an app or a web page.

1. 01

   My Profile, then API Keys, then Generate Key

   Type a name if you want one (the Key name field is optional), choose Generate Key and copy the key before you leave the page. Up to five keys can exist at once, so you can deploy a new key before you Revoke the old one.

2. 02

   Call the Offer API

   ShellCopy

   curl -G "https://affiliateos.xyz/publisher/offers" \
     -d country=US -d platform=iOS \
     -H "x-api-key: $AFFILIATEOS_KEY"

   Send country on every call. It keeps offers your users can’t be credited for off the list, and with one country it also merges copies of the same app that were aimed at different country lists.

3. 03

   Read each row

   A row is one offer. The fields you’ll use first:

   • id: the offer’s ID. Key everything you store by it.
   • name, image and description: what to show your user.
   • effectivePayoutUsd: what the whole offer pays you, in USD.
   • goals: each step, with what it pays you (effectivePayoutUsd) and the player’s reward (userRewardUsd).
   • isPaidOnInstall: true when the install is the step that pays you.
   • platforms and geoTargeting: where the offer runs.
   • trackingUrl: the link to send your user through.

   JSONCopy

   {
     "status": "success",
     "data": {
       "offers": [
         {
           "id": "aff_7c2e91b04d3a",
           "name": "Harbor Blocks",
           "platforms": ["ios"],
           "isPaidOnInstall": true,
           "effectivePayoutUsd": 4.2,
           "trackingUrl": "https://click.affiliateos.ai/click?off_id=aff_7c2e91b04d3a&pub_id=...&partner_id=...&sub_id={SUB_ID}&device_id={DEVICE_ID}",
           "goals": [
             {
               "name": "Install",
               "effectivePayoutUsd": 4.2,
               "userRewardUsd": 1.5,
               "userRewardIsAdvertiserSet": true
             },
             {
               "name": "Reach level 10",
               "effectivePayoutUsd": 0,
               "userRewardUsd": 1.5,
               "userRewardIsAdvertiserSet": true
             }
           ]
         }
       ],
       "pagination": {
         "current_page": 1,
         "per_page": 1,
         "total": 1,
         "has_more_pages": false
       }
     }
   }

   Example for Pebble Rewards, trimmed. Real rows carry every field in Every offer field, explained.

4. 04

   Send each user through trackingUrl

   Replace {SUB_ID} with that user’s own ID and, when you have it, {DEVICE_ID} with the device’s advertising ID. Leave partner_id exactly as we send it: it is what credits the conversion to you. The user’s ID comes back on every postback as sub_id.

5. 05

   Check it worked

   The response reads "status": "success", and without paging pagination.total equals the number of rows you got. Pick one row, search its id on the Offers page in the portal and check the payout matches.

Narrow the list with country, platform and the other filters in Filter offers by country, platform and category. Paging is off unless you send page or per_page, so one response holds every offer. To turn it on, read Paging and sorting a large list.

• Offers that can’t take a new user right now. A daily cap that filled, or a budget that ran out or was paused. They come back on their own; no parameter brings them back sooner. See Daily caps.
• Extra copies of the same app. With one country on the call, you get at most one install-paid and one event-paid row for each app and platform. See How we pick which copy of an offer you see.
• Offers you hid. If offer blocking is on for your account, an offer hidden with Hide this offer from my list also leaves this list and your Hosted Offerwall, and its link refuses new taps. What you already earned on it still pays.

The Offers page in the portal is built from this same list, at the same payouts, with two differences. It keeps offers that are full for today, marked Capped for today, and it matches copies of the same game more widely, so each game shows once per platform for each way it pays. An API key never gets capped rows: they would send your users to a dead end.

A network uses the Network API: GET https://affiliateos.xyz/network-api/offers with the network’s ak_ key, made under Workspace settings, then API Keys, then Generate Key. The rows have the same core fields, with two differences:

• It pages by default, 50 offers a page. Follow next_page until has_more_pages is false.
• pub_id in each tracking link names your network. Leave it as we send it.

Every parameter and field is in the Network API reference.