JSON API

Pull the same statistics your portal shows into your own systems, scoped by per entity API keys.

The JSON API

Everything you can see in an Offer Capsule report, your systems can read over an API. It is a machine-to-machine JSON interface serving the same click, conversion, and performance statistics the portals show, authenticated by a per-entity API key. Affiliates pull their own numbers into their own trackers, advertisers pull theirs into their own reporting, and you pull whatever you need into a warehouse or a dashboard - without anyone screen-scraping a portal or waiting for a scheduled email.

Per-entity keys

A key belongs to an entity: an affiliate, an advertiser, or the company itself for admin-scoped access. Which entity a call reads is taken from the key, never from a parameter in the request. That is the whole security model in one sentence, and it is worth being precise about why it matters. If the entity id came from a request parameter, then every endpoint would need its own check that the caller is allowed to ask about that id, and one missed check is a data leak. Reading it from the key row means an affiliate key can only ever return that affiliate's data, whatever the caller sends. There is no parameter to tamper with.

Keys are also checked for being active and inside their valid date window, and for the product entitlement behind them, on every call rather than at issue time. Revoking a key or letting one expire takes effect on the next request.

The three scopes

  • Affiliate scope - clicks, conversions, and the performance view for that affiliate, with payout and payout-per-click as the money columns. This is the affiliate-facing earnings picture, matching what the portal shows them.
  • Advertiser scope - the same statistics for that advertiser's own offers.
  • Admin scope - network-wide statistics, plus the offer and affiliate lists needed to drive filters on your own side.

Every endpoint takes a date range and the same filters as the equivalent report - offer, and conversion status where it applies - and returns a JSON envelope. The numbers come from the same read-only aggregates the portals use, so an API answer and a portal answer for the same range are the same answer, produced by the same query. Test rows are excluded here exactly as they are everywhere else.

What it is for

The obvious use is affiliate self-service at scale: an affiliate running a serious media operation wants their EPC by day in their own system, not in a browser tab. The second is advertiser reporting, where an advertiser wants your conversion counts next to their own numbers to reconcile. The third is internal - feeding a warehouse, a BI tool, or an alerting job that watches for an offer's conversion rate falling off a cliff.

What it does not do

Being straight about the boundaries is more useful than a feature list. This is a statistics API. It is read-only: it creates no offers, changes no conversion statuses, and moves no money. Conversions are recorded through the tracking endpoints, not here - see conversion tracking. And there is no rate limiting implemented today, so if you are polling on a schedule, be sensible about the interval and prefer a wider date range less often over a narrow one every few seconds.

Push or pull

The API is the pull side. If what you want is to be told the moment something happens to a conversion rather than to go and ask, that is a postback, not a poll - Offer Capsule will call your URL on record, approval, and reversal with the details substituted in. Most integrations end up using both: postbacks for events, the API for periodic reconciliation. See affiliate postbacks.

Related: reporting for what the same numbers look like in a portal, and the affiliate portal for where an affiliate works with them directly.