Ads · CampaignKit API Docs

POST

/v1/ads

Stellt die Anzeige ein (wie im Werbeanzeigenmanager) und legt sie an. HIER gehört die Anzeigen-Copy hin (nicht ins Template): Primärer Text, Überschrift, Beschreibung, Call-to-Action, Ziel-Link, optionaler angezeigter Link sowie Ad-Name und -Status. Aus dem Entwurf (creative_id aus POST /v1/templates/render oder POST /v1/creatives) wird damit das finale, platzierungsoptimierte Creative (Bild oder Video) gebaut und die Anzeige erstellt. Ads durchlaufen das Meta-Review.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
ad_set_id	string (UUID)	erforderlich	Übergeordnetes Ad Set (aus POST /v1/adsets). `z. B. a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77`
creative_id	string (UUID)	erforderlich	Creative-Entwurf aus POST /v1/templates/render (Vorlage) ODER POST /v1/creatives (eigenes Bild/Video). Aus dem Entwurf wird hier mit der Copy das finale Creative gebaut. Ist es bereits finalisiert, werden die Copy-Felder ignoriert. `z. B. 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d`
link	string (URL)	optional	Echte Ziel-URL (Landingpage), auf die der Klick führt. PFLICHT, wenn creative_id ein Render-Entwurf ist. Nur die saubere URL angeben: UTM-/Tracking-Parameter (Kampagnen-, Ad-Set-, Ad-Name plus eindeutige IDs) hängt campaignKit automatisch an; KEINE eigenen Tracking-Parameter setzen. `z. B. https://acme-events.de/tickets`
display_link	string	optional	Optionaler angezeigter Link, den der Nutzer sieht, unabhängig von der echten Ziel-URL. Für lange/unleserliche Ziel-URLs eine kurze, vertrauenswürdige URL zeigen. Empfehlung für die KI: nur die Marken-Domain plus optional kurzer Pfad, ohne https:// und ohne Query-Parameter (z. B. „acme-events.de/tickets“). `z. B. acme-events.de/tickets`
call_to_action	enum	optional	Button-Text der Anzeige. Genau einer dieser Werte, Format API-Wert (angezeigter Button): SIGN_UP (Registrieren), SUBSCRIBE (Abonnieren), SEE_MORE (Mehr ansehen), DOWNLOAD (Herunterladen), APPLY_NOW (Jetzt bewerben), BOOK_NOW (Jetzt buchen), BUY_TICKETS (Tickets kaufen), CONTACT_US (Kontaktiere uns), GET_OFFER (Angebot beanspruchen), GET_QUOTE (Angebot einholen), GET_SHOWTIMES (Spielzeiten), WATCH_MORE (Details ansehen), LEARN_MORE (Mehr dazu), LISTEN_NOW (Jetzt anhören), ORDER_NOW (Jetzt bestellen). Default: LEARN_MORE (Mehr dazu). Für Event/Ticket: BUY_TICKETS. `z. B. BUY_TICKETS`
message	string	optional	In Meta „Primärer Text“: Dies ist der wichtigste Text deiner Anzeige. Er erscheint in den meisten Platzierungen (wie dem Facebook-Feed) direkt über oder unter deinem Bild oder Video. Er sollte die Hauptbotschaft vermitteln und Nutzer dazu bewegen, mehr erfahren zu wollen. Maximal 125 Zeichen. Idealerweise umfasst der Text nur 1 bis 3 Zeilen, damit er ohne „Mehr anzeigen“ vollständig lesbar ist. KEINEN Call-to-Action hier eintragen (dafür ist das CTA-Feld). Pro Anzeige genau eine Variante. `z. B. Triff Gründer und Macher beim Networking-Event in Berlin am 18. Juli ab 19 Uhr.`
headline	string	optional	In Meta „Überschrift“: Die Überschrift erscheint meist fett gedruckt neben deinem Call-to-Action-Button (z. B. „Jetzt buchen“). Sie dient dazu, das wichtigste Verkaufsargument oder den Nutzen deines Angebots kurz und prägnant hervorzuheben. Maximal 40 Zeichen. So bleibt sie auch auf kleineren Bildschirmen einzeilig und gut lesbar. KEINEN Call-to-Action hier eintragen. `z. B. Founders Night Berlin`
description	string	optional	In Meta „Beschreibung“: Dieses Feld wird oft unter der Überschrift angezeigt, ist aber nicht in allen Platzierungen sichtbar. Hier kannst du zusätzliche, nicht essenzielle Details hinzufügen, wie zum Beispiel Lieferinformationen oder ein kurzes Kunden-Testimonial. Maximal 25 Zeichen. Da dieser Text oft abgeschnitten wird, solltest du hier nur ergänzende Informationen platzieren. KEINEN Call-to-Action hier eintragen. `z. B. Fr. 18. Juli, 19 Uhr`
name	string	optional	Optionaler Anzeigenname. Ohne Angabe wird er automatisch nach Naming Convention vergeben. `z. B. Founders Night · Visual A`
status	enum	optional	PAUSED (Default, Entwurf) oder ACTIVE (direkt ausspielen nach Meta-Review). `z. B. PAUSED`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/ads`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      ad_set_id: "a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77",
      creative_id: 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d,
      link: "https://acme-events.de/tickets",
      display_link: "acme-events.de/tickets",
      call_to_action: "BUY_TICKETS",
      message: "Triff Gründer und Macher beim Networking-Event in Berlin am 18. Juli ab 19 Uhr.",
      headline: "Founders Night Berlin",
      description: "Fr. 18. Juli, 19 Uhr",
      name: "Founders Night · Visual A",
      status: "PAUSED",
    }),
});
const data = await res.json();

Response 200

{
  "data": { "id": "9b2e…", "meta_ad_id": "390218475610", "meta_creative_id": "120210394857", "name": "[CK] … · Ad #1", "status": "PAUSED" },
  "request_id": "…"
}

Aus einem Render-Entwurf (creative_id) wird hier das finale Creative gebaut (Multi-Ratio mit Placement-Regeln) und die Ad angelegt; `link` ist dann Pflicht. Das Anlegen ist nur unter einer aktiven Ziel-Kampagne möglich, sonst 409 conflict. Erfordert vollständiges Onboarding (Token verifiziert, Werbekonto, Page, Instagram-Konto, DSA/legal_name); fehlt etwas → 422 mit details.missing.

GET

/v1/ads

Listet Ads inklusive ihres (gecachten) effective_status. Für den frischen Live-Status einer einzelnen Ad siehe GET /v1/status/{ad_id}.

Query-Parameter

Name	Typ	Pflicht	Beschreibung
adset_id	string (UUID)	optional	Auf ein Ad Set filtern.
status	enum	optional	ACTIVE \| PAUSED \| ARCHIVED.
limit	integer	optional	Anzahl pro Seite (Default 25, max 100).
offset	integer	optional	Versatz für Pagination (Default 0).

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/ads`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "9b2e1d77-4a3c-4e90-b1f2-8c7d6e5f4a3b",
      "ad_set_id": "a51f…",
      "creative_id": "1f0c…",
      "name": "[CK] … · Ad #1",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "disapproval_reason": null,
      "meta_ad_id": "390218475610"
    }
  ],
  "request_id": "…"
}

PATCH

/v1/ads/{id}

Setzt den Status einer Ad (z. B. nach erfolgreichem Review aktivieren).

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Ad-ID (aus POST/GET).

Body-Parameter

Name	Typ	Pflicht	Beschreibung
status	enum	erforderlich	ACTIVE \| PAUSED.

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/ads/${id}`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "…",
    }),
});
const data = await res.json();

Response 200

{
  "data": { "id": "9b2e…", "status": "ACTIVE", "effective_status": "PENDING_REVIEW", "meta_ad_id": "390218475610" },
  "request_id": "…"
}

Jede Änderung (auch Aktivieren/Pausieren) erfordert eine aktive Ziel-Kampagne, sonst 409 conflict. Archivieren (DELETE) bleibt möglich.

DELETE

/v1/ads/{id}

Archiviert eine Ad (status=ARCHIVED) bei uns und bei Meta.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Ad-ID.

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/ads/${id}`, {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{ "data": { "id": "9b2e…", "status": "ARCHIVED" }, "request_id": "…" }

Archiviert statt hart zu löschen.