# 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:


```json
{
  "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](/status_codes) 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:


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

This means that the request body should include:


```json
"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:


```json
{
  "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

- [API Status Codes](/status_codes)
- [OpenAPI Documentation](https://adflex.redocly.app/openapi)