How do I search for specific advertisers or programs?

Use the name parameter for text search across advertiser data: GET /api/v1/advertisers?name=fashion. You can also filter by vertical, network, country, status, and with_deals. Combine multiple parameters for precise filtering: GET /api/v1/advertisers?name=electronics&network_slug=flexoffers&country=US&status=approved.

How do I filter to advertisers that have deals?

Use the with_deals parameter: GET /api/v1/advertisers?with_deals=true. This will return advertisers that have at least one deal.

Advertisers API Documentation

Q: What's the difference between the index and show endpoints?

The index endpoint (GET /api/v1/advertisers) returns a list of multiple advertisers with basic information, perfect for browsing and filtering. The show endpoint (GET /api/v1/advertisers/{id}) returns detailed information about a specific advertiser, including full descriptions, contact information, and comprehensive program details. Use index for discovery and show for detailed analysis.

Q: How do I find advertisers by their website domain?

Use the domain parameter to find advertisers by their website: GET /api/v1/advertisers?domain=amazon.com. This is particularly useful for AI systems that need to check if a specific website has an affiliate program or to find similar advertisers to a given domain.

Q: What's the difference between advertisers and deals?

The Advertisers API returns information about affiliate programs themselves (companies, commission rates, program details), while the Deals API returns specific promotional offers and discounts. Advertisers are the companies offering affiliate programs, while deals are time-sensitive promotions. Use advertisers for program discovery and deals for promotional content.

Complete guide to searching and retrieving advertiser data Complete guide to searching and retrieving advertiser data

Overview

The Advertisers API provides access to advertiser data from major networks including FlexOffers, CJ, Rakuten, Impact, Awin, Partnerize, Pepperjam, and ShareASale. This endpoint is optimized for AI agents with advanced search capabilities, Pagy-backed offset pagination by default, and explicit advertiser cursor compatibility when older clients still need it.

Key Features

Advanced Search - Universal search across names, domains, and descriptions
Domain Lookup - Find advertisers by domain or URL
Default Meta Pagination - Pagy-backed current_page, next_page, and per_page metadata by default
Cursor Compatibility - Advertisers still support explicit cursor requests for compatibility
Rich Metadata - Comprehensive advertiser information and statistics
AI-Friendly - Structured responses perfect for AI agents

Endpoint Details

Base Endpoint

GET /api/v1/advertisers

Retrieve paginated list of advertisers

Authentication

X-Api-Key: YOUR_API_KEY

Required header for all requests

You need to sign in to get your API key

Domain Search

GET /api/v1/advertisers/search_by_domain

Search advertisers by domain or URL

Single Advertiser

GET /api/v1/advertisers/{id}

Get detailed advertiser information

Index vs Show Endpoints

Understanding when to use each endpoint is crucial for efficient API usage:

Index Endpoint

GET /api/v1/advertisers

When to Use:

Browse multiple advertisers
Search and filter advertisers
Get paginated lists
Discover new advertisers
Build advertiser directories

Features:

Pagination support
Search and filtering
Multiple results
Summary data

Best for: Listing, searching, and browsing advertisers

Show Endpoint

GET /api/v1/advertisers/{id}

When to Use:

Get detailed advertiser information
View specific advertiser profile
Access complete advertiser data
Show advertiser details page
Get comprehensive advertiser stats

Features:

Complete advertiser details
Full statistics and metrics
Single result
Rich metadata

Access Required: Paid Publisher Account

Best for: Detailed advertiser information and profiles

Quick Comparison

Aspect	Index Endpoint	Show Endpoint
Purpose	Browse, search, filter multiple advertisers	Get detailed info for one specific advertiser
URL Pattern	`/api/v1/advertisers`	`/api/v1/advertisers/{id}`
Response Type	Array of advertiser objects	Single advertiser object
Pagination	Supported (offset by default, cursor when requested)	Not applicable
Search & Filtering	Full support	Not applicable
Data Detail Level	Summary information	Complete detailed information
Performance	Optimized for bulk operations	Optimized for single record access

Usage Examples

Index Endpoint Examples

# Browse all advertisers
GET /api/v1/advertisers

# Search for fashion advertisers
GET /api/v1/advertisers?name=fashion

# Get FlexOffers advertisers in US
GET /api/v1/advertisers?network_slug=flexoffers&country=US

