Step 4: Fetching Offers

numo's White Label UI is the recommended way to present offers to cardholders — a hosted, customizable front-end you can embed with minimal work (contact numo to get set up). If you maintain a legacy direct integration, you can also fetch offers from the API and render them in your own code. For this example, we'll show you how to fetch offers, offer details, and capture user events using the API.

Prerequisites

Before you perform this step, make sure that:

• You have an active authentication token.
• You have registered card accounts.

Retrieving Offers

You can retrive offers one or two ways:

1. Retrieve a batch of offers (max. 1,000) via search POST /partner/card-accounts/{carhdolder_id}/offers.search
2. Retrieve recommended offers for a cardholder via POST /partner/card-accounts/{cardholder_id}/offers.recommendations

offers.search

{
  "apply_filter": {
    "category": "AUTOMOTIVE",
    "exclude_activated_offers": false,
    "exclude_content_provider_ids": [
      "triple-abc-123"
    ],
    "exclude_offer_ids": [
      "triple-abc-123"
    ],
    "include_offer_ids": [
      "triple-abc-123"
    ],
    "mode": "ONLINE",
    "type": "CARD_LINKED",
    "activation_required": true
  },
  "page_offset": 0,
  "page_size": 25,
  "proximity_target": {
    "country_code": "US",
    "latitude": "40.440624",
    "longitude": "-79.995888",
    "postal_code": "15206",
    "radius": 35000
  },
  "text_query": "italian food"
}

offers.recommendations

{
  "apply_filter": {
    "category": "AUTOMOTIVE",
    "exclude_activated_offers": false,
    "exclude_content_provider_ids": [
      "triple-abc-123"
    ],
    "exclude_offer_ids": [
      "triple-abc-123"
    ],
    "include_offer_ids": [
      "triple-abc-123"
    ],
    "mode": "ONLINE",
    "type": "CARD_LINKED",
    "activation_required": true
  },
  "include_categories": [
    "AUTOMOTIVE",
    "CHILDREN_AND_FAMILY",
    "ELECTRONICS",
    "ENTERTAINMENT",
    "FINANCIAL_SERVICES",
    "FOOD",
    "HEALTH_AND_BEAUTY",
    "HOME",
    "OFFICE_AND_BUSINESS",
    "RETAIL",
    "SERVICES_AND_SUBSCRIPTIONS",
    "TRAVEL",
    "UTILITIES_AND_TELECOM"
  ],
  "include_modes": [
    "ONLINE"
  ],
  "proximity_target": {
    "country_code": "US",
    "latitude": "40.440624",
    "longitude": "-79.995888",
    "postal_code": "15206",
    "radius": 35000
  },
  "page_offset": 0,
  "page_size": 100
}