---
title: "Create an Ad Group"
method: POST
path: "/ad_groups"
tags: ["Ad Groups"]
---

# Create an Ad Group

`POST /ad_groups`

Creates an ad group (ad set) in a campaign.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `ad_campaign_id` string, required — The ad campaign to create the ad group in, prefixed `adcamp_`.
  - `audiences` AdGroupAudiencesBody — Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic.
    - `exclude` string[] — IDs of saved audiences to exclude from delivery, prefixed `adaud_`.
    - `include` string[] — IDs of saved audiences to deliver to, prefixed `adaud_`.
  - `bid_type` 'minimum_cost' | 'average_target' | 'maximum_target' — How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.
  - `budget_amount` number — This ad group's budget, in the ad account's currency. Omit when the budget is set on the campaign instead.
  - `budget_type` 'daily' | 'lifetime' — Whether budget_amount is spent per day (`daily`) or over the ad group's full run (`lifetime`).
  - `conversion_event` union — The pixel event optimized for. A standard event, or any custom pixel event name.
    - 'purchase' | 'add_to_cart' | 'initiated_checkout' | 'add_payment_info' | 'complete_registration' | 'lead' | 'content_view' | 'search' | 'contact' | 'customize_product' | 'donate' | 'find_location' | 'schedule' | 'start_trial' | 'submit_application' | 'subscribe'
    - string
  - `conversion_location` 'website' | 'profile' | 'instagram_and_facebook' | 'instagram_profile' | 'messaging' | 'on_ad' | 'instant_forms' | 'instant_forms_and_messenger' | 'website_and_instant_forms' — Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. The lead form itself is set on the ad.
  - `demographics` AdGroupDemographicsBody — Age, gender, and automatic-audience targeting.
    - `automatic` boolean — Turn on automatic audience targeting (Advantage+ on Meta): the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.
    - `gender` 'all' | 'male' | 'female' — Gender to target.
    - `maximum_age` integer — Oldest age to target.
    - `minimum_age` integer — Youngest age to target.
  - `desired_cost_per_result` number — Cost per result to aim for (`average_target`) or never exceed (`maximum_target`).
  - `detailed_targeting` AdGroupDetailedTargetingBody — Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories.
    - `behaviors` object[] — Behavior categories to target, such as frequent travelers.
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Movies`.
    - `demographics` object[] — Demographic categories to target, such as life events or industries.
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Recently moved`.
      - `type` 'life_events' | 'industries' | 'income' | 'family_statuses', required — Kind of demographic the category belongs to.
    - `interests` object[] — Interest categories to target, such as an interest in movies.
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Movies`.
  - `devices` AdGroupDevicesBody — Device platforms and operating systems to target.
    - `operating_systems` object[] — Operating systems to target. Empty targets all operating systems.
      - `minimum_version` string — Lowest OS version to target, such as `18.0`. Omit to target any version.
      - `os` 'ios' | 'android', required — Operating system to target.
    - `platforms` string[] — Device types to target. Empty targets all devices.
  - `dynamic_creative` boolean — Let the ad platform automatically mix and match this ad group's creatives and copy to find the best-performing combinations. Set at creation; can't be changed afterward.
  - `ends_at` string — When the ad group stops delivering, as an ISO 8601 timestamp. Omit to run until paused.
  - `frequency_cap` object — Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective.
    - `maximum_impressions` integer — Most times one person can be shown ads from this ad group within the window.
    - `per_days` integer — Length of the rolling window, in days.
  - `languages` string[] — Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.
  - `message_apps` string[] — Apps the conversation opens in. Required when setting `conversion_location` to `messaging`, and rejected unless the ad group's conversion location is `messaging`.
  - `minimum_daily_spend` number — Minimum the ad group tries to spend each day.
  - `optimization_goal` 'conversions' | 'link_clicks' | 'landing_page_views' | 'reach' | 'impressions' | 'engagement' | 'conversations' | 'video_views' | 'two_second_views' | 'page_likes' | 'social_profile' | 'ad_recall_lift' | 'event_responses' | 'reminders_set' | 'lead_generation' | 'quality_lead' | 'value' | 'profile_and_page_engagement' — The result the ad group's delivery is optimized to get the most of.
  - `placements` union — `automatic` to let the ad platform choose placements, or the list of platforms and positions to target. Omit a platform's positions to target all of them. Valid positions per platform: - `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`, `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `biz_disco_feed` - `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `profile_reels`, `ig_search` - `messenger`: `story` - `audience_network`: `classic`, `rewarded_video` - `threads`: `threads_stream` - `whatsapp`: `status`
    - 'automatic'
    - object[]
      - `platform` 'facebook' | 'instagram' | 'messenger' | 'audience_network' | 'threads' | 'whatsapp', required — Platform the ads run on.
      - `positions` string[] — Positions to target within the platform, such as `feed` or `story`. Omit to target all of the platform's positions.
  - `regions` AdGroupRegionsBody — Locations to target and exclude.
    - `exclude` AdGroupGeoLocationsBody
      - `cities` object[] — Cities, keyed by the ad platform's location taxonomy.
        - `key` string, required — The ad platform's key for the city in its location taxonomy.
        - `name` string — City name, such as `Austin`.
      - `countries` string[] — Countries, as ISO 3166-1 alpha-2 codes such as `US`.
      - `country_groups` string[] — Multi-country groups such as `worldwide` or `europe`. Include-only — groups can't be excluded.
      - `custom_locations` object[] — Circular areas, each a coordinate plus a radius. At most 200 across include and exclude.
        - `distance_unit` 'mile' | 'kilometer' — Unit for `radius`. Defaults to `mile`.
        - `latitude` number, required — Latitude of the center point.
        - `longitude` number, required — Longitude of the center point.
        - `name` string — Label for the location, such as a city or address.
        - `radius` number, required — Radius around the center point: 1-50 miles or 1-80 kilometers.
      - `regions` string[] — US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.
      - `zips` union[] — ZIP and postal codes, as bare strings or objects with a key.
        - union
          - string
          - object
            - `key` string, required — The ZIP or postal code.
    - `include` AdGroupGeoLocationsBody
      - `cities` object[] — Cities, keyed by the ad platform's location taxonomy.
        - `key` string, required — The ad platform's key for the city in its location taxonomy.
        - `name` string — City name, such as `Austin`.
      - `countries` string[] — Countries, as ISO 3166-1 alpha-2 codes such as `US`.
      - `country_groups` string[] — Multi-country groups such as `worldwide` or `europe`. Include-only — groups can't be excluded.
      - `custom_locations` object[] — Circular areas, each a coordinate plus a radius. At most 200 across include and exclude.
        - `distance_unit` 'mile' | 'kilometer' — Unit for `radius`. Defaults to `mile`.
        - `latitude` number, required — Latitude of the center point.
        - `longitude` number, required — Longitude of the center point.
        - `name` string — Label for the location, such as a city or address.
        - `radius` number, required — Radius around the center point: 1-50 miles or 1-80 kilometers.
      - `regions` string[] — US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.
      - `zips` union[] — ZIP and postal codes, as bare strings or objects with a key.
        - union
          - string
          - object
            - `key` string, required — The ZIP or postal code.
  - `starts_at` string — When the ad group starts delivering, as an ISO 8601 timestamp. Omit to start as soon as it's active.
  - `status` 'active' | 'paused' — Initial status (default: `active`).
  - `title` string — The display name of the ad group.

## Response `200`

ad group created

- AdGroup
  - `ad_campaign` AdEntityReference, required
    - `id` string, required — The referenced entity's id.
  - `added_to_cart_value` number, required — USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `added_to_carts` number, required — Whop pixel-attributed add-to-cart events, last-click.
  - `audiences` AdGroupAudiences, required
    - `exclude` string[], required
    - `include` string[], required
  - `bid_type` 'minimum_cost' | 'average_target' | 'maximum_target' | 'null', nullable, required — How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.
  - `budget_amount` number, nullable, required — This ad group's budget, in the ad account's currency. `null` when the budget is set on the campaign instead.
  - `budget_type` 'daily' | 'lifetime' | 'null', nullable, required — Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`).
  - `click_through_rate` number, required — Clicks divided by impressions, between 0 and 1.
  - `clicks` number, required — The number of clicks.
  - `completed_registration_value` number, required — USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `completed_registrations` number, required — Whop pixel-attributed complete-registration events, last-click.
  - `contact_value` number, required — USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `contacts` number, required — Whop pixel-attributed contact events, last-click.
  - `conversion_event` union — The pixel event optimized for. A standard event, or any custom pixel event name.
    - 'purchase' | 'add_to_cart' | 'initiated_checkout' | 'add_payment_info' | 'complete_registration' | 'lead' | 'content_view' | 'search' | 'contact' | 'customize_product' | 'donate' | 'find_location' | 'schedule' | 'start_trial' | 'submit_application' | 'subscribe'
    - string
  - `conversion_location` 'website' | 'profile' | 'instagram_and_facebook' | 'instagram_profile' | 'messaging' | 'on_ad' | 'instant_forms' | 'instant_forms_and_messenger' | 'website_and_instant_forms' | 'null', nullable — Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.
  - `cost_per_added_to_cart` number, nullable, required — Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.
  - `cost_per_click` number, required — Spend divided by clicks; 0 when there are no clicks.
  - `cost_per_completed_registration` number, nullable, required — Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.
  - `cost_per_contact` number, nullable, required — Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.
  - `cost_per_lead` number, nullable, required — Spend divided by attributed leads; null when leads are not a goal and none are attributed.
  - `cost_per_mille` number, required — Spend per 1,000 impressions; 0 when there are no impressions.
  - `cost_per_purchase` number, nullable, required — Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.
  - `cost_per_result` number, nullable, required — Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.
  - `cost_per_schedule` number, nullable, required — Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.
  - `cost_per_submitted_application` number, nullable, required — Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.
  - `cost_per_unique_click` number, nullable, required — Spend divided by unique clicks; null when there are no unique clicks.
  - `cost_per_viewed_content` number, nullable, required — Spend divided by attributed view-content events; null when they are not the goal and none are attributed.
  - `created_at` string, required — When the ad group was created, as an ISO 8601 timestamp.
  - `custom_conversions` number, required — Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.
  - `custom_event_counts` object, required — Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.
  - `custom_event_values` object, required — Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.
  - `delivery_status` 'all_ads_rejected' | 'rejected' | 'draft' | 'no_ads' | 'campaign_paused' | 'paused' | 'processing' | 'issues' | 'scheduled' | 'completed' | 'ads_off' | 'learning_limited' | 'learning' | 'active', required — Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.
  - `demographics` AdGroupDemographics, required
    - `automatic` boolean, required — Whether automatic audience targeting is on (Advantage+ on Meta). When `true`, the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.
    - `gender` 'all' | 'male' | 'female', required — Gender targeted.
    - `maximum_age` number, nullable, required — Oldest age targeted. `null` when no maximum is set.
    - `minimum_age` number, nullable, required — Youngest age targeted. `null` when no minimum is set.
  - `desired_cost_per_result` number, nullable, required — Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). `null` for `minimum_cost` bidding.
  - `detailed_targeting` AdGroupDetailedTargeting
    - `behaviors` AdGroupTargetingCategory[], required
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Movies`.
    - `demographics` AdGroupDemographicCategory[], required
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Recently moved`.
      - `type` 'life_events' | 'industries' | 'income' | 'family_statuses', required — Kind of demographic the category belongs to.
    - `interests` AdGroupTargetingCategory[], required
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Movies`.
  - `devices` AdGroupDevices
    - `operating_systems` AdGroupOperatingSystem[], required
      - `minimum_version` string — Lowest OS version targeted, such as `18.0`. Absent when any version qualifies.
      - `os` 'ios' | 'android', required — Operating system targeted.
    - `platforms` string[], required
  - `dynamic_creative` boolean — Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations.
  - `ends_at` string, nullable, required — When the ad group stops delivering, as an ISO 8601 timestamp. `null` when it runs until paused.
  - `frequency` number, nullable, required — Platform-reported impressions divided by reach.
  - `frequency_cap` AdGroupFrequencyCap
    - `maximum_impressions` number, required — Most times one person can be shown ads from this ad group within the window.
    - `per_days` number, nullable, required — Length of the rolling window, in days.
  - `id` string, required — Unique identifier for the ad group, prefixed `adgrp_`.
  - `impressions` number, required — The number of impressions.
  - `issues` AdPlatformIssue[], required
    - `id` string, required — Unique identifier for the issue.
    - `message` string, required — A description of what the issue is and how it can be resolved.
    - `resource_id` string, nullable, required — The ID of the campaign, ad group, or ad the issue is attached to.
    - `resource_type` 'ad_campaign' | 'ad_group' | 'ad', required — The type of resource the issue is attached to.
  - `languages` string[]
  - `lead_value` number, required — USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `leads` number, required — Whop pixel-attributed leads, last-click.
  - `message_apps` string[]
  - `minimum_daily_spend` number, nullable — Minimum the ad group tries to spend each day. `null` when no floor is set.
  - `optimization_goal` 'conversions' | 'link_clicks' | 'landing_page_views' | 'reach' | 'impressions' | 'engagement' | 'conversations' | 'video_views' | 'two_second_views' | 'page_likes' | 'social_profile' | 'ad_recall_lift' | 'event_responses' | 'reminders_set' | 'lead_generation' | 'quality_lead' | 'value' | 'profile_and_page_engagement' | 'null', nullable, required — The result the ad group's delivery is optimized to get the most of.
  - `placements` AdGroupPlacement[]
    - `platform` 'facebook' | 'instagram' | 'messenger' | 'audience_network' | 'threads' | 'whatsapp', required — Publisher platform where the ad is eligible to appear.
    - `positions` string[], required
  - `purchase_value` number, required — USD value of pixel-attributed purchases.
  - `purchases` number, required — Whop pixel-attributed purchases, last-click.
  - `reach` number, required — The number of unique people who saw this.
  - `regions` AdGroupRegions
    - `exclude` AdGroupGeoLocations, required
      - `cities` AdGroupCity[], required
        - `key` string, required — The ad platform's key for the city in its location taxonomy.
        - `name` string — City name, such as `Austin`. Absent when the platform doesn't return one.
      - `countries` string[], required
      - `country_groups` string[], required
      - `custom_locations` AdGroupCustomLocation[], required
        - `distance_unit` 'mile' | 'kilometer', required — Unit for `radius`.
        - `latitude` number, required — Latitude of the center point.
        - `longitude` number, required — Longitude of the center point.
        - `name` string — Label for the location, such as a city or address. Absent when the location has no label.
        - `radius` number, required — Radius around the center point, in `distance_unit`.
      - `regions` string[], required
      - `zips` string[], required
    - `include` AdGroupGeoLocations, required
      - `cities` AdGroupCity[], required
        - `key` string, required — The ad platform's key for the city in its location taxonomy.
        - `name` string — City name, such as `Austin`. Absent when the platform doesn't return one.
      - `countries` string[], required
      - `country_groups` string[], required
      - `custom_locations` AdGroupCustomLocation[], required
        - `distance_unit` 'mile' | 'kilometer', required — Unit for `radius`.
        - `latitude` number, required — Latitude of the center point.
        - `longitude` number, required — Longitude of the center point.
        - `name` string — Label for the location, such as a city or address. Absent when the location has no label.
        - `radius` number, required — Radius around the center point, in `distance_unit`.
      - `regions` string[], required
      - `zips` string[], required
  - `result_event` 'purchase' | 'lead' | 'schedule' | 'submit_application' | 'contact' | 'complete_registration' | 'view_content' | 'add_to_cart' | 'custom' | 'null', nullable, required — The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.
  - `result_event_name` string, nullable, required — The merchant-defined event name when result_event is custom; null for the standard events.
  - `results` number, nullable, required — The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.
  - `return_on_ad_spend` number, required — Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.
  - `schedule_value` number, required — USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `schedules` number, required — Whop pixel-attributed schedule events, last-click.
  - `spend` number, required — The amount charged, in spend_currency.
  - `spend_currency` string, nullable, required — The ISO 4217 currency code of all monetary metrics.
  - `starts_at` string, nullable, required — When the ad group starts delivering, as an ISO 8601 timestamp. `null` when it starts as soon as it's active.
  - `status` 'active' | 'paused' | 'rejected' | 'duplicating', required — Whether the ad group is enabled. `active` and `paused` are set by you; `rejected` means it failed ad review; `duplicating` is a copy still being filled in.
  - `submitted_application_value` number, required — USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `submitted_applications` number, required — Whop pixel-attributed submit-application events, last-click.
  - `title` string, nullable, required — Display name of the ad group.
  - `unique_click_through_rate` number, nullable, required — Unique clicks divided by impressions, between 0 and 1.
  - `unique_clicks` number, required — People who clicked, reported by the Whop pixel, counted once per person.
  - `updated_at` string, required — When the ad group was last updated, as an ISO 8601 timestamp.
  - `viewed_content_value` number, required — USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.
  - `viewed_contents` number, required — Whop pixel-attributed view-content events, last-click.

## Other responses

- `404` — Resource not found

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/db0883548bc5/schema)