---
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://docs.unified.to/guides/creating_ads_using_the_unified_ads_api"
---

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


```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" }
      ]
    }
  }
}
```


---