CPAlead Publisher API

Publisher API Documentation

Use these APIs to pull offers, check conversions, and download reversals. If you want, you can also use the OpenAPI file below with your own API tools.

OpenAPI JSON Offers API Conversions API Reversals API

Looking to manage advertiser campaigns?

The Publisher API on this page is for retrieving offers and publisher reporting. Advertisers can use the separate Campaign API to validate, create, edit, start, and pause self-serve campaigns, including with help from an AI agent.

Read the Advertiser Campaign API guide

This page is public. Replace placeholder values like {PUBLISHER_ID} and {API_KEY} with your own values after you sign in.

Quick Facts

Formats: JSON and JSONP
Offers Default Limit: 2500
CPC API Access: Paid CPAlead Premium Members only
OpenAPI File: https://www.cpalead.com/api/openapi.json

On This Page

OpenAPI File

You can use this file if you want to import the API into your own tools.

Overview

What this API is designed for

Offer Sync

Pull available offers, filter by device or country, and use updated_since for incremental refreshes.

Tracking Safety

CPC and boost-click earnings require paid CPAlead Premium membership and enabled CPC API access. Boosted offers keep their normal rank.

OpenAPI File

The public OpenAPI file is available at /api/openapi.json .

Offers API

Returns a JSON list of available offers. Lower offer_rank values show first.

Your CPC API access

Why click rewards may pause

CPC offers and boost-click rewards may be temporarily limited if your traffic generates repeated clicks without enough qualifying CPA or CPI conversions. This helps protect advertisers from bots and invalid traffic.

Native CPC offers and boost-click reward fields are hidden from your API feed during this pause. Qualifying CPA or CPI conversions lift the pause automatically. Eligible conversion offers remain available. Refresh your full offer feed to update availability; other click eligibility checks still apply.

CPC eligibility status

Every successful offers response includes cpc_eligibility, even when no offers match or fields is used. access_enabled shows your account permission. status is not_enabled, eligible, conversion_limited, or unavailable. native_cpc_available and boost_click_rewards_available show whether those rewards are currently available for your account.

Compare these values each time you sync. When they change, refresh the full feed without updated_since and replace your saved offer list. The status does not guarantee a reward for each click; other click checks still apply.

Ranking & Country Payouts

Each offer includes an offer_rank where 1 is the highest ranked offer. Results stay in offer_rank order from low to high.
Some offers pay different amounts depending on the country. If an offer includes a "payouts_per_country" list, use the payout that matches the user's two-letter country code (e.g., US, CA, GB). If their country isn't in the list, use the default payout shown in "amount".
Some offers pay by event. If an offer includes an "events" list, use each event name, description, and amount for the completed event. Event amounts are already adjusted to your publisher payout split.
CPA and CPI offers with conversion_mode=events pay each listed event once. The offer amount is the maximum total reward; events.amount is the reward for that event. Complete events within 30 days of the original click. The daily cap counts new acquisitions on the day of their first paid event.
CPT (Cost Per Task) offers use screenshot verification. Send visitors to the returned offer link for instructions and My Tasks. Each task pays after approval; the events list shows the publisher rewards. Lockers unlock only after every required task is confirmed.
Use the same subid or advertising ID when someone returns to an event offer. We reuse the original click and its 30-day deadline. Opening the offer again does not restart it. Direct links without an ID rely on a browser cookie; changing browsers, clearing cookies, or changing tracking domains can lose that identity.
Use lead_id to credit each reward once. Event callbacks and conversion or reversal records include event_key and event_name. A later event has a new lead_id even when it belongs to the same offer and user.

Offer API Notes

CPC offers and boost-click rewards through the API are available only to CPAlead Premium Members who have paid the $100 membership fee and have CPC API access enabled.
If an offer has boost clicks, it still keeps its normal rank. It is not moved to the top just because it has boost clicks.
Use the exact link returned by the API. Do not rebuild CPAlead tracking links from offer IDs in your own system.
Eligible boost clicks on CPA, CPI, or CPE offers pay $0.10 for US visitors and $0.07 for visitors from other countries. Rewards require remaining boost clicks and are subject to normal click eligibility limits.
For native CPC offers, cpc_reward_type is native and amount is your click payout. For boosted offers, cpc_reward_type is boost_click and amount remains the conversion payout. boost_click_balance shows the remaining boost clicks. The API returns cpc_payout_us, cpc_payout_not_us, or both, based on the offer's target countries. These click rewards are paid to the publisher only and do not send publisher postbacks or unlock content through a postback.

Endpoint

https://www.cpalead.com/api/offers?id={PUBLISHER_ID}

Available HTTP query parameters

