FreebinFreebin
Developer Hub

Pull live public referral codes and offers into your app, embed our widget, use read-only APIs, and connect compatible AI clients. Deployment status and review requirements are shown below.

01 · Data feed

Public API

A single POST endpoint returns live, verified offer and referral-code data as JSON. No API key needed for read access. Offer discovery requires active, verified, unexpired records with separate public-distribution approval. Links and codes require their own permission checks.

Endpoint
POST https://freebin.app/functions/publicApi
Search approved offers and referral codes

Params: company_slug (optional filter), category (optional), limit (1–20, default 10); reuse next_cursor with the same filters for pagination.

curl -X POST https://freebin.app/functions/publicApi \
  -H "Content-Type: application/json" \
  -d '{"action": "search_offers", "company_slug": "numan", "limit": 5}'
List companies
curl -X POST https://freebin.app/functions/publicApi \
  -H "Content-Type: application/json" \
  -d '{"action": "companies", "limit": 20}'
Get referral codes

Returns only active, verified, unexpired referral codes independently approved for public sharing. A separate approved Offer is not required. Missing eligibility or reward information remains unknown. Optional company_slug filter.

curl -X POST https://freebin.app/functions/publicApi \
  -H "Content-Type: application/json" \
  -d '{"action": "referral_codes", "company_slug": "uber-eats"}'
02 · Embed

Embeddable Widget

Drop two lines into any site to show Freebin-verified offers for a company. The widget is self-contained, responsive, and styled to match Freebin. Set data-company to a company slug to filter, or omit it for a general feed.

Embed snippet
<div data-freebin-widget data-company="revolut" data-limit="4"></div>
<script src="https://freebin.app/freebin-widget.js" defer></script>
Live preview
No active offers found.

Attributes: data-company (slug), data-limit (1–10, default 4), data-api-url (override endpoint).

04 · Realtime

Partner Webhooks

Register a webhook URL for your company and we'll POST to it when events happen: a report is filed on one of your offers, an offer expires, or a clicks milestone is hit. Each delivery is signed with an HMAC-SHA256 signature so you can verify authenticity.

Available events
report_created
A user reports one of your offers
offer_expired
One of your offers is marked expired
offer_clicks_milestone
An offer crosses a click threshold
Example payload
{
  "event": "report_created",
  "company_slug": "revolut",
  "data": {
    "report_id": "rpt_abc123",
    "offer_id": "off_xyz789",
    "offer_title": "Get €50 signup bonus",
    "reason": "expired",
    "status": "open"
  },
  "sent_at": "2026-10-12T03:22:00.000Z"
}
Verify the signature (Node.js)
import crypto from "crypto";

const rawBody = req.rawBody; // the exact request body string
const signature = req.headers["x-freebin-signature"];
const expected = crypto
  .createHmac("sha256", YOUR_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (signature !== expected) {
  return res.status(401).send("Invalid signature");
}

To register a webhook, an admin creates a WebhookConfig record with your company slug, webhook URL, events, and a secret. The dispatch system handles the rest.

05 · AI

MCP Server & AI Clients

The verified public gateway provides twelve no-sign-in discovery tools covering both structured offers and approved referral codes, with no access to private accounts or inboxes.Available tools: search_referral_offers, search_referral_codes, get_referral_offer, get_referral_code, compare_referral_offers, get_company_offers, get_company_referral_codes, list_reward_categories, get_claim_instructions, find_similar_offers, get_referral_destination, check_offer_requirements.
MCP Endpoint
https://mcp.freebin.app/functions/mcpGateway

This is the verified no-sign-in, read-only gateway address. See the connection guide for step-by-step setup.

Questions or want a custom integration? Get in touch