# Paginated results
GET /api/v1/advertisers?page=2&per_page=50
GET /api/v1/advertisers?limit=50&cursor=...

Show Endpoint Examples

# Get specific advertiser details
GET /api/v1/advertisers/12345

# Get Amazon's complete profile
GET /api/v1/advertisers/67890

# Get Nike's detailed information
GET /api/v1/advertisers/11111

Pro Tip: Use the Index endpoint to discover advertisers and get their IDs, then use the Show endpoint to get detailed information about specific advertisers you're interested in.

Backwards Compatibility

Important: The API maintains backwards compatibility with legacy endpoints while providing modern JSONAPI format for new integrations.

Legacy Endpoints

/api/advertisers - Returns flat JSON format
/api/advertisers/:id - Returns JSONAPI format
/api/deals - Returns wrapped format

Perfect for existing integrations that expect specific data structures

Modern Endpoints

/api/v1/advertisers - Returns JSONAPI format
/api/v1/advertisers/:id - Returns JSONAPI format
/api/v1/deals - Returns JSONAPI format
/api/v1/verticals - Returns JSONAPI format

Recommended for new integrations and AI applications

API Playground

Use the table below to see how to perform common actions. Click Test to run a request and preview the JSON response, or Open to open the URL in a new tab. Sign in to enable live testing with your API key.

Action	Method	Endpoint	Description
List advertisers (first page)	`GET`	`/api/v1/advertisers`	Offset pagination by default; optional page, per_page, limit, q, name, domain, and compatibility cursor.
Get single advertiser	`GET`	`/api/v1/advertisers/:id`	Fetch one advertiser by ID or slug.
Search by name	`GET`	`/api/v1/advertisers?name=...`	Text search across advertiser names and descriptions.
Search by domain	`GET`	`/api/v1/advertisers?domain=amazon.com`	Find advertisers by website domain.
Filter by country	`GET`	`/api/v1/advertisers?country=US`	Advertisers that serve a given country.
Filter by vertical	`GET`	`/api/v1/advertisers?vertical=...`	Advertisers in a given vertical (use vertical ID or name).
Advertisers with deals	`GET`	`/api/v1/advertisers?with_deals=true`	Only advertisers that have at least one deal.
Domain search endpoint	`GET`	`/api/v1/advertisers/search_by_domain?domain=...`	Search advertisers by domain or URL.

GET /api/v1/advertisers v1

List advertisers (first 5).

Open

GET /api/v1/advertisers/:id v1

Get single advertiser (example).

Open

GET /api/v1/advertisers?name=nike v1

Search by name.

Open

GET /api/v1/advertisers?domain=amazon.com v1

Search by domain.

Open

GET /api/v1/advertisers?with_deals=true v1

Advertisers with deals.

Open

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results per page (clamped to 500, default: 20)
`cursor`	string	No	Optional advertiser compatibility cursor. If present, the response switches from `meta` to `pagination`.
`page`	integer	No	Default pagination page number (1-based).
`per_page`	integer	No	Default pagination page size. When omitted, `limit` acts as an upper bound rather than replacing offset pagination mode.
`q`, `query`	string	No	Preferred free-form advertiser lookup. Use this for brand-style or natural-language search.
`name`	string	No	Text search across advertiser data (Searchkick/Elasticsearch-backed when available, with SQL fallback).
`domain`	string	No	Filter by advertiser domain (e.g., "amazon.com")
`url`	string	No	Filter by advertiser URL (supports partial matching)
`network`	string	No	Filter by network name.
`network_slug`	string	No	Filter by network (e.g., "flexoffers", "cj", "rakuten", "impact", "awin", "partnerize", "pepperjam", "shareasale", "avantlink")
`vertical`	string	No	Filter by vertical tag name (e.g., `fashion`, `electronics`).
`status`	string	No	Filter by advertiser status: "not_applied", "applied", "approved", "rejected", "stopped", "unknown"
`country`	string	No	Filter by country code (e.g., "US", "CA", "UK")
`with_deals`	boolean	No	Return only advertisers that currently have deals.

Response Format

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

