Build with ToroAds Lockers, Links & API

Getting started

Three steps from sign-up to your first paid conversion. Everything after that is configuration.

Content Locker

A locker gates any part of your page — a download, a video, an article, a coupon — behind one completed offer. Integration is a single script tag; the loader handles the overlay, the offer list, the click and the unlock poll for you.

1. Drop in the loader

Every locker exposes its own loader URL, built from its public code. Copy the exact line from the locker’s embed page.

<script src="https://cdn.toroads.com/cl/js/9f1c8a2b-4d3e-11ef-9c0a-0242ac120002"></script>

2. Choose how it opens

The load method decides who starts the opening, and the load delay decides how long after that. They are not two knobs on one timer.

3. Trigger it yourself (javascript method)

Each locker gets its own global function, derived from its public id — it is not a shared toro_load(). The embed page prints the real name; here it is vd7.

<button onclick="vd7()">Unlock the download</button>

<script>
  // or open it on your own schedule
  setTimeout(function () { vd7(); }, 5000);
</script>

4. Inline template

For an inline locker there is no trigger question: the container is the trigger. Put it where the locker should render.

<div id="captcha-locker"></div>
<script src="https://cdn.toroads.com/cl/js/9f1c8a2b-4d3e-11ef-9c0a-0242ac120002"></script>

Smart Links & Direct Links

A link is the lightest integration we have: no script, no key, nothing to embed. You share a URL, we pick the best-paying eligible offer for that visitor’s country and device, record the click, and redirect. Both prefixes below hit the same resolver, so links already in circulation keep working.

Link format

https://your-domain.com/sl/9f1c8a2b-4d3e-11ef-9c0a-0242ac120002
https://your-domain.com/dl/2b7e54c1-9a08-4f16-8b3d-6f5e2c1d4a90

Passing your own user id

Direct Links are templates you fill in yourself. They carry a single {user_id} macro: substitute your end user’s identifier before you publish the link, and that value comes back to you on the conversion postback.

# template as shown in the dashboard
https://your-domain.com/dl/2b7e54c1-.../{user_id}

# what you publish for user 4821
https://your-domain.com/dl/2b7e54c1-.../4821

Offerwall

A hosted, brandable wall of offers for your app or site, denominated in your own virtual currency. There is nothing to sign and nothing to compute. The only URL you need is the one on your app’s page in the dashboard; your api_secret is not involved here, it is used only to verify the postbacks we send you.

<iframe
  src="https://titan.toroads.com/123/end-user-42"
  style="border:0;width:100%;height:720px"
  title="Offers"></iframe>

Substitute your App ID for 123 and your own end-user id for end-user-42. You can also simply link to that URL instead of framing it.

Offer Feed API

Returns the offers eligible for an app, already filtered by country, device and the app’s own configuration — so you can render offers in your own UI. All endpoints return application/json.

Base URLs

Offer feed (v1 / v2 / v3):  https://api.toroads.com
Everything else:            https://your-domain.com/api

The /api prefix is not part of the path on the feed domain. Postbacks, click redirects and the offerwall endpoints keep the prefix on your main domain and are not reachable on the API domain.

Authentication

Versions

Query parameters

Automatic targeting on v3

v3 returns at most 10 offers, boosted and premium inventory first. A parameter you leave out can be answered from the request itself — but only when the request comes from a browser, detected from User-Agent and Accept.

Your backend is deliberately excluded: your server’s location describes your infrastructure, not your visitor. Always pass ip (or country_code) and platform explicitly from your server.

Example request

curl -H "Authorization: Bearer APP_API_KEY" \
  "https://api.toroads.com/v2/offers/123/end-user-42?country_code=US&platform=android"

Example response — 200 OK

{
  "offers": [
    {
      "id": 1234,
      "name": "Play Game X — reach level 10",
      "description": "Install and reach level 10 within 7 days.",
      "image": "https://cdn.example.com/offers/1234.png",
      "offer_type": "CPI",
      "payout": "2.40",
      "countries": ["US", "CA", "GB"],
      "devices": ["android", "ios"],
      "url": "https://your-domain.com/api/redirect/eyJpdiI6Ii4uLiJ9"
    }
  ]
}

Field notes

• payout is a string with two decimals, already adjusted for the app’s custom rate.
• devices is always non-empty, drawn from android, ios, web. An unrestricted offer lists all three rather than an empty array, so there is no empty case to branch on, and the values are exactly the tokens platform accepts.
• url is a ToroAds tracking link: send the user there and we record the click, then redirect to the offer.
• v2 additionally includes points, is_game, incent and events. v3 omits those.
• events is the goal ladder and is present only on offers with more than one goal — branch on the key being absent, not on an empty array.
• Network-wide performance metrics (EPC, conversion rate, click volume) are never returned by the feed. Your own figures are on the dashboard and Statistics pages.

Content Locker API

If you would rather build your own locker UI, these endpoints drive one directly, identified by its {uuid}. The typical flow is config → offers → view → click → poll status / unlock.

// completed
{ "unlocked": true, "content": { "type": "file", "url": "...", "filename": "..." } }

// still pending
{ "unlocked": false, "status": "pending" }

// flagged by fraud scoring
{ "unlocked": false, "reason": "Suspicious activity detected" }

Public resources are addressed by UUID (lockers, smart links). Offers are referenced by their internal id; the upstream provider’s offer ID and name are never exposed.

Postbacks

Conversions reach the platform through a per-provider callback URL. The handler validates auth, records the conversion, credits your balance and logs the raw hit for auditing — every hit, including auth failures, becomes an audit row.

ANY https://your-domain.com/api/{token}/{password}/{provider}

Conversion fields such as user_id, offer_id, payout, transaction_id and status are provider-specific and mapped per provider configuration. Pass them exactly as the provider sends them, in the query string or the POST body.

Errors & status codes

Authentication and app-state failures answer with { "error": "<reason>" }.

Common error reasons on the feed: App Not Found, App Pending, App Rejected, App Disabled, API Not Approved, Invalid API Key, Missing parameters.