HTTP Parameter	Description
id	Required. Your publisher ID.
country	Only show offers from country, pass two letter ISO country code Use `country=user` to get offers for user's country automatically
limit	Limit the number of offers returned. This can make your API calls faster. Default is 2500 and the maximum is 5000.
type	By default this API returns CPA, CPI, CPE, and CPT offers. Native CPC offers and boost-click rewards require paid CPAlead Premium membership and enabled CPC API access. You can request payout types with a comma-separated list, for example `&type=cpi,cpe,cpr`
updated_since	Only return offers updated on or after this date. You can use YYYY-MM-DD or a full ISO date and time, for example `&updated_since=2026-04-01T00:00:00Z`
fields	Only return the offer fields you need. Use a comma-separated list, for example `&fields=id,title,link,amount,offer_rank` Available fields: `id, title, description, long_description, conversion, device, daily_cap, is_fast_pay, review_period_hours, payment_terms_label, payment_terms_description, link, preview_link, amount, payout_currency, payout_type, countries, epc, creatives, offer_rank, payouts_per_country, events, conversion_mode, verification_method, cpc_reward_type, cpc_payout_us, cpc_payout_not_us, boost_click_balance` Use "description" for the short offer description. Use "long_description" when you want the longer marketplace description.
include_long_description	Set this to 0 or false to leave long_description out of the default Offers API response. If your fields list includes long_description, it will still be returned. `&include_long_description=0`
offerwall_offers	Deprecated. Ignored. The offers API only returns API-safe offers and does not return offerwall-only or other tools-only inventory.
device	Use this only if you are not using automatic device targeting. By default, the API can return all device types. Use this field to only return certain device types. Available values: ios, android, mobile, and desktop. Device may also be a comma-separated list, for example: `&device=ios,android,mobile,desktop` For getting only CPI / CPE offers (which requires only installation for conversion - use device=ios,android Use `device=user` to get offers for user's device automatically
subid / subid2 / subid3	SubID tracking lets you pass extra data into CPAlead tracking links. CPAlead stores the value with clicks and conversions and returns it in publisher postbacks when available. If you do not pass subid, CPAlead will not add one automatically. Use a user ID, wallet ID, or click reference when you need to credit a specific visitor. You can also use a shared value for a page, site, sub-affiliate, keyword, or traffic source, but shared values are for reporting and segmentation and cannot identify one visitor for rewards. A second subid variable for extra data A third subid variable for extra data
gaid / idfa	If you have a Google Advertising ID (GAID) for mobile, use this variable to automatically fill in the gaid on your tracking link If you have a Apple Identifier For Advertisers (IDFA) for mobile, use this variable to automatically fill in the idfa on your tracking link
format / callback	JSON or JSONP format. JSON is default JSONP callback function name. Only used for JSONP format. If using jQuery getJSON, use callback=? and jQuery will automatically fill function name in for you. See JSONP example

Response example

{
    "status": "success",
    "number_offers": 2,
    "country": "US",
    "devices": null,
    "cpc_eligibility": {
        "access_enabled": false,
        "status": "not_enabled",
        "native_cpc_available": false,
        "boost_click_rewards_available": false
    },
    "offers": [
        {
            "id": 999001,
            "title": "QuizBlitz Pro",
            "description": "Test your knowledge and win rewards!",
            "long_description": "Play QuizBlitz Pro, answer trivia questions, and complete the required level to earn your reward.",
            "conversion": "Complete Level 5 (New Users Only)",
            "device": "android",
            "daily_cap": 50,
            "is_fast_pay": true,
            "link": "https://{tracking_domain}/view.php?id=999001&pub={PUBLISHER_ID}&_src=api&_src_sig={SIGNATURE}",
            "preview_link": "https://example.com/offerblast",
            "amount": 1.2,
            "payout_currency": "USD",
            "payout_type": "CPE",
            "conversion_mode": "single",
            "countries": [
                "US",
                "CA",
                "GB",
                "AU",
                "NZ"
            ],
            "epc": 0.95,
            "creatives": {
                "url": "https://{assets_domain}/images/offerblast.png"
            },
            "offer_rank": 7,
            "payouts_per_country": {
                "US": 1.2,
                "CA": 1.1,
                "GB": 0.9
            },
            "events": [
                {
                    "key": "event_1",
                    "name": "Event 1",
                    "description": "Install and open the app.",
                    "amount": 0.7,
                    "payout_currency": "USD"
                },
                {
                    "key": "event_2",
                    "name": "Event 2",
                    "description": "Reach level 5.",
                    "amount": 1.2,
                    "payout_currency": "USD"
                }
            ]
        },
        {
            "id": 999002,
            "title": "PhotoMaster Lite",
            "description": "Edit photos with one tap.",
            "long_description": "Install PhotoMaster Lite, try the editing tools, and keep the app installed for the required period.",
            "conversion": "Install, open & keep for 2 days (New Users Only)",
            "device": "ios",
            "daily_cap": 100,
            "is_fast_pay": false,
            "link": "https://{tracking_domain}/view.php?id=999002&pub={PUBLISHER_ID}&_src=api&_src_sig={SIGNATURE}",
            "preview_link": "https://example.com/photomaster",
            "amount": 0.85,
            "payout_currency": "USD",
            "payout_type": "CPI",
            "conversion_mode": "single",
            "countries": [
                "US"
            ],
            "epc": 1.1,
            "creatives": {
                "url": "https://{assets_domain}/images/photomaster.png"
            },
            "offer_rank": 12,
            "events": []
        }
    ]
}

Response example: HTTP 403

Code example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>CPAlead Offers API Example</title>
</head>
<body>
    <div id="offer-list">Loading offers...</div>

document.getElementById("offer-list").innerHTML = html || "No offers found.";
            })
            .catch(() => {
                document.getElementById("offer-list").innerText = "Failed to load offers.";
            });
    </script>
