---
title: "Get best referral code for a vendor"
method: GET
path: "/api/referral-codes/{vendor}"
---

# Get best referral code for a vendor

`GET /api/referral-codes/{vendor}`

## Request

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

Returns the referral code AgentDeals holds for a vendor, or 404 when we hold none. Same shape is inlined on /api/offers, /api/compare, /api/details/{vendor}, /api/newest, and MCP tool responses.

## Path parameters

- `vendor` string, required

## Response `200`

Best available referral code

- object
  - `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.
  - `_provenance` Provenance, required: 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

- `404`: No active referral codes for the requested vendor

---

[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)