# Ad Campaign Category

{% hint style="info" %}
For an overview of key concepts and the full campaign setup lifecycle, see the [Ad Campaign Management overview](/advertiser-apis/advertiser-guides/ad-campaign-management.md). For a visual overview of how these resources relate to each other, see the [Entity Diagram](/advertiser-apis/advertiser-guides/ad-campaign-management/entity-diagram.md).
{% endhint %}

Categories define what your campaign targets. Each category is associated with a price and can optionally be linked to a campaign listing.

## Authentication

These endpoints require API-key authentication. See the [Authentication Guide](/advertiser-apis/advertiser-guides/authentication.md) for details on obtaining and using your API key.

## List Ad Campaign Categories

```http
GET https://apis.elocal.com/advertisers/v2/account/{accountId}/ad-campaign/{adCampaignId}/ad-campaign-category
```

**Query parameters:** `page`, `size`

**Response:**

```json
{
  "content": [
    {
      "ad_campaign_category_id": 1,
      "ad_campaign_id": 10,
      "ad_campaign_listing_id": 5,
      "category_id": 42,
      "price": 25.00,
      "target_status": "ACTIVE"
    }
  ],
  "page": 0,
  "size": 20,
  "total_elements": 1,
  "total_pages": 1,
  "first": true,
  "last": true
}
```

***

## Get an Ad Campaign Category

```http
GET https://apis.elocal.com/advertisers/v2/account/{accountId}/ad-campaign/{adCampaignId}/ad-campaign-category/{adCampaignCategoryId}
```

**Response:**

```json
{
  "ad_campaign_category_id": 1,
  "ad_campaign_id": 10,
  "ad_campaign_listing_id": 5,
  "category_id": 42,
  "price": 25.00,
  "target_status": "ACTIVE"
}
```

***

## Create an Ad Campaign Category

```http
POST https://apis.elocal.com/advertisers/v2/account/{accountId}/ad-campaign/{adCampaignId}/ad-campaign-category
Content-Type: application/json
```

**Request body:**

```json
{
  "category_id": 42,
  "price": 25.00,
  "ad_campaign_listing_id": 5
}
```

| Field                    | Type    | Required | Description                                                                                                                                                      |
| ------------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category_id`            | integer | Yes      | Category ID — use the [Categories lookup](/advertiser-apis/advertiser-guides/lookup-apis.md#categories) to find valid IDs for the services you want to advertise |
| `price`                  | decimal | Yes      | Maximum price you're willing to pay per lead in this category                                                                                                    |
| `ad_campaign_listing_id` | integer | No       | Campaign listing to associate with — must belong to the same campaign                                                                                            |

**Response:** The created ad campaign category object.

***

## Update an Ad Campaign Category

```http
PUT https://apis.elocal.com/advertisers/v2/account/{accountId}/ad-campaign/{adCampaignId}/ad-campaign-category/{adCampaignCategoryId}
Content-Type: application/json
```

**Request body:** Include only the fields you want to update.

```json
{
  "price": 30.00,
  "target_status": "INACTIVE"
}
```

| Field           | Type    | Required | Description                    |
| --------------- | ------- | -------- | ------------------------------ |
| `price`         | decimal | No       | Updated maximum price per lead |
| `target_status` | string  | No       | `ACTIVE` or `INACTIVE`         |

At least one field must be provided in the update request.

**Response:** The updated ad campaign category object.

***

## Status Codes

| Code | Description                                        |
| ---- | -------------------------------------------------- |
| 200  | Success                                            |
| 400  | Invalid request (e.g., missing required fields)    |
| 401  | Unauthorized — API key invalid or account mismatch |
| 403  | Forbidden                                          |
| 404  | Campaign or category not found                     |
| 500  | Internal server error                              |

## What's Next?

With categories set, [configure geographies](/advertiser-apis/advertiser-guides/ad-campaign-management/ad-campaign-geography.md) to define the postal codes where you want to receive leads.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.elocal.com/advertiser-apis/advertiser-guides/ad-campaign-management/ad-campaign-category.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.