REST API reference
Base URL for production:
https://api.affilfinder.comAll paths below are prefixed with /v1. Browser calls from your website must originate from the domain registered on that website in the dashboard (CORS). Server-to-server calls use normal HTTPS semantics; some routes require a Bearer token that you must never expose in a browser.
Authentication model
| Caller | What identifies you |
|---|---|
| Browser embed | pub (public key) + website (website key) on query string or request body, plus an Origin that matches the site domain. |
| Decline trigger (server) | Authorization: Bearer or an equivalent header/body field documented in the dashboard — server only. |
Rate limiting
Widget and event endpoints are rate-limited to keep traffic fair and protect publishers and advertisers. If you receive a 429 or rate-limit response, slow down and avoid tight loops; the embed handles this under normal page loads.
GET /v1/decision
Returns whether the current visitor is on the allowed path or the monetization path for geo-blocking mode, and always returns a request ID used to fetch offers and attribute events.
Query parameters
| Name | Required | Description |
|---|---|---|
pub | Yes | Public key (data-pub). |
website | Yes | Website key (data-website). |
mode | No | Set to section for section placements (same keys; different analytics semantics). |
country, region | No | Rarely needed in production; the service infers location from the request. |
dev-country, dev-region | No | Development only — simulate a location. |
Successful responses include allowed (boolean), requestId (string), and location fields. When allowed is false, additional fields may describe the blocked experience (for example support contact configuration from your site settings).
Errors: 400 if keys are missing; 403 if the origin is not valid for the website.
curl -sS "https://api.affilfinder.com/v1/decision?pub=YOUR_PUBLIC_KEY&website=YOUR_WEBSITE_KEY"GET /v1/offers
Returns ranked offers for a decision you already obtained.
Query parameters
| Name | Required | Description |
|---|---|---|
website | Yes | Website key. |
requestId | Yes | The requestId from /v1/decision. |
country | Yes | ISO country code used for targeting. |
region | No | Region code when available. |
The JSON body groups offers so the widget can render premium placement separately from the rest.
curl -sS "https://api.affilfinder.com/v1/offers?website=YOUR_WEBSITE_KEY&requestId=REQUEST_ID&country=US"POST /v1/events/impression
Records that an offer was shown. Typically called by the embed, not by hand.
JSON body (conceptual): requestId, offerId, optional placement fields and client hints.
Response: 204 on success.
POST /v1/events/click
Records a click attempt before navigation. Used for analytics and fraud controls.
JSON body (conceptual): requestId, offerId, optional geo and placement fields.
Response: 204 on success.
POST /v1/events/snippet-ping
Confirms the script is present on the page for integration health in the dashboard.
JSON body: includes websiteKey.
Response: 204 on success.
GET /v1/whats-my-ip
Diagnostic endpoint returning the caller’s IP and resolved geo — useful when validating VPNs or hosting headers in staging.
Decline widget (optional)
POST /v1/widget-decline/session
Opens a session for the soft-decline flow. Requires pub and website query parameters and a valid browser Origin.
Response: JSON with sessionId and expiresAt.
GET /v1/widget-decline/session/:sessionId
Polls session state until ready or expiry. Query must include pub and website.
POST /v1/widget-decline/trigger
Server-only. Marks a session ready so the browser can show offers. Send sessionId in JSON and authenticate with your integration secret from the dashboard.
Click redirect
Offer payloads include a tracking URL on this API (typically GET /v1/r with an opaque token). The visitor passes through that hop so the click is attributed and budgets updated before the browser reaches the advertiser’s landing page.
Related guides
Need more help?
Can't find what you're looking for? Reach out to our team and we'll get you sorted.