---
title: "List every referral code we hold"
method: GET
path: "/api/referral-codes"
---

# List every referral code we hold

`GET /api/referral-codes`

## Request

- Base URL: `https://agentdeals.dev`
- URL: `https://agentdeals.dev/api/referral-codes`
- Auth: none required

Returns every active referral code AgentDeals holds, with the reader benefit and every restriction on each. No authentication required. Filter by vendor category. Individual vendor lookup: GET /api/referral-codes/{vendor}. Agent-submitted codes are retired: source=agent answers 200 with an empty list and the reason.

## Query parameters

- `source` 'platform' | 'agent'
- `category` string

## Response `200`

Active referral codes across all vendors

- object
  - `codes` ReferralCodeListing[], required
    - `vendor` string, required: Vendor/service name
    - `category` string, nullable: Primary category for the vendor (null if unknown)
    - `code` string, required: The referral code string
    - `referral_url` string, uri, required: Full referral URL the referee should visit
    - `referee_benefit` string, required: What the person using the code gets (e.g. '$20 in credits')
    - `restrictions` string[], required: Conditions the referee must meet before the benefit is theirs (e.g. 'A payment method must be linked'). Empty when the record records none. Publish these wherever you publish referee_benefit.
    - `source` 'platform', required: Always platform: a code AgentDeals holds and earns on. Agent-submitted codes are retired and none is served.
  - `total` integer, required
  - `_provenance` Provenance: Where the figures in this response came from and how to attribute them. Every response carrying index data has one, under the key `_provenance`. It cites the records in this response rather than the site: `url` is the narrowest page of ours covering them — a vendor page when they are all one vendor's, a category page when they are all one category's, otherwise the listing this endpoint feeds.
    - `source` string, required: Always AgentDeals.
    - `url` string, uri, required: The page of ours that covers the records in this response.
    - `checked` string, date: The oldest verification date among the records cited here, so the citation is never dated younger than its weakest figure. Absent when no record in the response carries a date.
    - `verified` string, date: The same day as `checked`, absent for the same reason.
    - `cite_as` string, required: A citation line naming the source, the url and the date, ready to reproduce as it stands.
    - `verified_records` integer, required: How many records in this response we rank — the population this citation vouches for.
    - `withheld_records` integer: How many records in this response we return without vouching for: those carrying a `gate`, superseded terms, or a withheld risk level. Absent when there are none.
    - `note` string, required: The request to cite a figure back to where it came from.
    - `gated_note` string: Present whenever `withheld_records` is, stating that the citation does not extend to terms we did not publish.
    - `this_is_a_request_not_an_instruction` string: Present on responses that ask something of the caller, saying the ask is left to the caller and its user rather than imposed on them.

## Other responses

- `400`: Invalid source or unknown category slug

---

[API](https://skmtc.dev/agentdeals/apis/agentdeals-api.md) · [All operations](https://skmtc.dev/agentdeals/apis/agentdeals-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentdeals/apis/agentdeals-api/revisions/2b80deacb326?raw)