Publisher API

The Publisher API gives you programmatic access to your reports, to the CPA offers available to your account and to ad tags for your websites. All endpoints return JSON and accept only GET requests.

Base URL: https://publisher.advertica.com/api/v1

A successful response wraps the result in data:

{ "data": { ... } }

Money values are numbers in the currency of your account (see currency), percentages are numbers from 0 to 100.

Parameters: optional parameters are sent as query string variables in the URL - add ? after the endpoint and join more parameters with &:

https://publisher.advertica.com/api/v1/campaigns?country=US
https://publisher.advertica.com/api/v1/campaigns?country=US&category=5&page=2
https://publisher.advertica.com/api/v1/reports/42?startDate=2026-09-01&endDate=2026-09-30

Parameters that are not set use their default value. Only the API key goes in the header, never in the URL.

Authentication

Create an API key in the publisher panel under Publisher API → API Keys. The API is enabled per account - if you don't see the Publisher API menu in your panel, contact support. For every key you can set:

• Name - to recognise the key, e.g. the application that uses it.
• Validity - forever, or until a date (the key works until the end of that day).
• IP restriction - allow all IPs, or only listed IP addresses / CIDR ranges (IPv4 and IPv6).

The name, validity and IP restriction can be changed later (Edit), the key itself stays the same. The full key can be shown again with the eye icon in the list of your keys. Send it in the Authorization header of every request:

curl -H "Authorization: Bearer YOUR_API_KEY" https://publisher.advertica.com/api/v1/me

Never send the key in the URL - such requests are rejected. If a key leaks, revoke it and create a new one. Every call made with your keys, including rejected ones, is listed under Publisher API → API Logs.

Errors & limits

Errors return an HTTP status code and a body:

