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, YouTube, and TikTok. This guide provides a complete walkthrough of how to interact with the API, including authorization, filters, request structure, and result handling.

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.

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.

Use the following endpoint to retrieve platform-specific filters:

Endpoint:
GET /ads/{platform}/filters

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 items.
  • NumberMultiRange, SearchBox, and others for more specific types.
• api_url: A URL pointing to an API route (e.g., /v2/ads/facebook/filters/interests) to retrieve filter items. You must send a request with "search" in the body to this endpoint to fetch the available options.
• sub_keys: If present, the filter expects a more complex structure. For example:

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_owner", "text": "Runners" }
]

Or the advanced_order filter includes:

"sub_keys": {
  "type": "order",
  "main": "orderby"
}

This means that the request body should include:

"advanced_order": {
  "orderby": "web_traffic",
  "order": "desc"
}

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

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

Endpoint:
POST /ads/{platform}/search

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

{
  "page": 1,
  "advanced_order": {
    "orderby": "web_traffic",
    "order": "desc"
  },
  "behaviors": [50, 61],
  "interests": [198],
  "search_field": [
    { "type": "text", "text": "Club" },
    { "type": "without_owner", "text": "Runners" }
  ]
}

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

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

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

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

• API Status Codes
• OpenAPI Documentation