Verticals API Documentation

Overview

The Verticals API provides access to industry categories and vertical tags used across all affiliate networks. These verticals are curated and normalized to ensure consistency when filtering advertisers and deals by industry.

Key Features

Curated Categories - Normalized vertical names across all networks
Network Agnostic - Consistent categories regardless of source network
Filter Support - Use vertical IDs to filter advertisers and deals
Case Sensitive - Vertical names are stored in lowercase
AI-Friendly - Structured responses perfect for AI agents

Endpoint Details

Base Endpoint

GET /api/v1/verticals

Retrieve paginated list of verticals

Authentication

X-Api-Key: YOUR_API_KEY

Required header for all requests

You need to sign in to get your API key

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 all verticals	`GET`	`/api/v1/verticals`	Paginated list of vertical tags (cursor or limit).
Filter advertisers by vertical	`GET`	`/api/v1/advertisers?vertical_id=...`	Use vertical ID from /api/v1/verticals to filter advertisers.
Filter deals by vertical	`GET`	`/api/v1/deals?vertical_id=...`	Use vertical ID to filter deals.

GET /api/v1/verticals v1

List verticals.

Open

GET /api/v1/verticals?limit=20 v1

List verticals with limit.

Open

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results per page (clamped to 500, default: 20)
`cursor`	string	No	Cursor for pagination (use next_cursor from previous response)
`with_deals`	boolean	No	Filter to only include verticals from advertisers that have active deals
`with_approved`	boolean	No	Filter to only include verticals from advertisers with approved status

Response Format

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

{
  "data": [
    {
      "id": 1,
      "name": "electronics",
      "display_name": "Electronics",
      "description": "Consumer electronics and technology products",
      "advertiser_count": 1250,
      "deal_count": 3400,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "fashion",
      "display_name": "Fashion",
      "description": "Clothing, accessories, and fashion items",
      "advertiser_count": 890,
      "deal_count": 2100,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_next_page": true,
    "next_cursor": "eyJpZCI6MTIzLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoifQ=="
  },
  "meta": {
    "total_count": 150,
    "filters_applied": {
      "with_deals": true
    }
  }
}

Field Reference

Complete reference of all fields returned by the Verticals API:

Basic Vertical Information

Field	Type	Description
`id`	integer	Unique vertical identifier
`name`	string	Vertical name (lowercase, URL-friendly)
`slug`	string	URL-friendly identifier (V1 API only)
`display_name`	string	Human-readable vertical name
`description`	string	Vertical description

Statistics & Metrics

Field	Type	Description
`advertiser_count`	integer	Number of advertisers in this vertical
`deal_count`	integer	Number of deals in this vertical
`active_advertiser_count`	integer	Number of active advertisers
`active_deal_count`	integer	Number of active deals

Timestamps

Field	Type	Description
`created_at`	datetime	Vertical creation timestamp
`updated_at`	datetime	Last update timestamp
`last_deal_at`	datetime	Most recent deal creation date
`last_advertiser_at`	datetime	Most recent advertiser addition date

API Version Differences

Field	Legacy API	V1 API
`name`	Always lowercase	Original case
`slug`	Not included	Auto-generated
`created_at`	Not included	Included
`updated_at`	Not included	Included

Response Structure

Legacy API Format

{
  "verticals": {
    "data": [
      {
        "id": 1,
        "name": "electronics"
      }
    ]
  },
  "meta": { ... }
}

V1 API Format

{
  "data": [
    {
      "id": 1,
      "name": "Electronics",
      "slug": "electronics",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": { ... }
}

Pagination Meta

total_count - Total verticals
per_page - Items per page
current_page - Current page number
next_cursor - Next page cursor (V1)
has_more - More pages available

Examples

Basic Request

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

Get first 10 verticals

Combined Filters

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

Get verticals from approved advertisers that have deals

With Deals Filter

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

Get verticals with active deals

Approved Filter

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

Get verticals from approved advertisers

Advanced Filtering

With Deals Filter

Filter to only include verticals from advertisers that have active deals:

?with_deals=true

This is useful when you only want to show verticals that have promotional deals available.

With Approved Filter

Filter to only include verticals from advertisers with approved status:

?with_approved=true

This ensures you only see verticals from advertisers that are currently active and approved.

Combined Filters

Combine multiple filters for precise results:

?with_deals=true&with_approved=true

Get verticals from approved advertisers with active deals.

Pro Tip: Use with_deals=true when building deal-focused applications to ensure users only see verticals with available promotions.

Pagination

The Verticals API supports cursor-based pagination (when cursor is provided) and offset pagination (page/per_page).

How It Works

Make initial request without cursor
Use next_cursor from response for next page
Continue until has_next_page is false

Pagination Response

{
  "pagination": {
    "limit": 20,
    "has_next_page": true,
    "next_cursor": "eyJpZCI6MTIzLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoifQ=="
  }
}

Performance: Cursor pagination is much faster than offset-based pagination, especially with large datasets, as it doesn't require expensive COUNT queries.

Usage Tips

Filtering Advertisers

Use vertical IDs to filter advertisers by industry:

# Get electronics advertisers
GET /api/v1/advertisers?vertical_id=1

# Get fashion advertisers
GET /api/v1/advertisers?vertical_id=2

Filtering Deals

Use vertical IDs to filter deals by industry:

# Get electronics deals
GET /api/v1/deals?vertical_id=1

# Get fashion deals
GET /api/v1/deals?vertical_id=2

Building Category Menus

Use the verticals API to build dynamic category menus:

# Get all verticals for menu
GET /api/v1/verticals?limit=50

# Get only verticals with deals
GET /api/v1/verticals?with_deals=true

Filtering & UX

Keep vertical lists fast and user-friendly:

# Start with only verticals that matter for deals UIs
GET /api/v1/verticals?with_deals=true&with_approved=true&limit=200

Best Practices:

Use with_deals=true when building deal-focused applications
Use with_approved=true to ensure you only show active advertisers
Store vertical IDs locally to avoid repeated API calls
Filter the returned list client-side to help users find relevant categories

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"
  }
}

Overview

Key Features

Endpoint Details

Base Endpoint

Authentication

API Playground

Parameters

Response Format

Field Reference

Basic Vertical Information

Statistics & Metrics

Timestamps

API Version Differences

Response Structure

Legacy API Format

V1 API Format

Pagination Meta

Examples

Basic Request

Combined Filters

With Deals Filter

Approved Filter

Advanced Filtering

With Deals Filter

With Approved Filter

Combined Filters

Pagination

How It Works

Pagination Response

Usage Tips

Filtering Advertisers

Filtering Deals

Building Category Menus

Filtering & UX

Error Handling

Common Error Codes

Error Response Format

If this page feels TLDR, ask Dex AI.