Developer Docs

Referenz

Audiences

Custom Audiences aus rohen CRM-Kontakten (serverseitig gehasht) und darauf basierende Lookalikes.

Verfügbar

GET

/v1/audiences

Listet die Audiences des Kunden (DB-Spiegel). Status/Größe stammen aus dem letzten Sync (last_synced_at); frischen Live-Status liefert GET /v1/audiences/{id}.

Query-Parameter

Name	Typ	Pflicht	Beschreibung
subtype	enum	optional	Filter: CUSTOM \| LOOKALIKE.
status	enum	optional	Filter: active \| deleted.
limit	integer	optional	Max. Treffer (Default 25, max 100).
offset	integer	optional	Offset für Pagination.

Request · Next.js

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

Response 200

{
  "data": [
    { "id": "9b2e…", "meta_audience_id": "238947561029", "subtype": "CUSTOM", "name": "Käufer 2026", "approximate_count": 4120, "ready": true, "last_synced_at": "2026-06-15T08:00:00Z" }
  ],
  "request_id": "…"
}

POST

/v1/audiences/custom

Erstellt eine Custom Audience aus rohen CRM-Kontakten. Wir normalisieren und hashen serverseitig (SHA-256, im Speicher) — rohe PII wird nicht gespeichert. Optionaler erster Batch direkt beim Anlegen; weitere über POST /v1/audiences/{id}/contacts.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
name	string	erforderlich	Name der Audience (intern und in Meta sichtbar). `z. B. Käufer 2026`
description	string	optional	Interne Beschreibung. `z. B. Alle Ticket-Käufer 2026`
customer_file_source	enum	optional	Herkunft der Daten (Default USER_PROVIDED_ONLY): USER_PROVIDED_ONLY \| PARTNER_PROVIDED_ONLY \| BOTH_USER_AND_PARTNER_PROVIDED. `z. B. USER_PROVIDED_ONLY`
contacts	object[]	optional	Rohe CRM-Kontakte im festen Schema (max. 10.000 pro Request). Serverseitig normalisiert und gehasht (SHA-256), nichts wird gespeichert. Felder je Kontakt (mindestens eines aus email/phone/external_id): email, phone (inkl. Ländervorwahl), first_name, last_name, city, state, zip, country (ISO-2), year_of_birth (Zahl), gender (m\|f), external_id (nicht gehasht). `z. B. [{"email":"max@example.com","phone":"+4915112345678","first_name":"Max","zip":"50667","country":"DE"}]`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/audiences/custom`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      name: "Käufer 2026",
      description: "Alle Ticket-Käufer 2026",
      customer_file_source: "USER_PROVIDED_ONLY",
      contacts: [{"email":"max@example.com","phone":"+4915112345678","first_name":"Max","zip":"50667","country":"DE"}],
    }),
});
const data = await res.json();

Response 200

{ "data": { "id": "9b2e…", "meta_audience_id": "238947561029", "subtype": "CUSTOM", "contacts_received": 1 }, "request_id": "…" }

DSGVO: nur mit Einwilligung verarbeiten. Pro Request max. 10.000 Kontakte; größere Listen paginieren. Custom Audiences setzen voraus, dass (a) die Custom-Audience-Nutzungsbedingungen im Werbekonto akzeptiert sind UND (b) das Werbekonto dafür freigeschaltet ist. Sehr neue Werbekonten oder Konten ohne ausgelieferte Anzeigen können noch geblockt sein. In beiden Fällen liefert Meta denselben Fehler; die Antwort ist 403 mit details.reason='custom_audience_unavailable'. Das ist KEIN API-Konfigurationsfehler. Abhilfe: Nutzungsbedingungen akzeptieren und/oder zuerst eine Anzeige schalten und das Konto reifen lassen, dann erneut versuchen.

POST

/v1/audiences/lookalike

Erzeugt eine Lookalike-Audience aus einer eigenen Custom Audience für ein Land mit wählbarem Ähnlichkeitsgrad (empfohlen 1–10 %). Die Quelle sollte ≥ 100 Treffer haben.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
name	string	erforderlich	Name der Lookalike-Audience. `z. B. LAL Käufer 2026 DE 3%`
source_audience_id	string (UUID)	erforderlich	Quell-Custom-Audience (interne UUID aus POST /v1/audiences/custom). `z. B. 9b2e1f7c-…`
country	string	erforderlich	Zielland als ISO-2 (z. B. DE). `z. B. DE`
ratio	number (0.01–0.20)	erforderlich	Ähnlichkeitsgrad (1–20 %, empfohlen 1–10 %). `z. B. 0.03`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/audiences/lookalike`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      name: "LAL Käufer 2026 DE 3%",
      source_audience_id: 9b2e1f7c-…,
      country: "DE",
      ratio: 0.03,
    }),
});
const data = await res.json();