{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key." } }

Rate limits: 60 requests per minute per account (all keys together), of which at most 5 calls of /reports/{id}.

GET /me

Checks the key and returns your account settings. Useful as a first test call.

{
  "data": {
    "publisher_id": 123456,
    "currency": "USD",
    "api_key": { "name": "Dashboard", "prefix": "adv_1a2b3c4d", "valid_until": null, "ip_whitelist": ["203.0.113.10"] },
    "rate_limit": { "requests_per_minute": 60, "report_requests_per_minute": 5 }
  }
}

GET /reports

Lists your saved reports. Save a report in the publisher panel (Reports → set up columns and filters → save) and call it by its id.

{
  "data": {
    "reports": [
      { "id": 42, "name": "Daily by country", "type": "impressions", "url": "https://publisher.advertica.com/api/v1/reports/42" }
    ]
  }
}

type is impressions for reports saved on the main / complete report and conversions for conversion reports.

GET /reports/{id}

Returns the data of a saved report. Columns, filters and sorting are taken from the saved report.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://publisher.advertica.com/api/v1/reports/42?startDate=2026-09-01&endDate=2026-09-30"

{
  "data": {
    "report": { "id": 42, "name": "Daily by country", "type": "impressions", "campaign_type": "cpa" },
    "period": { "start_date": "2026-09-01", "end_date": "2026-09-30" },
    "currency": "USD",
    "columns": [
      { "key": "date", "label": "Date", "kind": "dimension" },
      { "key": "country", "label": "Country", "kind": "dimension" },
      { "key": "impressions", "label": "Impressions", "kind": "metric" }
    ],
    "totals": { "impressions": 120500, "clicks": 3100, "conversions": 85, "ctr": 2.5726, "cr": 0.0705, "earnings": 154.2, "ecpm": 1.2797 },
    "rows": [
      { "date": "2026-09-30", "country": { "id": "US", "name": "United States" }, "impressions": 4200, "clicks": 110, "conversions": 3, "ctr": 2.619, "cr": 0.0714, "earnings": 6.1, "ecpm": 1.4524 }
    ],
    "pagination": { "page": 1, "limit": 100, "total_rows": 540, "total_pages": 6 }
  }
}

Dimensions are the columns chosen in the saved report. Plain values (date, hour, month, device_group, status, time) are returned as they are, references (country, campaign, website, placement, ad format, device, OS, browser, ...) as { "id": ..., "name": ... }.

Metrics of impressions reports:

totals are the sums of the whole report (all pages), null when there is no data.

Conversion reports return one row per conversion with the chosen columns plus payout (your payout) and payout_updating (true for push subscriptions whose value is not known yet, payout is then null). totals is null.

GET /campaigns

Lists the CPA offers available to your account - the same offers as on the Offers page.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://publisher.advertica.com/api/v1/campaigns?country=US&limit=20"

{
  "data": {
    "campaigns": [
      {
        "id": 1234,
        "name": "Example Offer",
        "active": true,
        "category": "Dating",
        "flow": "SOI",
        "payout": { "type": "per_country", "amount": 0.5, "min": 0.5, "max": 2.4, "currency": "USD" },
        "countries": ["DE", "US"],
        "adult": false,
        "created": "2026-08-14"
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total_rows": 210, "total_pages": 5 }
  }
}

payout.type:

• fixed - the same payout for all countries (amount).
• per_country - payout differs by country, min / max give the range, the exact values are in the campaign detail. amount is the payout of countries without their own price (or null).
• revshare - a share of the advertiser's payout, amount is in % (currency is %).
• variable - the payout depends on the conversion.

countries is a list of country codes or "any".

GET /campaigns/{id}

Returns all details of an offer.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://publisher.advertica.com/api/v1/campaigns/1234?placement=footer"

GET /adtags

Lists the ad tag types you can generate and the accepted values of their parameters (including the current list of banner sizes).

curl -H "Authorization: Bearer YOUR_API_KEY" https://publisher.advertica.com/api/v1/adtags

{
  "data": {
    "ad_tag_types": [
      {
        "type": "banner",
        "url": "https://publisher.advertica.com/api/v1/adtags/banner",
        "format": "html",
        "parameters": {
          "website_type": { "values": ["non_adult"], "default": "non_adult" },
          "placement": { "values": "a-z, A-Z, 0-9, _ (max. 100 characters)", "default": "default" },
          "size": { "values": ["responsive", "300x250", "728x90", "160x600", "468x60", "300x50"], "default": "300x250" }
        }
      }
    ]
  }
}

GET /adtags/{type}

Generates an ad tag - the same code as the Ad Tags page of the publisher panel. type is one of smartlink, banner, popup, redirect. All parameters are optional, the defaults are the same as in the panel.

placement names the place where you use the tag, e.g. homepage_header (a-z, A-Z, 0-9, _, max. 100 characters, default default). Every placement is reported separately - filter or group your reports by placement to compare them. Use a different placement for every slot you want to measure.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://publisher.advertica.com/api/v1/adtags/banner?size=728x90&placement=homepage_header"

{
  "data": {
    "type": "banner",
    "placement": "homepage_header",
    "settings": { "website_type": "non_adult", "size": "728x90" },
    "format": "html",
    "code": "<ins style=\"width: 728px;height:90px\" ...><script src=\"...\" async></script></ins>",
    "usage": "HTML. Paste it into your page where the banner should be shown, once per banner slot."
  }
}

Where to put the code:

• smartlink - a URL; use it as a link, a button target or a redirect for your traffic. Visitors are sent to the best matching offer.
• banner - paste the snippet where the banner should appear; for more banners on one page paste one snippet per slot.
• popup - paste the snippet once into every page where pop ads should run, e.g. right before </body>.
• redirect - paste the snippet into the page; matching visitors are redirected to an offer right away, so use it only on pages meant for that.

Every call returns a new tag; tags generated earlier keep working. Statistics of all tags appear in your reports under their placement.

Example workflow

A typical integration - e.g. a script or an AI assistant that builds a website and monetizes it:

1. GET /me - check that the key works.
2. GET /adtags - see which ad tags and settings are available.
3. GET /adtags/banner?size=300x250&placement=sidebar, GET /adtags/popup?placement=site, ... - generate a tag for every slot, each with its own placement, and paste the returned code into the website.
4. Save a report in the publisher panel (Reports → e.g. group by date and placement → save), then GET /reports to find its id.
5. GET /reports/{id}?startDate=...&endDate=... - read impressions, clicks and earnings per placement.

Keep the API key out of the website code - ad tags do not need it, the key is only for calling the API.