---
title: "Creating Ads using the Unified Ads API"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/creating_ads_using_the_unified_ads_api-icon.png
date: 2026-03-14T23:39:00.000Z
tag: Guides
description: "The Unified API Ads category models advertising structures across Meta, Google, Amazon, Twitter, LinkedIn, and other providers. Understanding how objects..."
url: "https://unified.to/blog/creating_ads_using_the_unified_ads_api"
---

# Creating Ads using the Unified Ads API
------
_March 14, 2026_

# Unified Ads API Overview


The [Unified API](/technology) 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:


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


| Object               | Description                                                                                                    | Parent(s)                                    | Typical use                                                               |
| -------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| **ads_organization** | The ad account (e.g., Meta ad account, Google Ads customer). Billing and access are scoped here.               | —                                            | List accounts, select which account to use                                |
| **ads_campaign**     | A campaign groups ad sets under a goal, budget, and schedule.                                                  | `organization_id`                            | Set campaign-level budget, dates, objective                               |
| **ads_group**        | An ad set or line item. Holds targeting, bid, and budget. Often called "ad set" (Meta) or "line item" (DV360). | `campaign_id`, `organization_id`             | Define who sees ads (targeting), bid strategy, promoted object            |
| **ads_ad**           | The actual ad creative + placement. What users see.                                                            | `group_id`, `campaign_id`, `organization_id` | Creative content, destination URL, promoted entity (e.g., tweet, product) |
### Creatives and Insertion Orders


| Object                 | Description                                                                                                         | Parent(s)                                    | Notes                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| **ads_creative**       | The creative asset (image, video, copy). Some providers treat it as a separate resource; others embed it in the ad. | `group_id`, `campaign_id`, `organization_id` | Meta: can be shared across ads. Amazon/Twitter: often 1:1 with ad. |
| **ads_insertionorder** | DV360-specific. Sits between campaign and line item.                                                                | `campaign_id`, `organization_id`             | Similar to a purchase order for a campaign.                        |
### Discovery


| Object          | Description                                                        | Purpose                                                                 |
| --------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| **ads_target**  | Targeting options (countries, regions, interests, etc.).           | Look up valid IDs to use in `targeting` when creating campaigns/groups. |
| **ads_promote** | Promoted entities (pages, apps, products, tweets, ad group types). | Look up or pass IDs for `promoted` when creating groups/ads/creatives.  |
###  Reporting


| Object         | Description          | Purpose                                                                |
| -------------- | -------------------- | ---------------------------------------------------------------------- |
| **ads_report** | Performance metrics. | Fetch impressions, clicks, spend, etc. by org, campaign, group, or ad. |
### Provider Mapping


Naming varies by provider:


| Unified API      | Meta Ads    | Google Ads | Amazon Ads | Twitter Ads    | LinkedIn          |
| ---------------- | ----------- | ---------- | ---------- | -------------- | ----------------- |
| ads_organization | Ad Account  | Customer   | Profile    | Account        | Sponsored Account |
| ads_campaign     | Campaign    | Campaign   | Campaign   | Campaign       | Campaign Group    |
| ads_group        | Ad Set      | Ad Group   | Ad Group   | Line Item      | Campaign          |
| ads_ad           | Ad          | Ad         | Product Ad | Promoted Tweet | Creative          |
| ads_creative     | Ad Creative | Ad         | Product Ad | Promoted Tweet | Creative          |
_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.


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


| Field  | Type   | Required | Description                                     |
| ------ | ------ | -------- | ----------------------------------------------- |
| `id`   | string | Yes      | The entity ID (e.g., page ID, ASIN, tweet ID)   |
| `name` | string | No       | Display name (optional, used in list responses) |
| `type` | string | Yes      | One of the supported promoted types (see below) |
### Supported Promoted Types


| Type            | Integration(s)       | Description                                                       |
| --------------- | -------------------- | ----------------------------------------------------------------- |
| `PAGE_ID`       | Meta Ads             | Facebook Page to promote                                          |
| `APP_ID`        | Meta Ads             | App to promote                                                    |
| `PIXEL_ID`      | Meta Ads             | Conversion pixel                                                  |
| `CATALOG_ID`    | Meta Ads             | Product catalog                                                   |
| `STORE_URL`     | Meta Ads             | Store URL (manual input)                                          |
| `PRODUCT_ID`    | Amazon Ads           | Product ASIN (manual input)                                       |
| `TWEET_ID`      | Twitter Ads          | Tweet to promote                                                  |
| `AD_GROUP_TYPE` | LinkedIn, Google Ads | Campaign/ad group type (e.g., SPONSORED_UPDATES, SEARCH_STANDARD) |
---


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


| Parameter | Type   | Description                                           |
| --------- | ------ | ----------------------------------------------------- |
| `type`    | string | Filter by promoted type (e.g., `PAGE_ID`, `TWEET_ID`) |
| `org_id`  | string | Organization/account I                                |
| `query`   | string | Optional search filter                                |
| `limit`   | number | Max results (default 100)                             |
| `offset`  | number | Pagination offset                                     |
### Example: List Facebook Pages (Meta Ads)


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


Response:


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


### Example: List User Tweets (Twitter Ads)


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


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


```bash
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


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


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


```json
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)


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


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


| Parameter | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `type`    | string | Yes      | Targeting type (see supported types below)        |
| `query`   | string | Yes*     | Search term (*required for most types)            |
| `org_id`  | string | No       | Organization/account ID (required for some types) |
| `limit`   | number | No       | Max results (default 100)                         |
| `offset`  | number | No       | Pagination offset                                 |
**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


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


Response:


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


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


Response:


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


### Example: Look Up Interests (Meta Ads)


```bash
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:


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


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


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


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


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


```bash
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`:


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


---