Response 200

{ "data": { "id": "7a1c…", "meta_audience_id": "238947561777", "subtype": "LOOKALIKE", "source_audience_id": "9b2e1f7c-…" }, "request_id": "…" }

Wie bei Custom Audiences kann Meta mit 403 (details.reason='custom_audience_unavailable') ablehnen, wenn das Werbekonto noch nicht für Custom Audiences freigeschaltet ist oder die Nutzungsbedingungen fehlen. Das ist KEIN API-Konfigurationsfehler.

GET

/v1/audiences/{id}

Liefert eine Audience inkl. frischem Status von Meta: operation_status, delivery_status, approximate_count und ready (true = fertig gebaut und in Ad-Sets nutzbar).

Path-Parameter

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

Request · Next.js

const id = "…";

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

Response 200

{
  "data": {
    "id": "9b2e…", "meta_audience_id": "238947561029", "subtype": "CUSTOM",
    "name": "Käufer 2026", "approximate_count": 4120,
    "operation_status_code": 200, "delivery_status_code": 200, "ready": true
  },
  "request_id": "…"
}

approximate_count kann direkt nach dem Upload noch 0 oder veraltet sein (die Population dauert).

PATCH

/v1/audiences/{id}

Ändert Name und/oder Beschreibung einer Audience.

Path-Parameter

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

Body-Parameter

Name	Typ	Pflicht	Beschreibung
name	string	optional	Neuer Name.
description	string	optional	Neue Beschreibung.

Request · Next.js

const id = "…";

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

    }),
});
const data = await res.json();

Response 200

{ "data": { "id": "9b2e…", "name": "Käufer 2026 (aktiv)", "subtype": "CUSTOM" }, "request_id": "…" }

DELETE

/v1/audiences/{id}

Löscht eine Audience bei Meta und markiert den Spiegel als deleted.

Path-Parameter

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

Request · Next.js

const id = "…";

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

Response 200

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

POST

/v1/audiences/{id}/contacts

Fügt einer Custom Audience weitere Kontakte hinzu (append). Rohe Kontakte im festen Schema, serverseitig gehasht. Max. 10.000 pro Request.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Audience-ID (nur CUSTOM).

Body-Parameter

Name	Typ	Pflicht	Beschreibung
contacts	object[]	erforderlich	Rohe CRM-Kontakte im festen Schema (max. 10.000 pro Request). Serverseitig normalisiert und gehasht (SHA-256), nichts wird gespeichert. Felder je Kontakt (mindestens eines aus email/phone/external_id): email, phone, first_name, last_name, city, state, zip, country (ISO-2), year_of_birth, gender (m\|f), external_id (nicht gehasht). `z. B. [{"email":"erika@example.com","country":"DE"}]`

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/audiences/${id}/contacts`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      contacts: [{"email":"erika@example.com","country":"DE"}],
    }),
});
const data = await res.json();

Response 200

{ "data": { "id": "9b2e…", "contacts_received": 1, "contacts_invalid": 0 }, "request_id": "…" }

DELETE

/v1/audiences/{id}/contacts

Entfernt Kontakte aus einer Custom Audience (DSGVO-Opt-out, Löschbegehren). Gleiches Kontakt-Schema wie beim Hinzufügen.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Audience-ID (nur CUSTOM).

Body-Parameter

Name	Typ	Pflicht	Beschreibung
contacts	object[]	erforderlich	Rohe CRM-Kontakte (festes Schema) zum Entfernen. Identifikation über dieselben gehashten Felder wie beim Hinzufügen. `z. B. [{"email":"erika@example.com"}]`

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/audiences/${id}/contacts`, {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contacts: [{"email":"erika@example.com"}],
    }),
});
const data = await res.json();

Response 200

{ "data": { "id": "9b2e…", "contacts_removed": 1 }, "request_id": "…" }