</body>
</html>

Boost-click response example

Illustrative response for a paid Premium Member with CPC API access. This CPI offer targets the US and Canada, so both boost payout fields are shown. amount is the conversion payout; the CPC fields show potential click rewards.

{
    "status": "success",
    "number_offers": 1,
    "country": "US",
    "devices": null,
    "cpc_eligibility": {
        "access_enabled": true,
        "status": "eligible",
        "native_cpc_available": true,
        "boost_click_rewards_available": true
    },
    "offers": [
        {
            "id": 999002,
            "title": "PhotoMaster Lite",
            "description": "Edit photos with one tap.",
            "long_description": "Install PhotoMaster Lite, try the editing tools, and keep the app installed for the required period.",
            "conversion": "Install, open & keep for 2 days (New Users Only)",
            "device": "ios",
            "daily_cap": 100,
            "is_fast_pay": false,
            "link": "https://{tracking_domain}/view.php?id=999002&pub={PUBLISHER_ID}&_src=api&_src_sig={SIGNATURE}",
            "preview_link": "https://example.com/photomaster",
            "amount": 0.85,
            "payout_currency": "USD",
            "payout_type": "CPI",
            "conversion_mode": "single",
            "countries": [
                "US",
                "CA"
            ],
            "epc": 1.1,
            "creatives": {
                "url": "https://{assets_domain}/images/photomaster.png"
            },
            "offer_rank": 12,
            "events": [],
            "cpc_reward_type": "boost_click",
            "boost_click_balance": 250,
            "cpc_payout_us": 0.1,
            "cpc_payout_not_us": 0.07
        }
    ]
}

Conversions API

Conversions and Reversals share a request limit.
Conversion API allows you to ping CPAlead to test for conversions, useful for making custom apps. Pass subid in as a subid or ip address, or "user" to have our system use the ip address of the client calling this script (useful for JSONP calls)
For push-type conversion service (Server-to-Server Postback), see our Postback Documentation

If an API request returns HTTP 429, wait for the number of seconds in Retry-After before trying again. Check X-RateLimit-Limit and X-RateLimit-Remaining, and increase the delay after repeated failures.

Endpoint

https://www.cpalead.com/api/conversions?id={PUBLISHER_ID}&api_key={API_KEY}

Available HTTP query parameters

HTTP Parameter	Description
id	Required. Your publisher ID.
api_key	Required. Your API key.
subid	Required. Lookup conversion based on subid, pass subid or users ip address, pass "user" to use the ip address of the client calling this script (useful for JSONP calls)
offer_id	Optional. Will check for conversion only for this offer (campaign) id
format / callback	JSON or JSONP format. JSON is default JSONP callback function name. Only used for JSONP format. If using jQuery getJSON, use callback=? and jQuery will automatically fill function name in for you. See JSONP example

Response example

Reversals API

Conversions and Reversals share a request limit.
Use this API to download your list of bad leads between two dates. Useful for sorting out bad traffic

Endpoint

https://www.cpalead.com/api/reversals?id={PUBLISHER_ID}&api_key={API_KEY}

Available HTTP query parameters

HTTP Parameter	Description
id	Required. Your publisher ID.
api_key	Required. Your API key.
start_date	Starting date to use when pulling bad leads. Format: yyyy-mm-dd
end_date	End date to use when pulling bad leads. A maximum of one month can be pulled at a time
format / callback	JSON or JSONP format. JSON is default JSONP callback function name. Only used for JSONP format. If using jQuery getJSON, use callback=? and jQuery will automatically fill function name in for you. See JSONP example

Response example