Creating Ads using the Unified Ads API

March 14, 2026

Unified Ads API Overview

The Unified API Ads category models advertising structures across Meta, Google, Amazon, Twitter, LinkedIn, and other providers. Understanding how objects relate helps you build the correc flows.

Core Hierarchy

Most integrations follow a hierarchy from organization → campaign → ad group → ad:

ads_organization (ad account)
    └── ads_campaign
            └── ads_group (ad set, line item, etc.)
                    └── ads_ad

Creatives and Insertion Orders

Discovery

Reporting

Provider Mapping

Naming varies by provider:

Some integrations collapse levels (e.g., LinkedIn's "Campaign" maps to our ads_group).

Creating Ads: Required Parent IDs

When creating objects, you typically need parent IDs:

• Create campaign: organization_id
• Create ad group: organization_id, campaign_id
• Create ad: organization_id, campaign_id, group_id
• Create creative: organization_id, campaign_id, group_id (varies by provider)

The promoted field is required when creating ad groups or ads that need a promoted entity (e.g., Meta ad set with a page, Twitter promoted tweet with a tweet ID). Use ads_promote to discover options, or pass IDs manually when the provider has no list API.

Promoted Explained

The new promoted field specifies promoted entities (pages, apps, products, tweets, ad group types) when creating and managing ads across the Unified API.

Ads, Campaigns, and AdGroups have a promoted field to specify an ID of an entity to promote. There is also a ads_promote endpoint that provides a clean way to query the promoted entities.

{
  "organization_id": "act_123",
  "campaign_id": "456",
  "name": "My Ad Group",
  "promoted": [
    { "id": "789", "type": "PAGE_ID" }
  ]
}

The AdsPromoted Object

Each promoted entity has a simple structure:

Supported Promoted Types

GET /ads/{connection_id}/promoted Endpoint

Use the ads_promote list endpoint to discover available promoted entities that the integration supports.

Endpoint: GET /ads/{connection_id}/promote

Query parameters:

Example: List Facebook Pages (Meta Ads)

GET /ads/{connection_id}/promote?type=PAGE_ID

Response:

[
    { "id": "123456789", "name": "My Business Page", "type": "PAGE_ID" },
    { "id": "987654321", "name": "Another Page", "type": "PAGE_ID" }
]

Example: List User Tweets (Twitter Ads)

GET /ads/{connection_id}/promote?type=TWEET_ID

Example: List Ad Group Types (Google Ads, LinkedIn)

GET /ads/{connection_id}/promote?type=AD_GROUP_TYPE

Some integrations will return static options (e.g., SEARCH_STANDARD, DISPLAY_STANDARD for Google; SPONSORED_UPDATES, TEXT_ADS for LinkedIn).

When ads_promoted Returns Empty

Some promoted types have no discovery API (e.g., Amazon PRODUCT_ID, Meta STORE_URL). In those cases, ads_promote returns an empty array. You can still create ads by passing promoted manually with IDs you already know (e.g., ASINs for Amazon, store URLs for Meta).

Quick Reference: Create Examples

Meta Ads – Create Ad Group with Page

POST /ads/{connection_id}/group
{
  "organization_id": "act_123",
  "campaign_id": "456",
  "name": "My Ad Group",
  "promoted": [{ "id": "789", "type": "PAGE_ID" }]
}

Amazon Ads – Create Product Ad

POST /ads/{connection_id}/ad
{
  "organization_id": "profile_123",
  "campaign_id": "456",
  "group_id": "789",
  "name": "Product Ad",
  "promoted": [{ "id": "B08N5WRWNW", "type": "PRODUCT_ID" }]
}

Twitter Ads – Create Promoted Tweet

POST /ads/{connection_id}/ad
{
  "organization_id": "account_123",
  "group_id": "line_item_456",
  "name": "Promoted Tweet",
  "promoted": [{ "id": "1234567890", "type": "TWEET_ID" }]
}

LinkedIn – Create Ad Group (Campaign)

POST /ads/{connection_id}/group
{
  "organization_id": "123",
  "campaign_id": "456",
  "name": "Sponsored Updates Campaign",
  "promoted": [{ "id": "SPONSORED_UPDATES", "type": "AD_GROUP_TYPE" }]
}

Google Ads – Create Ad Group

POST /ads/{connection_id}/group
{
  "organization_id": "123",
  "campaign_id": "456",
  "name": "Search Ad Group",
  "promoted": [{ "id": "SEARCH_STANDARD", "type": "AD_GROUP_TYPE" }]
}

Using Targeting

Targeting lets you define who sees your ads (geography, demographics, interests, etc.). Use the ads_target endpoint to look up valid targeting IDs, then pass them in the targeting field when creating campaigns, ad groups, or ads.

The ads_target Endpoint

Look up targeting options (countries, regions, cities, interests, etc.) before creating ad objects.

Endpoint: GET /ads/{connection_id}/target

Query parameters:

Supported type values: countries, regions, cities, zips, us_dmas, locales, interests, behaviors, topics, user_lists, age_ranges, genders

Support varies by integration. Meta Ads supports most types; others (e.g., Amazon, Twitter) may support only countries and locales__.

Example: Look Up Countries

GET /ads/{connection_id}/target?type=countries&query=united

Response:

[
    { "id": "US", "name": "United States", "value": "US", "type": "countries" },
    { "id": "GB", "name": "United Kingdom", "value": "GB", "type": "countries" }
]

Example: Look Up Regions (e.g., US States)

GET /ads/{connection_id}/target?type=regions&query=california

Response:

[
    { "id": "3843", "name": "California", "value": "3843", "type": "regions" }
]

Example: Look Up Interests (Meta Ads)

GET /ads/{connection_id}/target?type=interests&query=technology

Using Targeting IDs When Creating Ads

Pass the id (or value) from ads_target responses into the targeting object. The structure matches the targeting type:

• Countries: targeting.geographic.countries — array of ISO country codes (e.g., ["US", "CA"])
• Regions: targeting.geographic.regions — array of { id, name? } (use id from ads_target)
• Cities: targeting.geographic.cities — array of { id, name?, radius?, radius_unit? }
• Demographics: targeting.demographic — age and gender (no lookup needed; use values directly)

Targeting Examples

Geo-Targeting: Countries and Regions

First, look up IDs:

# Get country codes
GET /ads/{connection_id}/target?type=countries&query=united

# Get regions (e.g., states) — for regions, query often includes country context
GET /ads/{connection_id}/target?type=regions&query=california

Then create an ad group with geographic targeting:

POST /ads/{connection_id}/group
{
  "organization_id": "act_123",
  "campaign_id": "456",
  "name": "US & California Ad Group",
  "promoted": [{ "id": "789", "type": "PAGE_ID" }],
  "targeting": {
    "geographic": {
      "countries": ["US"],
      "regions": [
        { "id": "3843", "name": "California" }
      ]
    }
  }
}

Geo-Targeting: Cities with Radius

{
  "targeting": {
    "geographic": {
      "countries": ["US"],
      "cities": [
        {
          "id": "2420379",
          "name": "San Francisco",
          "radius": 25,
          "radius_unit": "MILES"
        }
      ]
    }
  }
}

Demographic Targeting

Demographic targeting uses simple values; no ads_target lookup is needed:

{
  "targeting": {
    "demographic": {
      "age_min": 25,
      "age_max": 54,
      "male": true,
      "female": true
    }
  }
}

• age_min / age_max: 18–65 typically
• male / female: true to include, false or omit to exclude

Combined Geo + Demographic Targeting

POST /ads/{connection_id}/group
{
  "organization_id": "act_123",
  "campaign_id": "456",
  "name": "US Adults 25-54",
  "promoted": [{ "id": "789", "type": "PAGE_ID" }],
  "targeting": {
    "geographic": {
      "countries": ["US"]
    },
    "demographic": {
      "age_min": 25,
      "age_max": 54,
      "male": true,
      "female": true
    }
  }
}

Audience Targeting (Interests, Custom Audiences)

For interests and custom audiences, look up IDs first:

GET /ads/{connection_id}/target?type=interests&query=technology
GET /ads/{connection_id}/target?type=user_lists&query=my&org_id=act_123

Then use the id values in targeting.audience:

{
  "targeting": {
    "audience": {
      "interests": [
        { "id": "600313926646746", "name": "Technology" }
      ],
      "custom_audiences": [
        { "id": "12345678", "name": "My Custom Audience" }
      ]
    }
  }
}