Skip to content
Last updated

How to Use the AdFlex API

The AdFlex API allows users to explore, filter, and retrieve ads data across multiple advertising platforms including Facebook, Meta, Native, Display, Pinterest, Reddit, X, and YouTube. This guide provides a complete walkthrough of how to interact with the API, including authorization, filters, request structure, and result handling.

🔐 Authentication

The API supports two types of authentication methods:

  1. Header-Based Authentication – Provide your API Key in the headers using:

    x-api-key: YOUR_API_KEY

  2. Body-Based Authentication – Authentication details may be passed in the request body or query string using:

    api_key: YOUR_API_KEY

By default, the api_key element exists in all sample requests. But you can change the default authentication method and use the x-api-key header instead. Make sure to include authentication with all requests.

📦 Base Response Structure

Every API response from AdFlex follows a standardized structure:

{
  "status": "ok",
  "meta": {
    "code": 1000,
    "message": null
  },
  "data": { ... }
}
  • status: Indicates if the request was successful (ok) or not (failed).
  • meta.code: A numeric code representing the result.
  • meta.message: A human-readable message. It may be null for successful requests.

Refer to the API Status Codes Documentation for a full list of possible codes and messages.

🔍 Step 1: Retrieve Dynamic Filters

Use the following endpoint to retrieve platform-specific filters:

Endpoint:
GET /filters/{platform}/search

Replace {platform} with the desired platform (e.g., facebook, meta, native, display, pinterest).

Each filter object includes:

  • key: The parameter to use in the search request body.
  • component: The filter type, such as:
    • StringMultiApi: Fetches options dynamically using an api_url.
    • StringMulti: Options are listed directly in component_data.items.
    • NumberMultiRange, SearchBox, and others for more specific types.
  • component_data.api_url: A URL pointing to an API route (e.g., /v1/facebook/filter/interests/items) to retrieve filter items. You must send a request with "search" or "id" in the body to this endpoint to fetch the available options.
  • sub_keys: If present, the filter expects a more complex structure. For example:

🧩 Example: Complex Filter with sub_keys

The search_field filter includes:

"sub_keys": {
  "type": "type",
  "main": "text"
}

This means that the request body should include:

"search_field": [
  { "type": "text", "text": "Club" },
  { "type": "without_fanpage", "text": "Runners" }
]

Each object inside the array follows the structure defined by sub_keys.

📤 Step 2: Search Ads Using Filters

Once you have the filters, you can use them to send a search request:

Endpoint:
POST /{platform}/ads/search

Use the key field from each filter to construct the body. Refer to sub_keys if applicable. Example request:

{
  "page": 1,
  "orderby": "updated_at",
  "behaviors": [50, 61],
  "interests": [198],
  "search_field": [
    { "type": "text", "text": "Club" },
    { "type": "without_fanpage", "text": "Runners" }
  ]
}

📄 Step 3: View Ad Details

To get detailed data on an individual ad, use its ID from the search result.

Endpoint:
GET /{platform}/ads/{ad}

Replace {platform} with the correct platform and {ad} with the ad ID.

🔁 Summary

  1. Authenticate via header or body.
  2. Call GET /filters/{platform}/search to get filters.
  3. Use those filters to build your POST /{platform}/ads/search request.
  4. Use ad id to call GET /{platform}/ads/{ad} for detailed info.

📘 See Also

Previous page
Next page