# Ads

> One ads API over Meta, Google, LinkedIn, TikTok, Pinterest, X, Reddit and ChatGPT ads, with campaigns, boosts, audiences, insights, lead gen, pixels and conversions.

The Ads API is one platform-neutral model over **Meta (Facebook and Instagram), Google Ads, LinkedIn, TikTok, Pinterest, X, Reddit and OpenAI (ChatGPT) ads**. It has two reference groups:

| Reference | MCP toolset | Covers |
|---|---|---|
| [Ads](/docs/api-reference/ads/) | `ads` | Connections, campaigns, ad sets, ads, boosts, creatives, targeting, audiences, insights, Google Ads specifics |
| [Ads: accounts & measurement](/docs/api-reference/ads-accounts-measurement/) | `ads_measurement` | Ad accounts, users and finance, labels, tracking tags (pixels), lead forms and leads, product catalogs, conversions |

Every operation needs the `ads` feature (Business and Enterprise). Money is a decimal number in the ad account's currency (`50` = 50.00 EUR), never micros or cents.

## 1. Connect an ads account

`GET /v1/connect/{platform}/ads` (for example `meta_ads`, `google_ads`, `tiktok_ads`) returns the network's authorization URL, or connects immediately when an existing posting account's token can be reused. ChatGPT ads connect with an API key (`POST /v1/connect/openai-ads/credentials`).

A connection (`adc_…`) discovers its **ad accounts** (`ada_…`). Socialit syncs them every 30 minutes and backfills 90 days on connect (`ad_account.initial_sync_completed`). Synced reads answer `202` with `backfill_pending: true` until the first backfill finishes.

Live operations select the ad account with `ad_account_id`, or `connection_id` plus `platform_ad_account_id` (such as `act_123`).

## 2. Read campaigns and performance

| Endpoint | Returns |
|---|---|
| `GET /v1/ads/campaigns`, `/v1/ads/ad-sets`, `/v1/ads` | Synced objects with rolled-up metrics (`live=true` reads through) |
| `GET /v1/ads/tree` | Campaign → ad set → ad hierarchy |
| `GET /v1/ads/timeline` | Daily metrics per ad account |
| `GET /v1/ads/campaigns/{id}/analytics`, `/v1/ads/{id}/analytics` | Summary, daily series and breakdowns |
| `GET /v1/ads/insights`, `POST /v1/ads/insights/reports` | Flexible live insights and async reports |

## 3. Create ads

`POST /v1/ads` builds the whole tree (campaign → ad set → creative → ad) in one call, or attaches to an existing campaign or ad set. Objectives are portable (`traffic`, `engagement`, `awareness`, `video_views`, `lead_generation`, `conversions`, …) and mapped to each network.

```bash
curl -X POST https://api.socialit.com/v1/ads/boost \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: boost-launch-post" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_5Rt8Yp1Xn3Vb8Kd5SzHc2Lm9Qw4",
    "post_id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd",
    "name": "Boost: Focus mode launch",
    "goal": "engagement",
    "budget": { "type": "daily", "amount": 20 },
    "end_time": "2026-10-27T23:59:00Z"
  }'
```

- `POST /v1/ads/boost` promotes an organic post and keeps its engagement.
- `POST /v1/ads/messaging` creates click-to-message ads (Messenger, Instagram Direct); `POST /v1/ads/call` creates click-to-call ads.
- Pass `validate_only: true` (Meta, Google, OpenAI) to dry-run a create or update.
- Pause or resume with `…/status`, bulk with `POST /v1/ads/campaigns/bulk-status`; duplicate campaigns, ad sets and ads where the network allows.
- Creatives, images and videos have their own libraries (`/v1/ads/creatives`, `/v1/ads/images`, `/v1/ads/videos`); `POST /v1/ads/preview` renders previews before you spend.

Not every network supports every operation. Unsupported calls answer `409 capability_not_supported` with `platform` and `capability`; missing permissions answer `409 missing_scopes` with a `reconnect_url`.

## Targeting and audiences

Search any targeting dimension (`GET /v1/ads/targeting/search`), browse the category tree, and estimate reach (`POST /v1/ads/targeting/reach-estimate`). Custom audiences live at `/v1/ads/audiences`; `POST /v1/ads/audiences/{id}/users` adds people (plain emails and phones are SHA-256 hashed server-side).

## Google Ads specifics

Keywords and negative keywords, Keyword Planner ideas and historical metrics, recommendations (apply or dismiss), portfolio bid strategies, shared budgets, campaign assets (sitelinks, callouts, snippets), Performance Max asset groups, search terms and Local Services leads.

## Measurement

- **Tracking tags** (pixels): create, share and diagnose them per ad account.
- **Lead gen:** lead forms (`/v1/ads/lead-forms`) and stored leads (`/v1/ads/leads`). Every new lead fires `lead.received`, from Meta webhooks, live reads or LinkedIn polling.
- **Conversions:** send server-side events to the networks' Conversions APIs, manage conversion actions and check Event Match Quality.
- **Catalogs:** Meta product catalogs with their products, feeds and product sets (`/v1/ads/catalogs`).

## Webhooks

`ad.created`, `ad.updated`, `ad.status_changed`, `ad_campaign.*`, `ad_audience.*`, `ad_insights_report.completed`, `ad_connection.*`, `ad_account.*`, `lead.received` and `tracking_tag.*`. See [Ads events](/docs/api-reference/webhook-events/#events-ads).

---

Source: https://socialit.com/docs/ads/
