What parameters are available for filtering deals?

The Deals API supports several filtering parameters including: search (text search), vertical_id (category), advertiser_id, country, exclusive, active/status, and pagination parameters (limit or page/per_page depending on endpoint). You can combine multiple parameters for precise filtering.

How does pagination work with the Deals API?

The Deals API uses offset-based pagination. Provide page and per_page, or simply limit to cap page size. Each response includes next_page/prev_page to navigate.

Deals API Documentation | Hi Energy AI API - Complete

Q: How do I filter deals by category or vertical?

You can filter deals by category using the vertical_id parameter (a vertical tag ID). For example: GET /api/v1/deals?vertical_id=123 will return deals from advertisers tagged with that vertical. Use the Verticals API (GET /api/v1/verticals) to discover available vertical IDs.

Q: Can I search for specific deals or offers?

Yes! Use the search parameter to find deals containing specific text. For example: GET /api/v1/deals?search=black friday will return deals related to Black Friday promotions. The search works across deal titles, descriptions, and promotional text, making it perfect for AI-powered deal discovery and recommendation systems.

Overview

The Deals API provides access to affiliate deals and offers from major networks including FlexOffers, CJ, Rakuten, Impact, Awin, Partnerize, Pepperjam, and ShareASale. This endpoint is optimized for AI agents and chatbots with structured responses and offset pagination.

Endpoint Details

Base Endpoint

GET /api/v1/deals

Retrieve paginated list of deals

Authentication

X-Api-Key: YOUR_API_KEY

Required header for all requests

You need to sign in to get your API key

API Playground

Click Test to run the request and preview the JSON response inline, or Open to view the endpoint in a new tab. Sign in to enable live testing with your API key.

Action	Method	Endpoint	Description
List deals (first page)	`GET`	`/api/v1/deals`	Offset pagination; supports page/per_page or limit.
List active deals	`GET`	`/api/v1/deals?active=true`	Filter to active deals only.
List exclusive deals	`GET`	`/api/v1/deals?exclusive=true`	Filter to exclusive deals.
Filter by country	`GET`	`/api/v1/deals?country=US`	Deals for a specific country code.
Text search	`GET`	`/api/v1/deals?search=...`	Search deal text (e.g. summer sale).
Get single deal	`GET`	`/api/v1/deals/:id`	Fetch one deal by ID.
Legacy list (offset)	`GET`	`/api/deals?page=1&per_page=...`	Legacy endpoint with offset pagination.

GET /api/v1/deals v1

Basic request (first page).

Open

GET /api/v1/deals?active=true v1

Active deals.

Open

GET /api/v1/deals?exclusive=true v1

Exclusive deals.

Open

GET /api/v1/deals?country=US v1

Filter by country.

Open

GET /api/v1/deals?search=summer+sale v1

Text search.

Open

GET /api/deals legacy

Legacy endpoint (offset pagination).

Open

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results per page (clamped to 500). Alternative to `per_page`; when provided, caps the page size.
`page`	integer	No	Offset pagination page number (default: 1).
`per_page`	integer	No	Offset pagination page size (default varies by endpoint; clamped). Use with `page`.
`search`	string	No	Text search across deals (Searchkick/Elasticsearch-backed when available, with SQL fallback).
`advertiser_id`	string	No	Filter by advertiser (supports numeric ID or slug).
`vertical_id`	integer	No	Filter by advertiser vertical tag ID. Get IDs from `GET /api/v1/verticals`.
`country`	string	No	Filter by country code (ISO2, e.g. `US`, `CA`).
`exclusive`	boolean	No	Filter for exclusive deals only (true/false)
`status`	string	No	Deal status filter: `active` or `inactive`.
`active`	boolean	No	Filter for active deals only (true/false)
`network_id`	string	No	Filter by network (supports numeric ID or slug). Only supported on `/api/v1/deals`.
`api_key`	string	No	Legacy authentication for `/api/deals`. For `/api/v1/deals`, prefer the `X-Api-Key` header.

Response Format

All responses follow a consistent JSON structure optimized for AI agents:

