---
title: "Search conditional benefits, bonuses, perks, and eligibility programs"
method: GET
path: "/api/v1/entitlements"
---

# Search conditional benefits, bonuses, perks, and eligibility programs

`GET /api/v1/entitlements`

## Request

- Base URL: `https://andrewsfreebies.com`
- URL: `https://andrewsfreebies.com/api/v1/entitlements`
- Auth: none declared

## Query parameters

- `q` string
- `focus` 'redeemable-value'
- `kind` 'bank-account-bonus' | 'benefit-tracker' | 'benefits-counseling' | 'business-support' | 'card-linked-offer' | 'community-benefit' | 'community-program' | 'consumer-complaint' | 'credit-card-welcome-bonus' | 'cultural-access' | 'customer-loyalty-perk' | 'deal-directory' | 'education-program' | 'eligibility-directory' | 'employment-program' | 'family-support' | 'free-admission' | 'government-benefit' | 'grant' | 'health-coverage' | 'health-locator' | 'hotline' | 'housing-assistance' | 'insurance-benefit' | 'library-access' | 'library-benefit' | 'public-resource' | 'rebate' | 'rights-advocacy' | 'rights-enforcement' | 'school-program' | 'shopping-portal' | 'tax-credit'
- `cost_basis` 'no-cost' | 'no-additional-cost' | 'discounted' | 'subsidized' | 'requires-purchase' | 'requires-spend' | 'requires-deposit' | 'paid-membership' | 'varies'
- `personalized` boolean
- `status` 'verified' | 'source-found' | 'directory-listed'
- `limit` integer
- `offset` integer

## Response `200`

A paginated list of matching entitlements

- EntitlementSearchResponse
  - `count` integer
  - `returned` integer
  - `next_offset` integer, nullable
  - `items` Entitlement[]
    - `id` string, required
    - `name` string, required
    - `provider` string, required
    - `entitlement_type` 'bank-account-bonus' | 'benefit-tracker' | 'benefits-counseling' | 'business-support' | 'card-linked-offer' | 'community-benefit' | 'community-program' | 'consumer-complaint' | 'credit-card-welcome-bonus' | 'cultural-access' | 'customer-loyalty-perk' | 'deal-directory' | 'education-program' | 'eligibility-directory' | 'employment-program' | 'family-support' | 'free-admission' | 'government-benefit' | 'grant' | 'health-coverage' | 'health-locator' | 'hotline' | 'housing-assistance' | 'insurance-benefit' | 'library-access' | 'library-benefit' | 'public-resource' | 'rebate' | 'rights-advocacy' | 'rights-enforcement' | 'school-program' | 'shopping-portal' | 'tax-credit', required: Primary record archetype; this value does not establish price or individual eligibility.
    - `entitlement_type_label` string, required
    - `entitlement_type_context` object, required
      - `definition` string
      - `domain` string
      - `archetype` string
      - `agent_instruction` string
    - `summary` string
    - `benefit` object, required
      - `description` string
      - `estimated_value_usd` number, nullable
    - `discovery` object, required
      - `focus` 'redeemable-value' | 'public-service'
      - `has_estimated_dollar_value` boolean
    - `access` object, required
      - `relationships` string[]
      - `requirements` string
      - `activation` string
      - `cost_basis` 'no-cost' | 'no-additional-cost' | 'discounted' | 'subsidized' | 'requires-purchase' | 'requires-spend' | 'requires-deposit' | 'paid-membership' | 'varies': Normalized financial condition; read cost_basis_context and fees before describing the benefit as free.
      - `cost_basis_label` string
      - `cost_basis_context` object
        - `classification` string
        - `definition` string
        - `agent_instruction` string
        - `variation_patterns` string[], nullable
        - `does_not_mean` string[], nullable
      - `fees` string
      - `personalized` boolean
      - `regions` string[]
      - `expires` string, nullable
    - `parent` object, nullable: Parent entitlement when this record exposes one independently searchable benefit from a broader access relationship.
      - `id` string
      - `name` string
      - `relationship` 'benefit-of'
      - `web_url` string
    - `coverage` object, nullable
      - `level` 'national' | 'state' | 'local'
      - `family` string
      - `jurisdiction` string
      - `maturity` 'locator' | 'direct'
    - `status` string, required
    - `last_checked` string, date
    - `verification_readiness` VerificationReadiness, required
      - `status` 'audit-confirmed-exact' | 'audit-confirmed-partial' | 'audit-inconclusive' | 'audit-warning' | 'not-audited', required
      - `latest_outcome` 'confirmed-exact' | 'confirmed-partial' | 'terms-changed' | 'explicitly-expired' | 'moved' | 'blocked' | 'fetch-error' | 'not-found' | 'unknown', required: Conservative field-level audit result. blocked, fetch-error, not-found, and unknown do not establish expiration.
      - `latest_checked_at` string, date-time, nullable, required
      - `interpretation` string, required: Factual guidance for using the latest audit without treating an inconclusive fetch as expiration.
    - `action_url` string, uri, nullable, required: Measured official-action path; null means the record is inspectable but must not be recommended for action.
    - `official_action` OfficialActionState, required
      - `allowed` boolean, required
      - `status` 'ready' | 'source-navigation' | 'withheld', required
      - `reason` string, required: Instruction for whether an agent may recommend the official action path.
    - `claim_url` string, uri
    - `source_url` string, uri
    - `source` object, required
    - `taxonomy` object, required
      - `version` string
      - `url` string

---

[API](https://skmtc.dev/andrewsfreebies/apis/andrew-s-freebies-api.md) · [All operations](https://skmtc.dev/andrewsfreebies/apis/andrew-s-freebies-api/llms.txt) · [OpenAPI document](https://skmtc.dev/andrewsfreebies/apis/andrew-s-freebies-api/revisions/2e23a7a12f7a?raw)