{
  "data": [
    {
      "id": 12345,
      "attributes": {
        "name": "Amazon",
        "slug": "amazon",
        "domain": "amazon.com",
        "url": "https://amazon.com",
        "status": "approved",
        "network_name": "FlexOffers",
        "country_list": ["us", "ca", "uk"],
        "vertical_list": ["electronics", "books", "home"],
        "logo_url": "https://example.com/amazon-logo.png",
        "large_logo_url": "https://example.com/amazon-logo-large.png",
        "transactions_count": 1250,
        "deals_count": 12,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "per_page": 20,
    "total_count": 50000,
    "total_pages": 2500
  }
}

If you explicitly send cursor, the same endpoint returns pagination.limit, has_next_page, and next_cursor instead of meta.

Access Control

Different endpoints have different access requirements based on your account type:

Index Endpoint Access

GET /api/v1/advertisers

All Users: Free and Paid Publisher users can access the advertiser index endpoint.

Free users can browse advertisers
Paid publisher users get full access
All users can use search and filtering

Show Endpoint Access

GET /api/v1/advertisers/{id}

Restricted Access: Only Paid Publisher users can access detailed advertiser information.

Free users cannot access detailed advertiser data
Paid publisher users get full access
Detailed information requires upgrade

User Types & Permissions

Free Users

HiEnergy publisher users

Browse advertiser index
Search and filter advertisers
View detailed advertiser profiles
Access show endpoint

Paid Publisher Users

Non-HiEnergy publisher users

Full access to all endpoints
Detailed advertiser information
Complete API functionality
Advanced features

Paid Users

Upgraded publisher accounts

Full access to all endpoints
Detailed advertiser information
10,000 requests/hour (other publishers)
Priority support

Access Denied Error Response

When free users attempt to access the show endpoint, they receive a structured error response:

Error Response Format

{
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "This endpoint requires a paid publisher account. Please upgrade to access detailed advertiser information.",
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456"
  }
}

Response Details

Status Code: 403 Forbidden
Error Code: UPGRADE_REQUIRED
Message: Clear upgrade instruction
Timestamp: ISO 8601 format
Request ID: For support tracking

Field Reference

Complete reference of all fields returned by the Advertisers API:

Basic Information

Field	Type	Description
`id`	integer	Unique advertiser identifier
`name`	string	Advertiser company name
`slug`	string	URL-friendly identifier
`domain`	string	Primary website domain
`url`	string	Full website URL
`description`	string	Company description
`status`	string	Program status (active, inactive, pending)
`program_status`	string	Detailed program status

Network & Publisher

Field	Type	Description
`network_name`	string	Affiliate network name
`publisher_name`	string	Publisher organization name
`network_cid`	string	Network-specific advertiser ID
`hubspot_id`	string	HubSpot CRM identifier
`rocket_id`	integer	Internal Rocket ID

Commission Rates

Field	Type	Description
`commission_rate`	float	Primary commission rate (%)
`network_commission_rates`	object	Network default/min/max rates
`actual_commission_rates`	object	Calculated avg/min/max rates

Analytics & Metrics

Field	Type	Description
`estimated_gross_revenue`	float	Estimated annual revenue
`estimated_sales_yearly`	float	Estimated annual sales
`estimated_page_views`	integer	Estimated monthly page views
`transactions_count`	integer	Total transaction count

Social Media & Branding

Field	Type	Description
`logo_url`	string	Standard logo image URL
`large_logo_url`	string	High-resolution logo URL
`linkedin_url`	string	LinkedIn company page
`facebook_url`	string	Facebook page URL
`twitter_url`	string	Twitter profile URL
`instagram_url`	string	Instagram profile URL
`pinterest_url`	string	Pinterest profile URL
`youtube_url`	string	YouTube channel URL

Categories & Reviews

Field	Type	Description
`country_list`	array	Countries where program operates
`vertical_list`	array	Product/service categories
`trust_pilot_average_rating`	float	Trustpilot average rating
`trust_pilot_review_count`	integer	Number of Trustpilot reviews
`platform`	string	E-commerce platform used
`plan`	string	Business plan type
`headquarters`	string	Company headquarters location

Terms Integration Examples

Accessing Terms Data

Terms are included in advertiser responses and provide detailed program information:

// Terms are included in advertiser show endpoint
GET /api/advertisers/12345

// Response includes terms array
{
  "data": {
    "id": 12345,
    "name": "Amazon",
    "terms": [
      {
        "id": 1,
        "name": "Standard Terms",
        "summary": "5% commission on all sales...",
        "raw_response": { ... },
        "campaign_id": 789,
        "advertiser_id": 12345,
        "cid": "TERM_001",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Terms Field Details

AI-Generated Summary: Machine-readable summary of complex terms
Raw Response: Complete original term data from networks
Campaign Association: Links terms to specific campaigns
Network Integration: CID field for network-specific identification
Version Control: Timestamps for term updates and changes

Examples

Basic Request

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

Get first 10 advertisers

Search Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers?name=fashion&limit=5"

Search for fashion advertisers

Domain Search

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers/search_by_domain?domain=amazon.com"

Find advertiser by domain

Filtered Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers?network_slug=flexoffers&country=US"

Get FlexOffers advertisers in US

Detailed API Call Examples

Legacy API Format

Index Endpoint (Flat Format)

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

Response Format:

{
  "data": [
    {
      "id": 12345,
      "name": "Amazon",
      "domain": "amazon.com",
      "terms": [
        {
          "id": 1,
          "name": "Standard Terms",
          "summary": "Standard affiliate terms...",
          "campaign_id": 100
        }
      ],
      "campaigns": [...],
      "network": {...}
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 5,
    "total_pages": 1000
  }
}

Modern API Format

Show Endpoint (JSONAPI Format)

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

Response Format:

{
  "data": {
    "type": "advertiser",
    "id": "12345",
    "attributes": {
      "name": "Amazon",
      "domain": "amazon.com",
      "terms": [
        {
          "id": 1,
          "name": "Standard Terms",
          "summary": "Standard affiliate terms...",
          "campaign": {
            "id": 100,
            "name": "Holiday Campaign"
          }
        }
      ]
    }
  }
}

Advanced Search Examples

Multi-Filter Search

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers?name=electronics&network_slug=flexoffers&country=US&status=approved&limit=20"

Deals-Only Advertisers

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers?with_deals=true&limit=50"

Pagination Example

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

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers?cursor=eyJpZCI6MTIzfQ==&limit=50"

Terms Integration Examples

New Feature: All advertiser responses now include associated terms data, making it easier to understand program requirements and conditions.

Get Advertiser with Terms

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

Returns detailed advertiser info including all associated terms and campaign details

Search with Terms Data

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers?name=fashion&limit=5"

Each advertiser in the results includes their terms for immediate program analysis

Search Features

Search (name parameter)

Search across advertiser data (name, tags, campaigns, and more) using Elasticsearch when available:

Advertiser names
Domain names
URLs
Descriptions

?name=amazon
?name=fashion store
?name=electronics

Specific Field Search

Target specific fields for precise results:

name - Advertiser name
domain - Domain name
url - Full URL

?name=nike
?domain=amazon.com
?url=https://store.com

Search Tips: Use partial matches for broader results. The API supports fuzzy matching and will return relevant suggestions in the meta section.

Advanced Filtering

By Network

Filter by affiliate network:

?network_slug=flexoffers
?network_slug=cj
?network_slug=rakuten
?network_slug=impact
?network_slug=awin
?network_slug=partnerize
?network_slug=pepperjam
?network_slug=shareasale
?network_slug=avantlink

By Status

Filter by advertiser status:

?status=approved
?status=applied
?status=rejected
?status=stopped
?status=not_applied
?status=unknown

By Country

Filter by geographic availability:

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

By Vertical

Filter by product category:

?vertical=fashion
?vertical=electronics
?vertical=travel

Example API Calls:

GET /api/advertisers?network_slug=flexoffers&status=approved - Get approved Flexoffers advertisers
GET /api/advertisers?network_slug=cj&status=applied&per_page=10 - Get 10 CJ advertisers with pending applications
GET /api/advertisers?status=approved&country=US - Get approved US advertisers from all networks
GET /api/advertisers?network_slug=rakuten&status=stopped - Get stopped Rakuten advertisers

Filtering Examples

Filter by Network

Get all Flexoffers advertisers:
GET /api/advertisers?network_slug=flexoffers

Get CJ advertisers with pagination:
GET /api/advertisers?network_slug=cj&per_page=20&page=2

Get Impact advertisers:
GET /api/advertisers?network_slug=impact

Filter by Status

Get approved advertisers:
GET /api/advertisers?status=approved

Get advertisers with pending applications:
GET /api/advertisers?status=applied

Get rejected advertisers:
GET /api/advertisers?status=rejected

Combined Filters

Approved Flexoffers advertisers:
GET /api/advertisers?network_slug=flexoffers&status=approved

US advertisers from Rakuten:
GET /api/advertisers?network_slug=rakuten&country=US

Approved advertisers with deals:
GET /api/advertisers?status=approved&with_deals=true

Advanced Combinations

Approved US advertisers from CJ with deals:
GET /api/advertisers?network_slug=cj&status=approved&country=US&with_deals=true

Stopped advertisers from all networks:
GET /api/advertisers?status=stopped&per_page=50

Applied advertisers with Sports vertical:
GET /api/advertisers?status=applied&vertical=Sports

Pro Tip: You can combine any of these filters together. The more specific your filters, the more targeted your results will be!

Sorting

Advertiser search supports sort options that use Searchkick only (no SQL fallback). Use sort_by and sort_order on both GET /api/v1/advertisers and GET /api/advertisers.

Sort fields:

updated_at – last updated (default)
deals_count – number of deals
name – advertiser name (alphabetical)

Sort order: asc or desc (default: desc).

Examples

GET /api/v1/advertisers?sort_by=updated_at&sort_order=desc&limit=10
GET /api/advertisers?sort_by=name&sort_order=asc&per_page=10&api_key=YOUR_KEY

Domain Search

The domain search endpoint allows you to find advertisers by their domain or URL:

Endpoint

GET /api/v1/advertisers/search_by_domain

Parameters

domain - Domain name (e.g., "amazon.com")
url - Full URL (e.g., "https://amazon.com")
limit - Number of results (default: 20)

Example Usage

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/advertisers/search_by_domain?domain=amazon.com"

Use Cases

Verify if a domain is an advertiser
Find advertiser details by URL
Check domain availability

Pagination

The Advertisers API uses offset-style pagination by default and keeps cursor-based pagination as an explicit compatibility mode:

How It Works

For new clients, use page and per_page and follow meta.next_page
If you already rely on advertiser cursors, send cursor explicitly
Cursor responses return pagination.next_cursor instead of meta

Default Pagination Response

{
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "per_page": 20,
    "total_count": 500,
    "total_pages": 25
  }
}

Compatibility: advertiser cursors still work when you explicitly send cursor, but the default v1 contract for advertiser listing and domain search is Pagy-style meta pagination.

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 Advertisers API provides comprehensive information about affiliate programs and advertisers from major networks including FlexOffers, CJ, Rakuten, Impact, Awin, Partnerize, Pepperjam, and ShareASale. It returns structured data about program details, commission rates, categories, countries served, and application requirements, making it perfect for AI-powered affiliate program discovery and recommendation systems.

The index endpoint (GET /api/v1/advertisers) returns a list of multiple advertisers with basic information, perfect for browsing and filtering. The show endpoint (GET /api/v1/advertisers/{id}) returns detailed information about a specific advertiser, including full descriptions, contact information, and comprehensive program details. Use index for discovery and show for detailed analysis.

Use the name parameter for text search across advertiser data: GET /api/v1/advertisers?name=fashion. You can also filter by vertical, network_slug, country, status, and with_deals. Combine multiple parameters for precise filtering: GET /api/v1/advertisers?name=electronics&network_slug=flexoffers&country=US&status=approved.

Use with_deals=true: GET /api/v1/advertisers?with_deals=true. This returns advertisers that have at least one deal.

Use the domain parameter to find advertisers by their website: GET /api/v1/advertisers?domain=amazon.com. This is particularly useful for AI systems that need to check if a specific website has an affiliate program or to find similar advertisers to a given domain.

The Advertisers API returns information about affiliate programs themselves (companies, commission rates, program details), while the Deals API returns specific promotional offers and discounts. Advertisers are the companies offering affiliate programs, while deals are time-sensitive promotions. Use advertisers for program discovery and deals for promotional content.

Use the status parameter to filter by advertiser status: GET /api/v1/advertisers?status=approved. Available statuses include approved, applied, rejected, stopped, not_applied, and unknown. This ensures your AI applications only recommend advertisers that are currently accepting new affiliates.

The Advertisers API now uses offset-style pagination by default. Standard requests return meta.current_page, next_page, prev_page, and per_page. If you explicitly send cursor, the endpoint switches to compatibility cursor pagination and returns pagination.next_cursor instead.