Documentation

Overview

KooAds gives you three integration surfaces that work together: the embeddable offerwall your users earn from, a REST Offers API for fully custom UIs, and signed server-to-server postbacks that credit rewards in real time.

Embed the offerwall with a single iframe — no SDK required.
Build your own wall with the Offers API and drive traffic through tracking URLs.
Credit users the moment they convert via signed postbacks — validate {sig} and the server IP.

Quick start

A working integration is four steps: create an app placement, embed the wall, set your postback URL, and verify the first conversion in the postback logs.

Integration at a glance

1. Tools → Offerwall      create placement, copy APP_ID
2. Embed                   iframe with {APP_ID} / {USER_ID}
3. Postback URL            https://your-server.com/callback?...&sig={sig}
4. Reports → Postbacks     watch the first conversion arrive

Server-to-server postbacks

When a user completes an offer, we notify your server in real time via a signed S2S postback so you can credit the reward instantly. Set your postback URL on each app placement.

Your postback URL

https://your-server.com/callback?user_id={user_id}&payout={payout}&reward={reward}&offer={offer_id}&status={status}&sig={sig}

A minimal PHP handler — whitelist our server IP, verify the signature, then credit (or revoke) the reward. The signature is md5(app_id . user_id . api_secret), where api_secretis your app's API Secret (found in your app settings — not the public API key used for the Offers API).

PHP · postback.php

<?php
// KooAds S2S postback handler

$appId     = 10000;               // your App ID
$apiSecret = 'YOUR_API_SECRET';   // app settings → API Secret (keep server-side)
$serverIp  = '1.1.1.1';  // see "Postback server IP" below

$userId  = $_GET['user_id']  ?? '';
$payout  = (float) ($_GET['payout'] ?? 0); // your USD revenue
$reward  = (float) ($_GET['reward'] ?? 0); // points to credit the user
$offerId = $_GET['offer_id'] ?? '';
$status  = (int) ($_GET['status'] ?? 0);   // 1 = credited, 2 = reversed/chargeback
$sig     = $_GET['sig']      ?? '';

// 1) Only accept requests from the KooAds postback server.
if ($_SERVER['REMOTE_ADDR'] !== $serverIp) {
    http_response_code(403);
    exit('forbidden');
}

// 2) Verify the signature: md5(app_id . user_id . api_secret).
if (! hash_equals(md5($appId . $userId . $apiSecret), $sig)) {
    http_response_code(403);
    exit('bad signature');
}

// 3) Deduplicate — skip if you already processed this offer_id + user_id.

// 4) Credit or revoke the reward in your database.
if ($status === 1) {
    // creditPoints($userId, $reward, $offerId);
} else {
    // revokePoints($userId, $reward, $offerId); // chargeback
}

http_response_code(200);
echo 'ok'; // any 2xx marks the postback as delivered

Available macros

We replace these tokens in your postback URL with the live conversion values (URL-encoded).

Macro	Description
{user_id}	Your end-user's unique id (as passed to the offerwall).
{payout}	Your revenue for the conversion, in USD.
{reward}	Points/coins to credit the user (payout × your rate).
{offer_id}	Identifier of the completed offer.
{country}	ISO-2 country code of the user.
{user_ip}	IP address of the converting user.
{status}	Conversion status (1 = credited, 2 = reversed/chargeback).
{sig}	MD5 security signature: md5(app_id . user_id . api_secret) — verify this to trust the callback.

Postback server IP

All postbacks are sent from our server IP address. If you need to whitelist IPs or configure your firewall, use the following IP:

Whitelist this IP

1.1.1.1

Test & monitor

View real-time postback logs in Reports → Postbacks to debug and monitor your integration while you go live.

View Postback Logs

Base URL & auth

Fetch your app's live offer catalog over a simple REST API. All requests are GET and return JSON.

List offers — v2

GEThttps://app.kooads.com/api/v2/offers/{id}/{user_id}Recommended

Clean, consistently-typed response that always includes devices. Each offer also carries description, instructions and requirements — ready to show your users the conversion terms. Requires an API key.

