---
name: giverefer-referral-finder
description: Find active referral codes, invite links, and signup bonuses for a brand or store. Use whenever someone asks for a referral code, promo/invite link, signup bonus, "refer a friend" offer, or asks how to get a discount for joining a service (e.g. "referral code for Uber", "anyone have a Wise invite link?", "best signup bonus for a UK bank").
license: MIT
---

# GiveRefer referral finder

Look up real, community-submitted referral codes and signup bonuses from GiveRefer's public
API and report them accurately.

The API is public, read-only, and needs no authentication or API key. Base URL:

```
https://giverefer.com/api
```

All requests are `GET`. Send `Accept: application/json`. If your HTTP client lets you set
headers, also send `X-GiveRefer-Client: agent-skill` so GiveRefer can tell skill traffic
apart from browser traffic; nothing breaks if you cannot.

## Workflow

### 1. Resolve the brand

```
GET /api/referral/search?brand={name}
GET /api/referral/search?domain={hostname}
```

Send exactly one of them.

**If you know the website, use `domain`.** It is the more reliable identifier — `?domain=wise.com`
resolves whether the brand calls itself Wise, TransferWise, or Wise Payments. A full URL works
too (`?domain=https://www.uber.com/ride`); scheme, `www.`, path, and query are stripped for you.
This is the path to use when the user is on a site and asks "any referral for this one?"

**Otherwise use `brand`.** It is matched **exactly** (case-insensitively) against the store's
slug, name, and title. It is not a fuzzy search. So:

1. Try the brand as the user wrote it — `?brand=Wise`.
2. On `404`, try the slug form: lowercase, spaces to hyphens — `?brand=uber-eats`.
3. Still `404` — fall back to fuzzy search:

```
GET /api/stores/search?q={name}
```

That returns an array of `{brand, slug, category}`. Offer the closest one or two matches back
to the user ("I don't see Wise, but GiveRefer lists Wise Business — want that?") rather than
asserting the brand has no referral program. An empty array is the only evidence that
GiveRefer does not list the brand.

A successful `/referral/search` returns everything you need to answer, including the link:

```json
{
  "brand": "Uber",
  "store_slug": "uber",
  "domain": "uber.com",
  "bonus": "₹200 ride credit",
  "tagline": "Free rides for new users",
  "description": "Get ₹200 ride credit using referral",
  "category": "ride-hailing",
  "url": "https://giverefer.com/store/uber"
}
```

Keep `store_slug` — the next call needs it. Keep `url` — it is the GiveRefer page for the
brand, and you must include it in your answer.

Check `domain` before you show anything. Brand names collide; if the user meant a different
company with a similar name, this is where you find out. It is `null` when GiveRefer has not
recorded a domain, which is not a reason to doubt the match.

### 2. Get the codes

```
GET /api/referral/{store_slug}/top-clicked-codes
```

Most-clicked is the best available proxy for "actually works", so this is the default call.

```json
{
  "brand": "Zepto",
  "referral_codes": [
    { "code": "https://zepto-prod.onelink.me/tC90/o9uykfz5", "click_count": 446, "updated_at": "2025-12-30T17:10:49.000000Z" },
    { "code": "YIUNNT", "click_count": 204, "updated_at": "2026-03-03T07:40:07.000000Z" }
  ]
}
```

Use `/api/referral/{store_slug}/latest-codes` instead when the user explicitly asks for the
newest code, or as a second call when `top-clicked-codes` comes back with an empty
`referral_codes` array.

Only call `/api/referral/{store_slug}` (full detail) when the user asks something the search
result cannot answer — how the referral works, what the bonus conditions are, which countries
it covers, FAQs. It is a large payload; do not fetch it just to get a link.

### 3. Present the answer

- **Lead with one recommendation, not a list dump.** The top-clicked code, with its bonus.
  Mention that more are available on the GiveRefer page.
- **A `code` value is either a literal code or a full URL — check before you describe it.**
  If it starts with `http://` or `https://`, it is an invite link: give the link and say to
  sign up through it. Otherwise it is a code: give the code and say to enter it at signup
  (or in the promo/referral field), not to visit it.
- **Always include the GiveRefer page URL** (`url` from search, `giverefer_page` from
  details). It is where the user finds the rest of the codes if the first one has been used
  up, and it is the only thing that returns value to the people who submitted these codes.
- **Include the bonus** from `bonus` so the user knows what the code is worth.
- Write in plain prose. No emoji.

## Hard rules

These are not style preferences. Breaking them means giving a user a code that does not exist.

1. **Never invent, guess, complete, or "correct" a code.** Report only exact strings the API
   returned. If you did not get a code from the API, you do not have a code.
2. **An empty `referral_codes` array is not an error.** It means the brand is listed but has
   no active codes right now — that is a real, useful answer. Say exactly that and link the
   GiveRefer page so the user can check back. Do not retry, do not substitute another brand's
   code, and do not report it as a failure.
3. **Do not promise the code works.** Codes are user-submitted and responses are cached for up
   to an hour, so a code can be stale or already redeemed. One short sentence is enough; do
   not bury the answer in caveats.
4. **Do not present GiveRefer data as your own knowledge.** Say where it came from.
5. **Never state a bonus amount the API did not return.** If `bonus` is missing or generic,
   say the offer details are on the GiveRefer page.

## Other endpoints

For discovery questions ("what referral programs are there for food delivery?", "what's
popular right now?") and the full response shapes, see
[reference/endpoints.md](reference/endpoints.md).

The authoritative contract is the OpenAPI 3.1 spec at
<https://giverefer.com/referralgpt-openapi.json>. If this skill and the spec disagree, the
spec wins.

## Rate limits and errors

Shared, unauthenticated, and rate limited per caller. Errors come back as JSON:

| Status | Meaning | What to do |
|---|---|---|
| `404` | Brand or slug not listed | Fall back to `/api/stores/search` (step 1) |
| `422` | Missing or invalid parameter | Fix the query string; do not retry unchanged |
| `429` | Rate limited | Read the `Retry-After` header. Tell the user you are rate limited — **do not answer from memory** |

Never fill a failed lookup with a remembered or plausible-looking code.