# Ads API Connectors

> Planning, auditing, and debugging paid ads API connectors and data pipelines for Google Ads, Meta Marketing API, TikTok Ads, LinkedIn Ads, Microsoft Ads, Apple Ads, GA4, MMPs, and CRM/offline conversion uploads. Use when the user mentions API access, OAuth, developer token, MCC, account sync, ETL, connector, reporting pipeline, field mapping, pagination, rate limits, incremental sync, backfill, or automated ads dashboards.

- Skill: `elinking-111/ads-api-connectors` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add elinking-111/ads-api-connectors`
- Raw SKILL.md: https://api.skillmd.com/api/skills/elinking-111/ads-api-connectors/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: elinking-111 (https://skillmd.com/u/elinking-111)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/elinking-111/ads-api-connectors

---


# Ads API Connectors

Design reliable read-first ads data pipelines. Treat write operations such as pausing campaigns, changing bids, uploading audiences, or editing budgets as high-risk and require explicit user confirmation.

## Workflow

1. Define connector purpose:
   - Reporting only.
   - Monitoring and anomaly detection.
   - Offline conversion upload.
   - Audience sync.
   - Controlled account actions.
2. Resolve account model:
   - Google MCC/customer ids, Meta business/ad account ids, TikTok advertiser ids, LinkedIn ad accounts, Microsoft manager accounts, Apple Ads orgs.
3. Confirm auth:
   - OAuth app, scopes, refresh token, developer token, app review, system user, token expiration, least-privilege access.
4. Design schema:
   - Stable ids, names, status, date, currency, spend, impressions, clicks, conversions, values, campaign/ad group/ad/keyword/creative dimensions.
   - Creative-level fields when available: creative/ad id, asset id, asset name, format, aspect ratio, duration, thumbnail/video URL, landing URL, copy text, headline, CTA, hook, angle, offer, product/use case, creator, proof type, funnel stage, launch date, age, and fatigue status.
5. Build sync plan:
   - Incremental daily sync, rolling backfill for conversion lag, idempotent upserts, retry and rate-limit handling.
6. Validate:
   - Reconcile API totals to platform UI for the same date range, timezone, attribution settings, and currency.
7. Document failure modes:
   - Auth expiration, partial pages, incompatible fields, delayed conversions, removed entities, renamed entities, sampling, privacy thresholding.

## Platform Notes

- Google Ads: use GAQL compatibility carefully; cost is micros; MCC login customer id often matters.
- Meta: account timezone and attribution settings can change apparent results; CAPI diagnostics are separate from Ads Insights.
- TikTok: advertiser id, reporting dimensions, Events API status, and Spark Ads permissions need separate checks.
- LinkedIn: limited reporting granularity and long B2B lag; align with CRM stages when possible.
- Microsoft: imported Google structures need validation; UET and Microsoft-specific placements matter.
- Apple Ads: org/campaign ids, CPP assignment, MMP post-install events, and AdAttributionKit/SKAN limitations matter.

## Creative-Level Data Model

When the user wants creative analytics, reporting, fatigue monitoring, or a
creative board, design the pipeline at creative/ad grain instead of only
campaign/ad group grain.

### Canonical Tables

| Table | Grain | Purpose |
|-------|-------|---------|
| `ad_daily` | platform + account + ad/creative + date | Spend, delivery, clicks, conversions, value, CPA/ROAS over time |
| `creative_asset` | platform + asset/creative id | Stable metadata, format, dimensions, duration, URLs, text, launch date |
| `creative_taxonomy` | asset/creative id + taxonomy version | Hook, angle, offer, CTA, proof type, product/use case, funnel stage |
| `creative_cluster` | cluster id + taxonomy signature | Groups similar assets by concept, not just file or text similarity |
| `creative_alert` | asset/cluster + date + alert type | Fatigue, winner, loser, inconclusive, policy risk, tracking caveat |

### Canonical Creative Fields

| Field | Notes |
|-------|-------|
| `creative_id` | Platform ad or creative id; stable if possible |
| `asset_id` | Image/video/document/product asset id when distinct from ad id |
| `creative_cluster_id` | Concept cluster for comparing variants across platforms |
| `format` | static, video, carousel, collection, document, PMax asset, CPP, etc. |
| `hook` | First-frame / headline / opening promise; inferred fields must be marked |
| `angle` | price, speed, trust, novelty, ROI, risk reduction, ease, quality, etc. |
| `offer` | trial, demo, discount, consultation, bundle, app install, lead magnet |
| `cta` | normalized CTA text |
| `proof_type` | review, case study, rating, benchmark, credential, demo, guarantee |
| `funnel_stage` | prospecting, retargeting, brand, competitor, retention, upsell |
| `launch_date` / `creative_age_days` | Needed for fatigue and refresh cadence |
| `thumbstop_rate` / `hold_rate` / `watch_time` | Platform-specific video metrics; null when unavailable |

### Validation Rules

- Reconcile creative totals to campaign totals for the same date range, timezone, and attribution window.
- Preserve platform ids even when names change.
- Store taxonomy version so AI-generated tags can be re-run without corrupting historical reports.
- Mark AI-inferred fields as inferred; do not mix them with user-approved manual tags.
- Avoid cross-platform creative ranking unless attribution windows and conversion definitions are comparable.
- Track missing thumbnails/videos separately from missing metrics.

## Output

Provide:

```markdown
## Connector Plan
| Platform | Auth Needed | Accounts | Data Grain | Sync Cadence | Risks |

## Field Map
| Canonical Field | Platform Field | Notes |

## Creative-Level Schema
| Canonical Field | Google | Meta | TikTok | LinkedIn | Microsoft | Apple | Notes |

## Validation Plan
...

## Runbook
...
```