Parameter	In	Type	Description
id	path	integer	Your app placement ID.
user_id	path	string	Your end-user's unique id.
api required	query	string	Your app's API key.
platform	query	string	Filter by device: ios, android, desktop.
offer_type	query	string	Filter by type: CPI, CPA, Survey…
ip	query	string	User IP for geo-targeting (or use country_code).

200 · Response

{
  "offers": [
    {
      "id": 609,
      "name": "Iron Dome",
      "offer_type": "CPA",
      "payout": "2.50",
      "image": "https://cdn.kooads.com/o/609.png",
      "devices": ["android"],
      "countries": ["US", "GB"],
      "description": "Allowed Countries:\nAF/AL/DZ/AS/AD/AO/AI/AQ/AG/AR/AM/AW/AZ/BS/BH/BB/BY/BZ/BJ/BM/BT/BO/BQ/BA/BW/BV/BR/IO/BN/BG/BF/BI/CV/KH/CM/KY/CF/TD/CL/CX/CC/CO/KM/CD/CG/CK/CR/CI/HR/CU/CW/CY/CZ/DJ/DM/DO/EC/SV/GQ/ER/EE/ET/FK/FO/FJ/GA/GM/GE/GH/GI/GR/GL/GD/GP/GU/GT/GG/GN/GW/GY/HT/HM/VA/HN/HK/HU/IN/ID/IR/IQ/IL/IM/JM/JE/JO/KZ/KI/KP/KW/KG/LA/LV/LB/LS/LR/LY/LI/LT/MO/MK/MG/MW/MY/MV/ML/MT/MH/MQ/MR/MU/YT/MX/FM/MD/MC/MN/ME/MS/MA/MZ/MM/NA/NR/NP/NC/NI/NU/NF/MP/OM/PW/PS/PA/PG/PY/PE/PH/PN/PL/PT/PR/QA/RE/RO/RU/RW/BL/SH/KN/LC/MF/PM/VC/WS/SM/ST/SN/RS/SC/SL/SX/SK/SI/SB/SO/ZA/GS/SS/LK/SD/SR/SJ/SY/TJ/TZ/TH/TL/TG/TK/TO/TT/TR/TM/TC/TV/UG/UA/UY/UZ/VU/VE/VG/VI/WF/EH/YE/ZM/ZW\nRestricted Countries:\nCN/AE/SA/NE/NG/PK/VN/TN/EG/BD/KE/US/UK/CA/AU/DE/FR/NL/SE/NO/DK/FI/CH/AT/BE/IE/NZ/JP/KR/SG\nConversion:\nRegister, Collect credits, earn $2.5 and make a cashout in 7 days",
      "instructions": [
        "Register, Collect credits, Earn $2.5 and make a cashout in 7 days"
      ],
      "requirements": "Register, Collect credits, Earn $2.5 and make a cashout in 7 days"
    }
  ]
}

List offers — v1 (legacy)

GEThttps://app.kooads.com/api/v1/offers/{id}/{user_id}

The original endpoint. Prefer v2 for new integrations.

Parameter	In	Type	Description
id	path	integer	Your app placement ID.
user_id	path	string	Your end-user's unique id.

Embed the offerwall

Drop the KooAds offerwall into any app or website with a single iframe — no SDK required. Users earn rewards without ever leaving your product.

HTML

<iframe
  src="https://app.kooads.com/app/iframe/{APP_ID}/{USER_ID}"
  width="100%" height="700" frameborder="0"
  style="border:0;border-radius:16px"></iframe>

Placeholder	Description
{APP_ID}	Your app placement ID — found under Tools → Offerwall.
{USER_ID}	A stable unique id for the current end-user in your system.

Integration steps

Create an app placement under Tools → Offerwall and copy its App ID.
Embed the iframe above, substituting your {APP_ID} and the current {USER_ID}.
Set your postback URL (see Postbacks) so conversions credit your users in real time.
Whitelist our postback server IP and validate the {sig} signature.
Go live and monitor conversions in Reports → Postbacks.

Integrate KooAds in an afternoon.