{
  "deals": {
    "data": [
      {
        "id": "deal_123",
        "title": "Summer Sale - Up to 50% Off",
        "description": "Get up to 50% off on summer collection",
        "advertiser": {
          "id": 12345,
          "name": "Fashion Store",
          "slug": "fashion-store",
          "logo_url": "https://example.com/logo.png"
        },
        "vertical": "fashion",
        "countries": ["US", "CA"],
        "exclusive": false,
        "featured": true,
        "active": true,
        "commission_rate": 8.5,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "per_page": 200,
    "total_count": 1250,
    "total_pages": 7
  }
}

Field Reference

Complete reference of all fields returned by the Deals API:

Basic Deal Information

Field	Type	Description
`id`	integer	Unique deal identifier
`name`	string	Deal name/title
`name_fr`	string	Deal name in French
`name_es`	string	Deal name in Spanish
`name_ht`	string	Deal name in Haitian Creole
`name_vi`	string	Deal name in Vietnamese
`name_de`	string	Deal name in German
`name_pt`	string	Deal name in Portuguese
`name_bn`	string	Deal name in Bengali
`name_ru`	string	Deal name in Russian
`name_ja`	string	Deal name in Japanese
`name_ko`	string	Deal name in Korean
`name_zh_cn`	string	Deal name in Simplified Chinese
`description`	string	Deal description
`description_fr`	string	Description in French
`description_es`	string	Description in Spanish
`description_ht`	string	Description in Haitian Creole
`description_vi`	string	Description in Vietnamese
`description_de`	string	Description in German
`description_pt`	string	Description in Portuguese
`description_bn`	string	Description in Bengali
`description_ru`	string	Description in Russian
`description_ja`	string	Description in Japanese
`description_ko`	string	Description in Korean
`description_zh_cn`	string	Description in Simplified Chinese
`code`	string	Promotional code
`link`	string	Deal tracking link

Terms & Conditions

Field	Type	Description
`terms`	string	Deal terms and conditions
`terms_fr`	string	Terms in French
`terms_es`	string	Terms in Spanish
`terms_ht`	string	Terms in Haitian Creole
`terms_vi`	string	Terms in Vietnamese
`terms_de`	string	Terms in German
`terms_pt`	string	Terms in Portuguese
`terms_bn`	string	Terms in Bengali
`terms_ru`	string	Terms in Russian
`terms_ja`	string	Terms in Japanese
`terms_ko`	string	Terms in Korean
`terms_zh_cn`	string	Terms in Simplified Chinese
`effective_at`	datetime	Deal start date
`expires_at`	datetime	Deal expiration date
`created_at`	datetime	Deal creation timestamp
`updated_at`	datetime	Last update timestamp

Deal Properties

Field	Type	Description
`exclusive`	boolean	Whether deal is exclusive
`featured`	boolean	Whether deal is featured
`large_logo`	string	Large logo image URL
`small_logo`	string	Small logo image URL
`countries`	array	Countries where deal is valid

Related Objects

Field	Type	Description
`advertiser_id`	integer	Associated advertiser ID
`campaign_id`	integer	Associated campaign ID
`advertiser`	object	Full advertiser information
`campaign`	object	Full campaign information

Advertiser Object Fields

Basic Advertiser Info

id - Advertiser ID
name - Company name
display_name - Human-readable name
url - Website URL
domain - Website domain
status - Program status

Network & Commission

network_name - Affiliate network
publisher_name - Publisher organization
commission_rate - Commission percentage
vertical_list - Product categories

Campaign Object Fields

Campaign Information

id - Campaign ID
display_name - Campaign display name
name - Campaign name
cid - Network campaign ID

Timestamps

created_at - Campaign creation date
updated_at - Last update date

Examples

Basic Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?limit=10"

Get first 10 deals

Filtered Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?vertical_id=123&exclusive=true&limit=5"

Get exclusive deals for a given vertical (by vertical tag ID)

Search Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?search=summer+sale&country=US"

Search for summer sales in US

Pagination Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?page=2&per_page=200"

Get page 2 with 200 results

Backwards Compatibility Examples

Legacy API Format

Index Endpoint (Wrapped Format)

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/deals?limit=5"

Response Format:

{
  "deals": {
    "data": [
      {
        "id": 1,
        "name": "Nike Black Friday Sale",
        "description": "Up to 50% off",
        "exclusive": true,
        "advertiser": {
          "id": 123,
          "name": "Nike"
        }
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "per_page": 5,
    "total_pages": 100
  }
}

Modern API Format

Show Endpoint (Direct Format)

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/deals/12345"

Response Format:

{
  "data": {
    "id": 12345,
    "name": "Nike Black Friday Sale",
    "description": "Up to 50% off",
    "exclusive": true,
    "advertiser": {
      "id": 123,
      "name": "Nike"
    }
  }
}

Advanced Deal Search Examples

Multi-Filter Search

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?vertical_id=123&exclusive=true&country=US&active=true&limit=20"

Exclusive Active Deals

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?exclusive=true&active=true&limit=10"

Date Range Search

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/deals?effective_after=2024-01-01&effective_before=2024-12-31"

Legacy vs Modern API Comparison

Key Difference: Legacy endpoints wrap responses in a "deals" key for index, while modern endpoints return data directly. Both formats include the same deal information.

Legacy Index Response

{
  "deals": {
    "data": [deal1, deal2, ...]
  },
  "meta": {...}
}

Wrapped format for backwards compatibility

Modern Index Response

{
  "data": [deal1, deal2, ...],
  "meta": {...}
}

Direct format for new integrations

Advanced Filtering

By Advertiser

Filter deals by specific advertisers using their slug:

?advertiser_id=amazon
?advertiser_id=nike
?advertiser_id=apple

By Vertical

Filter by product categories:

?vertical_id=123
?vertical_id=456

By Country

Filter by geographic availability:

?country=US
?country=CA
?country=UK
?country=AU

By Deal Type

Filter by deal characteristics:

?exclusive=true
?active=true

Pro Tip: Combine multiple filters for precise results. For example: ?vertical_id=123&exclusive=true&country=US

Pagination

The Deals API uses offset pagination: supply page and per_page, or just limit to cap results. Responses include next_page and prev_page in meta.

How It Works

Make initial request: ?page=1&per_page=200 (or ?limit=200)
Read meta.next_page from the response
Request the next page until meta.next_page is null

Pagination Response

{
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "per_page": 200,
    "total_count": 12582,
    "total_pages": 63
  }
}

Error Handling

The API returns structured error responses with clear codes and messages:

Common Error Codes

UNAUTHORIZED - Invalid or missing API credentials
RATE_LIMITED - Too many requests
INVALID_PARAMETERS - Invalid parameter values
NOT_FOUND - Resource not found

Error Response Format

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456"
  }
}

Frequently Asked Questions

The Deals API provides access to affiliate deals and offers from major networks including FlexOffers, CJ, Rakuten, Impact, Awin, Partnerize, Pepperjam, and ShareASale. It returns structured data about promotional offers, discount codes, special deals, and seasonal promotions from thousands of affiliate programs, making it perfect for AI-powered deal recommendation systems and chatbots.

You can filter deals by category using the vertical_id parameter (a vertical tag ID). For example: GET /api/v1/deals?vertical_id=123 will return deals from advertisers tagged with that vertical. Use the Verticals API to discover available vertical IDs.

The Deals API supports several filtering parameters including search (text search), vertical_id (category), advertiser_id, country, exclusive, and active/status, plus pagination parameters (limit or page/per_page depending on endpoint).

The Deals API uses offset pagination. Provide page and per_page (or just limit) to navigate pages; responses include next_page and prev_page in meta.

Yes! Use the search parameter to find deals containing specific text. For example: GET /api/v1/deals?search=black friday will return deals related to Black Friday promotions. The search works across deal titles, descriptions, and promotional text, making it perfect for AI-powered deal discovery and recommendation systems.

Use the active=true parameter to get only currently active deals: GET /api/v1/deals?active=true. This ensures you only get deals that are currently valid and available, which is essential for AI systems that need to provide accurate, up-to-date information to users.

The Deals API returns specific promotional offers and discounts, while the Advertisers API returns information about affiliate programs themselves. Deals are time-sensitive promotions (like "20% off"), while advertisers are the companies offering affiliate programs. Use deals for promotional content and advertisers for program information.

Deal data is updated regularly throughout the day as new offers become available and expired deals are removed. The API provides real-time access to the most current deal information, ensuring your AI applications always have the latest promotional offers and discounts available.

Deals API Documentation

Overview

Endpoint Details

Base Endpoint

Authentication

API Playground

Parameters

Response Format

Field Reference

Basic Deal Information

Terms & Conditions

Deal Properties

Related Objects

Advertiser Object Fields

Basic Advertiser Info

Network & Commission

Campaign Object Fields

Campaign Information

Timestamps

Examples

Basic Request

Filtered Request

Search Request

Pagination Request

Backwards Compatibility Examples

Legacy API Format

Index Endpoint (Wrapped Format)

Response Format:

Modern API Format

Show Endpoint (Direct Format)

Response Format:

Advanced Deal Search Examples

Multi-Filter Search

Exclusive Active Deals

Date Range Search

Legacy vs Modern API Comparison

Legacy Index Response

Modern Index Response

Advanced Filtering

By Advertiser

By Vertical

By Country

By Deal Type

Pagination

How It Works

Pagination Response

Error Handling

Common Error Codes

Error Response Format

If this page feels TLDR, ask Dex AI.

Frequently Asked Questions

What is the Deals API and what data does it provide?

How do I filter deals by category or vertical?

What parameters are available for filtering deals?

How does pagination work with the Deals API?

Can I search for specific deals or offers?

How do I get only active deals?

What's the difference between deals and advertisers?

How often is deal data updated?