Klantly Developers

API-referentie

Meta co-pilot

De stand van de Meta co-pilot op het advertentieaccount van het bedrijf, zijn meldingen (verloren reacties, afkeuringen, bestedingsschokken) en de noodstop. Het mandaat instellen kan alleen in het scherm.

Endpoints

Stand van de co-pilot ophalen

GET /api/v1/meta-copilot

De stand (uit, schaduw, co-pilot of autopilot), het profiel, het doel, het maandbudget en de tellers van open meldingen en wachtende voorstellen. 404 als het bedrijf geen Meta-advertentieaccount heeft.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot",
    "ad_account_id": "act_123456789",
    "ad_account_name": "Veranda BV",
    "currency": "EUR",
    "mode": "shadow",
    "profile": "standard",
    "goal_metric": "cost_per_quote",
    "goal_value": "45.00",
    "monthly_budget": "1500.00",
    "autonomous_classes": [],
    "open_alerts": 1,
    "pending_proposals": 0,
    "enabled_at": null,
    "tier": "autopilot",
    "ad_budget_ceiling": "7500.00",
    "on_expiry": "lapse",
    "stopped_at": null,
    "connection_active": true,
    "running": {
      "state": "running",
      "since": null,
      "kind": "operational"
    }
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Mandaat van de co-pilot bijwerken

PATCH /api/v1/meta-copilot/mandate

Zet profiel, doel, maandbudget, dagbudgetplafond, stiltedagen, de grondslag voor klantgegevens en of een onbeslist voorstel na de deadline alsnog wordt doorgevoerd. Wordt het mandaat RUIMER (meer autonome klassen, hoger of weggehaald dagplafond, minder stiltedagen, klantgegevens toestaan, verlopen voorstellen doorvoeren), dan is confirm_widening: true verplicht; zonder die bevestiging volgt 422 validation_failed met de uitleg. Verkleinen hoeft geen bevestiging. Het maandbudget kan niet boven het advertentieplafond van de tier (ad_budget_ceiling). Elke verruiming komt als melding in de tijdlijn.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Body (JSON)

VeldTypeOmschrijving
profile verplicht string Het mandaatprofiel: careful, standard of broad. een van: careful, standard, broad
goal_metric optioneel string Waar de co-pilot op stuurt. kan leeg zijn (null) · een van: cost_per_quote, cost_per_lead, cost_per_conversion, roas
goal_value optioneel number De doelwaarde, als tekst met twee decimalen. kan leeg zijn (null) · van 0 tot 1000000
monthly_budget optioneel number De maandafspraak voor advertentiebudget. kan leeg zijn (null) · van 0 tot 10000000
max_daily_budget_euros optioneel number Het dagbudgetplafond per campagne in euro; leeg = geen eigen plafond. kan leeg zijn (null) · van 1 tot 1000000
quiet_days optioneel array De stiltedagen (monday … sunday): dan wijzigt de co-pilot niets zelf en gaat alles ter goedkeuring.
crm_audience_allowed optioneel boolean Of gehashte e-mailadressen en telefoonnummers van klanten naar Meta mogen voor doelgroepen. Weggelaten = de opgeslagen keuze blijft staan.
on_expiry optioneel string Wat er met een voorstel gebeurt dat niet op tijd is beoordeeld: lapse (vervalt, de standaard) of apply (wordt na de deadline alsnog doorgevoerd, binnen alle vaste grenzen). een van: lapse, apply
confirm_widening optioneel boolean true om een verruiming van het mandaat bewust te bevestigen. Verplicht zodra de invoer het mandaat ruimer maakt dan het nu is.
notes optioneel string Een aantekening voor de co-pilot in gewone taal, bijvoorbeeld "nooit op zondag adverteren". kan leeg zijn (null) · maximaal 2000 tekens

Voorbeeldverzoek

cURL
curl -X PATCH "https://app.klantly.com/api/v1/meta-copilot/mandate" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "profile": "standard",
  "goal_metric": "cost_per_quote",
  "goal_value": 45,
  "monthly_budget": 1500,
  "quiet_days": [
    "sunday"
  ],
  "on_expiry": "lapse"
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PATCH', 'meta-copilot/mandate', [
    'json' => [
        'profile' => 'standard',
        'goal_metric' => 'cost_per_quote',
        'goal_value' => 45,
        'monthly_budget' => 1500,
        'quiet_days' => [
            0 => 'sunday',
        ],
        'on_expiry' => 'lapse',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/mandate', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "profile": "standard",
  "goal_metric": "cost_per_quote",
  "goal_value": 45,
  "monthly_budget": 1500,
  "quiet_days": [
    "sunday"
  ],
  "on_expiry": "lapse"
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.patch(
    "https://app.klantly.com/api/v1/meta-copilot/mandate",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "profile": "standard",
        "goal_metric": "cost_per_quote",
        "goal_value": 45,
        "monthly_budget": 1500,
        "quiet_days": [
            "sunday"
        ],
        "on_expiry": "lapse"
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot",
    "ad_account_id": "act_123456789",
    "ad_account_name": "Veranda BV",
    "currency": "EUR",
    "mode": "shadow",
    "profile": "standard",
    "goal_metric": "cost_per_quote",
    "goal_value": "45.00",
    "monthly_budget": "1500.00",
    "autonomous_classes": [],
    "open_alerts": 1,
    "pending_proposals": 0,
    "enabled_at": null,
    "tier": "autopilot",
    "ad_budget_ceiling": "7500.00",
    "on_expiry": "lapse",
    "stopped_at": null,
    "connection_active": true,
    "running": {
      "state": "running",
      "since": null,
      "kind": "operational"
    }
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Meldingen van de co-pilot opvragen

GET /api/v1/meta-copilot/alerts

De meldingen van de wachters en de engagement-bewaking, nieuwste eerst. Filter op status of urgentie. Titel en toelichting staan in de taal van Accept-Language.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.
filter[status] string Alleen meldingen met deze status: open of resolved (afgehandeld). een van: open, resolved
filter[severity] string Alleen meldingen met deze urgentie: info, warning of critical. een van: info, warning, critical

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/alerts?filter[status]=open" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/alerts', [
    'query' => [
        'filter[status]' => 'open',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/alerts?filter[status]=open', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/alerts",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "open"
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_alert",
      "id": "4821",
      "kind": "engagement_post_replaced",
      "severity": "critical",
      "status": "open",
      "title": "Advertentie \"Veranda zomer\" hangt aan een andere post: reacties en likes lopen niet meer mee",
      "detail": "De post waarop 143 reacties, 27 opmerkingen en 9 keer delen stonden, wordt niet meer geadverteerd.",
      "cause": "external",
      "target_id": "120210000000000001",
      "occurrences": 1,
      "first_seen_at": null,
      "last_seen_at": null,
      "resolved_at": null,
      "created_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Noodstop uitvoeren

POST /api/v1/meta-copilot/stop

Zet de co-pilot uit: open voorstellen en open kansen worden ingetrokken en regels die hij bij Meta installeerde gaan uit. De campagnes lopen door zoals ze staan. 409 conflict als de co-pilot al uit staat.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/stop" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/stop', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/stop', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/stop",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot",
    "ad_account_id": "act_123456789",
    "ad_account_name": "Veranda BV",
    "currency": "EUR",
    "mode": "shadow",
    "profile": "standard",
    "goal_metric": "cost_per_quote",
    "goal_value": "45.00",
    "monthly_budget": "1500.00",
    "autonomous_classes": [],
    "open_alerts": 1,
    "pending_proposals": 0,
    "enabled_at": null,
    "tier": "autopilot",
    "ad_budget_ceiling": "7500.00",
    "on_expiry": "lapse",
    "stopped_at": null,
    "connection_active": true,
    "running": {
      "state": "running",
      "since": null,
      "kind": "operational"
    }
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Kansen van de co-pilot opvragen

GET /api/v1/meta-copilot/opportunities

Wat de kansenmotor en de co-pilot zelf hebben gevonden: verspilde besteding, versleten advertenties, verzadigde doelgroepen, budgetconcentratie, plaatsingen die niets opleveren, offertes die nooit winnen, een funnel die wegvalt, een CPL boven het Klantly-gemiddelde. Nieuwste eerst; standaard alle statussen. Titel en toelichting in de taal van Accept-Language.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.
filter[status] string Alleen kansen met deze status: open, accepted, done, dismissed of expired. een van: open, accepted, done, dismissed, expired

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/opportunities?filter[status]=open" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/opportunities', [
    'query' => [
        'filter[status]' => 'open',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/opportunities?filter[status]=open', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/opportunities",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "open"
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_opportunity",
      "id": "318",
      "source": "signal",
      "kind": "wasted_spend",
      "status": "open",
      "title": "\"Retargeting winter\" gaf € 184,20 uit zonder één conversie",
      "body": "In de laatste 30 dagen is er € 184,20 besteed en zijn er 212 klikken geweest, maar geen enkele conversie.",
      "impact_cents": 18420,
      "confidence": "high",
      "reversible": true,
      "actionable": true,
      "reuse_post": null,
      "image_id": null,
      "target_level": "adset",
      "target_id": "120210000000000001",
      "target_name": "Retargeting winter",
      "dismissed_reason": null,
      "action_id": null,
      "variant": {
        "reference_ad_id": "120210000000000009",
        "headline": "Veranda op maat, binnen 4 weken geplaatst",
        "primary_text": "Langer buiten zitten zonder gedoe? Onze aluminium veranda wordt op maat gemaakt en binnen vier weken geplaatst. Vraag vandaag een vrijblijvende offerte aan.",
        "description": "Op maat gemaakt",
        "cta_type": "GET_QUOTE"
      },
      "blueprint": {
        "branch": "veranda",
        "city": "Nijmegen",
        "radius_km": 40,
        "age_min": 30,
        "age_max": 65,
        "daily_budget_cents": 1500,
        "has_pixel": true,
        "landing_url": "https://configurator.klantly.com/offerte-aanvragen/01k7x?utm_source=facebook",
        "image_id": "12",
        "headline": "Veranda op maat van Veranda Boys",
        "primary_text": "Langer buiten zitten, ook in het najaar? Veranda Boys maakt veranda's op maat. Vraag vrijblijvend een offerte aan.",
        "description": "Vrijblijvende offerte",
        "cta_type": "GET_QUOTE",
        "peer_accounts": 7,
        "peer_median_cpl": "31.20"
      },
      "decided_at": null,
      "expires_at": null,
      "created_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een kans laten oppakken

POST /api/v1/meta-copilot/opportunities/{opportunity}/accept

"Laat de co-pilot dit doen." Draagt de kans een actie en staat de co-pilot niet in de schaduwstand, dan wordt die actie direct doorgevoerd binnen het mandaat; anders komt hij als volgende stap in de strategie. 409 conflict als de kans niet meer open staat.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
opportunity verplicht string De id van de kans.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/accept" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/accept', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/accept', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/accept",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_opportunity",
    "id": "318",
    "source": "signal",
    "kind": "wasted_spend",
    "status": "open",
    "title": "\"Retargeting winter\" gaf € 184,20 uit zonder één conversie",
    "body": "In de laatste 30 dagen is er € 184,20 besteed en zijn er 212 klikken geweest, maar geen enkele conversie.",
    "impact_cents": 18420,
    "confidence": "high",
    "reversible": true,
    "actionable": true,
    "reuse_post": null,
    "image_id": null,
    "target_level": "adset",
    "target_id": "120210000000000001",
    "target_name": "Retargeting winter",
    "dismissed_reason": null,
    "action_id": null,
    "variant": {
      "reference_ad_id": "120210000000000009",
      "headline": "Veranda op maat, binnen 4 weken geplaatst",
      "primary_text": "Langer buiten zitten zonder gedoe? Onze aluminium veranda wordt op maat gemaakt en binnen vier weken geplaatst. Vraag vandaag een vrijblijvende offerte aan.",
      "description": "Op maat gemaakt",
      "cta_type": "GET_QUOTE"
    },
    "blueprint": {
      "branch": "veranda",
      "city": "Nijmegen",
      "radius_km": 40,
      "age_min": 30,
      "age_max": 65,
      "daily_budget_cents": 1500,
      "has_pixel": true,
      "landing_url": "https://configurator.klantly.com/offerte-aanvragen/01k7x?utm_source=facebook",
      "image_id": "12",
      "headline": "Veranda op maat van Veranda Boys",
      "primary_text": "Langer buiten zitten, ook in het najaar? Veranda Boys maakt veranda's op maat. Vraag vrijblijvend een offerte aan.",
      "description": "Vrijblijvende offerte",
      "cta_type": "GET_QUOTE",
      "peer_accounts": 7,
      "peer_median_cpl": "31.20"
    },
    "decided_at": null,
    "expires_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een kans afwijzen

POST /api/v1/meta-copilot/opportunities/{opportunity}/dismiss

Met self=true noteer je dat je het zelf oppakt; anders is het "niet relevant". De reden gaat als leerpunt naar de co-pilot, en dezelfde kans komt dertig dagen niet terug. 409 conflict als de kans niet meer open staat.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
opportunity verplicht string De id van de kans.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/dismiss" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "reason": "Deze campagne stopt eind van de maand toch.",
  "self": false
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/dismiss', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'reason' => 'Deze campagne stopt eind van de maand toch.',
        'self' => false,
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/dismiss', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "reason": "Deze campagne stopt eind van de maand toch.",
  "self": false
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/opportunities/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/dismiss",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "reason": "Deze campagne stopt eind van de maand toch.",
        "self": False
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_opportunity",
    "id": "318",
    "source": "signal",
    "kind": "wasted_spend",
    "status": "open",
    "title": "\"Retargeting winter\" gaf € 184,20 uit zonder één conversie",
    "body": "In de laatste 30 dagen is er € 184,20 besteed en zijn er 212 klikken geweest, maar geen enkele conversie.",
    "impact_cents": 18420,
    "confidence": "high",
    "reversible": true,
    "actionable": true,
    "reuse_post": null,
    "image_id": null,
    "target_level": "adset",
    "target_id": "120210000000000001",
    "target_name": "Retargeting winter",
    "dismissed_reason": null,
    "action_id": null,
    "variant": {
      "reference_ad_id": "120210000000000009",
      "headline": "Veranda op maat, binnen 4 weken geplaatst",
      "primary_text": "Langer buiten zitten zonder gedoe? Onze aluminium veranda wordt op maat gemaakt en binnen vier weken geplaatst. Vraag vandaag een vrijblijvende offerte aan.",
      "description": "Op maat gemaakt",
      "cta_type": "GET_QUOTE"
    },
    "blueprint": {
      "branch": "veranda",
      "city": "Nijmegen",
      "radius_km": 40,
      "age_min": 30,
      "age_max": 65,
      "daily_budget_cents": 1500,
      "has_pixel": true,
      "landing_url": "https://configurator.klantly.com/offerte-aanvragen/01k7x?utm_source=facebook",
      "image_id": "12",
      "headline": "Veranda op maat van Veranda Boys",
      "primary_text": "Langer buiten zitten, ook in het najaar? Veranda Boys maakt veranda's op maat. Vraag vrijblijvend een offerte aan.",
      "description": "Vrijblijvende offerte",
      "cta_type": "GET_QUOTE",
      "peer_accounts": 7,
      "peer_median_cpl": "31.20"
    },
    "decided_at": null,
    "expires_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Voorstellen van de co-pilot opvragen

GET /api/v1/meta-copilot/approvals

De voorstellen die op een besluit wachten (standaard filter[status]=proposed), of met een filter de voornemens uit de schaduwstand, wat is doorgevoerd, afgewezen, verlopen of mislukt. Zonder payload en zonder namen van medewerkers.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.
filter[status] string Alleen voorstellen met deze status: proposed, simulated, applied, dismissed, expired of failed. Zonder filter: proposed. een van: proposed, simulated, applied, dismissed, expired, failed

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/approvals?filter[status]=proposed" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/approvals', [
    'query' => [
        'filter[status]' => 'proposed',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/approvals?filter[status]=proposed', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/approvals",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "proposed"
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_approval",
      "id": "2077",
      "status": "proposed",
      "action_type": "adjust_budget",
      "target_level": "adset",
      "target_id": "120210000000000001",
      "target_name": "Retargeting winter",
      "title": "Budget van \"Retargeting winter\" verlagen van € 40 naar € 30 per dag",
      "rationale": "De kosten per offerte liggen hier 60% boven het accountgemiddelde.",
      "risk": "low",
      "impact_estimate_cents": 30000,
      "change": {
        "kind": "budget",
        "level": "adset",
        "manual": false,
        "from_cents": 4000,
        "to_cents": 3000,
        "placements": [
          "audience_network"
        ],
        "devices": [
          "mobile"
        ],
        "min": 30,
        "max": 65,
        "genders": [
          "female"
        ],
        "audience_name": null,
        "headline": null,
        "days": 14,
        "template": null,
        "purpose": null,
        "percent": 1,
        "country": "NL",
        "strategy": "cost_cap",
        "cap_cents": null,
        "daily_budget_cents": null
      },
      "simulated": false,
      "reuse_post": null,
      "image_id": null,
      "approval_deadline_at": null,
      "applied_at": null,
      "outcome": null,
      "error": null,
      "created_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een voorstel goedkeuren

POST /api/v1/meta-copilot/approvals/{approval}/approve

Voert het voorstel door bij Meta, binnen het mandaat van het account. Alleen voor een voorstel met status proposed; anders 409 conflict. In de schaduwstand weigert de uitvoerder. Bij een advertentievariant met dezelfde tekst als het origineel kies je met reuse_post of de bestaande post wordt hergebruikt (standaard true).

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
approval verplicht string De id van het voorstel.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/approve" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/approve', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/approve', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/approve",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_approval",
    "id": "2077",
    "status": "proposed",
    "action_type": "adjust_budget",
    "target_level": "adset",
    "target_id": "120210000000000001",
    "target_name": "Retargeting winter",
    "title": "Budget van \"Retargeting winter\" verlagen van € 40 naar € 30 per dag",
    "rationale": "De kosten per offerte liggen hier 60% boven het accountgemiddelde.",
    "risk": "low",
    "impact_estimate_cents": 30000,
    "change": {
      "kind": "budget",
      "level": "adset",
      "manual": false,
      "from_cents": 4000,
      "to_cents": 3000,
      "placements": [
        "audience_network"
      ],
      "devices": [
        "mobile"
      ],
      "min": 30,
      "max": 65,
      "genders": [
        "female"
      ],
      "audience_name": null,
      "headline": null,
      "days": 14,
      "template": null,
      "purpose": null,
      "percent": 1,
      "country": "NL",
      "strategy": "cost_cap",
      "cap_cents": null,
      "daily_budget_cents": null
    },
    "simulated": false,
    "reuse_post": null,
    "image_id": null,
    "approval_deadline_at": null,
    "applied_at": null,
    "outcome": null,
    "error": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een voorstel afwijzen

POST /api/v1/meta-copilot/approvals/{approval}/reject

Zet het voorstel (of een voornemen uit de schaduwstand) op dismissed. Er verandert niets bij Meta.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
approval verplicht string De id van het voorstel.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/reject" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/reject', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/reject', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/approvals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/reject",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_approval",
    "id": "2077",
    "status": "proposed",
    "action_type": "adjust_budget",
    "target_level": "adset",
    "target_id": "120210000000000001",
    "target_name": "Retargeting winter",
    "title": "Budget van \"Retargeting winter\" verlagen van € 40 naar € 30 per dag",
    "rationale": "De kosten per offerte liggen hier 60% boven het accountgemiddelde.",
    "risk": "low",
    "impact_estimate_cents": 30000,
    "change": {
      "kind": "budget",
      "level": "adset",
      "manual": false,
      "from_cents": 4000,
      "to_cents": 3000,
      "placements": [
        "audience_network"
      ],
      "devices": [
        "mobile"
      ],
      "min": 30,
      "max": 65,
      "genders": [
        "female"
      ],
      "audience_name": null,
      "headline": null,
      "days": 14,
      "template": null,
      "purpose": null,
      "percent": 1,
      "country": "NL",
      "strategy": "cost_cap",
      "cap_cents": null,
      "daily_budget_cents": null
    },
    "simulated": false,
    "reuse_post": null,
    "image_id": null,
    "approval_deadline_at": null,
    "applied_at": null,
    "outcome": null,
    "error": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

De tijdlijn opvragen

GET /api/v1/meta-copilot/timeline

Rondes, wijzigingen en voornemens, meldingen en standwissels in één lijst, nieuwste eerst. Geen cursor: hooguit 100 regels.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal regels, hoogstens 100 (standaard 50). van 1 tot 100 · standaard: 50

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/timeline" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/timeline');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/timeline', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/timeline",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_timeline_entry",
      "id": "action-2077",
      "type": "action",
      "at": null,
      "kind": "adjust_budget",
      "status": "applied",
      "title": "Budget van \"Retargeting winter\" verlaagd naar € 30 per dag",
      "rationale": "De kosten per offerte liggen hier 60% boven het accountgemiddelde.",
      "target_name": "Retargeting winter",
      "actor": "copilot",
      "cause": null,
      "severity": null,
      "simulated": false,
      "action_id": "2077",
      "alert_id": null
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Weekdigests opvragen

GET /api/v1/meta-copilot/digests

De weekoverzichten die de co-pilot op maandag opstelt: besteding, resultaten, wat hij deed en wat hij voorstelt. Als gegevens, niet als tekst.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/digests" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/digests');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/digests', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/digests",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_digest",
      "id": "56",
      "period_start": "2026-10-12",
      "period_end": "2026-10-18",
      "language": "nl",
      "spend": "412.80",
      "previous_spend": "398.10",
      "conversions": 9,
      "cost_per_conversion": "45.87",
      "copilot_runs": 7,
      "copilot_applied": 2,
      "copilot_intentions": 0,
      "outcomes": {
        "improved": 1,
        "neutral": 1,
        "worsened": 0
      },
      "waiting": {
        "proposals": 1,
        "alerts": 0,
        "opportunities": 3
      },
      "next_steps": [
        "Nieuwe variant naast \"Veranda zomer\" testen"
      ],
      "sent_at": null,
      "created_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Ochtendbriefings opvragen

GET /api/v1/meta-copilot/briefings

Eén briefing per dag over de dag ervoor: besteding, leads, offertes en gewonnen opdrachten uit Klantly tegen het gemiddelde van de week ervoor, met de soort van de dag en de mijlpalen van die ochtend. Kop en toelichting volgen Accept-Language.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/briefings" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/briefings');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/briefings', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/briefings",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_briefing",
      "id": "412",
      "date": "2026-10-22",
      "kind": "quotes",
      "headline": "Twee offerteaanvragen uit Meta gisteren.",
      "body": "Besteed € 38,20 (gemiddeld € 41,10 per dag), 3 leads (gemiddeld 2,4), 2 offertes, 0 gewonnen.",
      "spend": "38.20",
      "avg_spend": "41.10",
      "leads": 3,
      "avg_leads": 2.4,
      "clicks": 61,
      "quotes": 2,
      "won": 0,
      "won_value": "0.00",
      "cost_per_lead": "12.73",
      "mtd_spend": "812.40",
      "milestone_ids": [
        "18"
      ],
      "tip": {
        "key": "frequency_high",
        "category": "audience",
        "actor": "copilot",
        "title": "Je doelgroep ziet elke advertentie 3,4 keer",
        "body": "Boven de 3 vertoningen per persoon stijgen de kosten per lead.",
        "action": "Laat de co-pilot dit oppakken"
      },
      "pushed_at": null,
      "created_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

De omzetbrug opvragen

GET /api/v1/meta-copilot/revenue

Advertentiekosten → leads → offertes → gewonnen → omzet over de laatste `days` dagen (standaard 30), per campagne en per kalendermaand, op echte Klantly-omzet. Offertes tellen alleen mee als ze via de campagne-macro aan een campagne van dit account hangen.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
days integer Hoeveel dagen terug, 7 tot 365 (standaard 30). De maandreeks is altijd de laatste zes kalendermaanden. van 7 tot 365 · standaard: 30

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/revenue?days=30" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/revenue', [
    'query' => [
        'days' => '30',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/revenue?days=30', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/revenue",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "days": "30"
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_revenue",
    "since": "2026-09-24",
    "until": "2026-10-23",
    "uses_quotes": true,
    "spend": "1240.50",
    "clicks": 1830,
    "impressions": 92400,
    "leads": 74,
    "quotes": 31,
    "quotes_value": "142300.00",
    "won": 6,
    "won_value": "27850.00",
    "cost_per_lead": "16.76",
    "cost_per_quote": "40.02",
    "cost_per_won": "206.75",
    "roas": 22.45,
    "revenue_source": "quotes",
    "purchases": 0,
    "purchase_value": "0.00",
    "cost_per_purchase": null,
    "meta_roas": null,
    "copilot_impact": "412.00",
    "campaigns": [
      {
        "campaign_id": "120210000000001",
        "name": "Veranda voorjaar",
        "spend": "812.00",
        "leads": 51,
        "quotes": 22,
        "quotes_value": "98400.00",
        "won": 4,
        "won_value": "19200.00",
        "cost_per_lead": "15.92",
        "roas": 23.65,
        "purchases": 0,
        "purchase_value": "0.00",
        "meta_roas": null
      }
    ],
    "months": [
      {
        "month": "2026-10",
        "spend": "1240.50",
        "leads": 74,
        "quotes": 31,
        "quotes_value": "142300.00",
        "won": 6,
        "won_value": "27850.00",
        "cost_per_lead": "16.76",
        "roas": 22.45,
        "purchases": 0,
        "purchase_value": "0.00",
        "meta_roas": null
      }
    ]
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

De cijfers van de campagnes opvragen

GET /api/v1/meta-copilot/stats

Kosten, vertoningen, kliks en resultaten over de laatste `days` dagen (7, 14, 30 of 90; standaard 30): totalen, dezelfde periode ervoor, per dag en per campagne. Geschikt voor grafieken. De co-pilot werkt de cijfers elke ochtend en middag bij.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
days integer Hoeveel dagen terug: 7, 14, 30 of 90 (standaard 30). een van: 7, 14, 30, 90 · standaard: 30

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/stats?days=30" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/stats', [
    'query' => [
        'days' => '30',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/stats?days=30', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/stats",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "days": "30"
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_stats",
    "since": "2026-09-26",
    "until": "2026-10-25",
    "days": 30,
    "currency": "EUR",
    "result_kind": "leads",
    "latest_date": "2026-10-04",
    "synced_at": null,
    "totals": {
      "spend": "412.30",
      "impressions": 31840,
      "clicks": 612,
      "results": 23,
      "leads": 23,
      "purchases": 0,
      "purchase_value": "0.00",
      "ctr": 1.92,
      "cpc": "0.67",
      "cpm": "12.95",
      "cost_per_result": "17.93",
      "roas": null
    },
    "previous": {
      "spend": "412.30",
      "impressions": 31840,
      "clicks": 612,
      "results": 23,
      "leads": 23,
      "purchases": 0,
      "purchase_value": "0.00",
      "ctr": 1.92,
      "cpc": "0.67",
      "cpm": "12.95",
      "cost_per_result": "17.93",
      "roas": null
    },
    "daily": [
      {
        "date": "2026-10-25",
        "spend": "14.20",
        "impressions": 1080,
        "clicks": 21,
        "results": 1,
        "leads": 1,
        "purchases": 0,
        "purchase_value": "0.00",
        "ctr": 1.94,
        "cpc": "0.68",
        "cpm": "13.15",
        "cost_per_result": "14.20"
      }
    ],
    "campaigns": [
      {
        "campaign_id": "120210000000001",
        "name": "Veranda voorjaar",
        "status": "ACTIVE",
        "share": 64.2,
        "daily_spend": [
          "12.40",
          "14.10"
        ],
        "spend": "264.70",
        "impressions": 20410,
        "clicks": 402,
        "results": 16,
        "leads": 16,
        "purchases": 0,
        "purchase_value": "0.00",
        "ctr": 1.97,
        "cpc": "0.66",
        "cpm": "12.97",
        "cost_per_result": "16.54",
        "roas": null
      }
    ]
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Het team van de co-pilot opvragen

GET /api/v1/meta-copilot/crew

Wat elke agent van de co-pilot het laatst deed, wanneer hij volgens de planning weer aan de slag gaat, en de tellers van vandaag en deze week. Alles uit echte handelingen en de echte planning.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/crew" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/crew');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/crew', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/crew",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_crew",
    "state": "active",
    "mode": "copilot",
    "agents": [
      {
        "role": "optimizer",
        "status": "ready",
        "last_at": "2026-10-25T05:03:11Z",
        "last_kind": "run_operational",
        "last_facts": {
          "status": "completed",
          "tool_calls": 14,
          "proposals": 2
        },
        "next_at": "2026-10-28T06:00:00Z",
        "next_kind": "operational",
        "count_7d": 3,
        "week": [
          0,
          1,
          0,
          0,
          1,
          0,
          1
        ]
      }
    ],
    "today": {
      "checks": 14,
      "campaigns": 4,
      "opportunities": 1,
      "proposals": 2
    },
    "week": {
      "checks": 98,
      "rounds": 3,
      "proposals": 5,
      "applied": 2
    },
    "next": {
      "role": "guard",
      "at": "2026-10-26T05:45:00Z"
    },
    "feed": [
      {
        "role": "analyst",
        "kind": "stats_synced",
        "at": "2026-10-25T04:45:12Z",
        "facts": {
          "campaigns": 4,
          "days": 14,
          "rows": 56
        }
      }
    ]
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Wat de co-pilot opleverde opvragen

GET /api/v1/meta-copilot/value

Wat de co-pilot sinds het aanzetten deed en wat dat opleverde: doorgevoerde verbeteringen (zelf of na een akkoord), de meting een week later (beter, gelijk, slechter, nog aan het meten), de geschatte opbrengst, wat hij bewaakte, en kosten per resultaat in de dagen vóór en sinds het aanzetten. De schatting is de verwachting bij elk voorstel, geen meting; de vergelijking staat er pas vanaf zeven dagen en vijf resultaten aan beide kanten.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/value" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/value');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/value', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/value",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_value",
    "since": "2026-10-02T08:14:00Z",
    "days_on": 26,
    "mode": "autopilot",
    "currency": "EUR",
    "actions": {
      "applied": 9,
      "by_itself": 7,
      "approved": 2,
      "rolled_back": 0
    },
    "outcomes": {
      "improved": 5,
      "neutral": 1,
      "worsened": 1,
      "measuring": 2
    },
    "estimated_value": "640.00",
    "watch": {
      "checks_30d": 412,
      "alerts": 6,
      "alerts_resolved": 5
    },
    "comparison": {
      "available": true,
      "days": 26,
      "result_kind": "leads",
      "before": {
        "spend": "812.40",
        "results": 31,
        "cost_per_result": "26.21"
      },
      "after": {
        "spend": "790.10",
        "results": 42,
        "cost_per_result": "18.81"
      },
      "change_pct": -28.2
    },
    "recent": [
      {
        "id": 4182,
        "title": "Budget van Veranda voorjaar met 15% verhoogd",
        "action_type": "update_campaign_budget",
        "at": "2026-10-24T05:12:00Z",
        "by_itself": true,
        "outcome": "measuring",
        "rollback": false,
        "impact_estimate": "120.00"
      }
    ],
    "generated_at": "2026-10-28T09:30:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Mijlpalen opvragen

GET /api/v1/meta-copilot/milestones

Gevierde mijlpalen (de stil vastgelegde nulmeting van een bestaand account staat er niet in), nieuwste eerst: het aantal leads uit Meta, gewonnen opdrachten, de beste week en weken op rij zonder verspilling. Titel en toelichting volgen Accept-Language.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/milestones" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/milestones');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/milestones', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/milestones",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_milestone",
      "id": "18",
      "kind": "leads",
      "threshold": 100,
      "period": "",
      "value": "104.00",
      "title": "De 100e lead uit Meta",
      "detail": "Sinds het begin van de meting kwamen er 104 leads uit je Meta-advertenties.",
      "reached_on": "2026-10-22",
      "created_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Jij vs. vergelijkbare bedrijven

GET /api/v1/meta-copilot/benchmark

Kosten per lead, CTR, CPC en CPM van dit account over 30 dagen tegen het midden en het beste kwart van alle gevolgde accounts met volume, anoniem en pas vanaf vijf accounts. position = het aandeel accounts dat slechter scoort.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/benchmark" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/benchmark');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/benchmark', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/benchmark",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_benchmark",
    "available": true,
    "accounts": 12,
    "min_accounts": 5,
    "period_days": 30,
    "metrics": [
      {
        "metric": "cost_per_lead",
        "own": 14.2,
        "median": 19.8,
        "best_quartile": 11.5,
        "position": 71,
        "higher_is_better": false
      }
    ]
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

De seizoenskalender opvragen

GET /api/v1/meta-copilot/seasonality

Hoeveel offerteaanvragen er per kalendermaand binnenkomen bij vergelijkbare Klantly-bedrijven (de branche van de AI-agent, anders het hele platform), als factor tegen het jaargemiddelde over twee jaar. Anoniem en alleen boven de volumevloer; anders available=false.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/seasonality" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/seasonality');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/seasonality', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/seasonality",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_seasonality",
    "available": true,
    "scope": "branch",
    "label": "Veranda en overkappingen",
    "companies": 23,
    "quotes_per_month": 410,
    "months": [
      {
        "month": 3,
        "factor": 1.42
      }
    ],
    "current_month": 10,
    "current_factor": 0.84,
    "next_month": 11,
    "next_factor": 0.61,
    "peak_month": 3,
    "low_month": 12
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Op de tip van vandaag antwoorden

POST /api/v1/meta-copilot/tips/{tip}/respond

accept = de co-pilot pakt het op (de tip wordt een kans en een volgende stap in zijn strategie), self = je pakt het zelf op, dismiss = niet relevant. Dezelfde tip komt daarna negentig dagen niet terug. 404 bij een onbekende tipsleutel.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
tip verplicht string De sleutel van de tip, zoals hij in de briefing staat (bijvoorbeeld frequency_high).

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/tips/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/respond" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/tips/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/respond', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/tips/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/respond', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/tips/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/respond",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_tip_response",
    "tip": "frequency_high",
    "category": "audience",
    "actor": "copilot",
    "title": "Je doelgroep ziet elke advertentie 3,4 keer",
    "vars": {
      "spend": "€ 600.00"
    },
    "response": "accept",
    "opportunity_id": "321",
    "responded_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Gevolgde concurrenten opvragen

GET /api/v1/meta-copilot/competitors

De Facebookpagina's die het bedrijf volgt (hooguit vijf), elk met zijn advertenties uit de openbare Ad Library van Meta (hooguit 25, lopende en nieuwe eerst): kop, tekst, platforms, looptijd en bereik in de EU. De co-pilot leest de bibliotheek wekelijks; is_new blijft veertien dagen staan. Geen cursor.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/competitors" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/competitors');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/competitors', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/competitors",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_competitor",
      "id": "7",
      "page_id": "115115300320906",
      "page_name": "Veranda Boys",
      "library_url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&view_all_page_id=115115300320906",
      "ads_active": 6,
      "ads_total": 14,
      "last_scanned_at": null,
      "ads": [],
      "created_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een concurrent volgen

POST /api/v1/meta-copilot/competitors

Op het numerieke Facebookpagina-id (te vinden in de Ad Library of in het scherm via zoeken op naam). De nulmeting van zijn advertenties gebeurt meteen; wat er dan al loopt telt niet als nieuw. 409 conflict bij een pagina die al wordt gevolgd, boven het maximum van vijf, of zonder actieve Meta-koppeling.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/competitors" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/competitors', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/competitors', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/competitors",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 201

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_competitor",
    "id": "7",
    "page_id": "115115300320906",
    "page_name": "Veranda Boys",
    "library_url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&view_all_page_id=115115300320906",
    "ads_active": 6,
    "ads_total": 14,
    "last_scanned_at": null,
    "ads": [],
    "created_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een concurrent niet meer volgen

DELETE /api/v1/meta-copilot/competitors/{competitor}

Verwijdert de pagina en zijn bewaarde advertenties.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Padparameters

NaamTypeOmschrijving
competitor verplicht string De id van de gevolgde concurrent.

Voorbeeldverzoek

cURL
curl -X DELETE "https://app.klantly.com/api/v1/meta-copilot/competitors/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('DELETE', 'meta-copilot/competitors/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/competitors/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.delete(
    "https://app.klantly.com/api/v1/meta-copilot/competitors/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "note",
    "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92",
    "deleted": true
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een variant maken op een advertentie van een concurrent

POST /api/v1/meta-copilot/competitors/ads/{ad}/variant

De co-pilot schrijft een variant op de eigen beste advertentie met de INSTEEK van deze advertentie van de concurrent — niet zijn tekst: geen zin wordt overgenomen, het eigen beeld blijft en er komt geen belofte bij die het eigen origineel niet draagt. Het resultaat is een kans van de soort creative_advice met de variant klaar om goed te keuren (status 201). 409 conflict als de co-pilot uit staat, er geen eigen actieve advertentie met tekst is, dezelfde bronadvertentie de laatste zestig dagen al een variant kreeg, of er geen bruikbare variant uit kwam. Kost één modelaanroep.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
ad verplicht string De id van de advertentie van de concurrent (uit de lijst van gevolgde concurrenten).

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/competitors/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/variant" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/competitors/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/variant', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/competitors/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/variant', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/competitors/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/variant",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 201

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_opportunity",
    "id": "318",
    "source": "signal",
    "kind": "wasted_spend",
    "status": "open",
    "title": "\"Retargeting winter\" gaf € 184,20 uit zonder één conversie",
    "body": "In de laatste 30 dagen is er € 184,20 besteed en zijn er 212 klikken geweest, maar geen enkele conversie.",
    "impact_cents": 18420,
    "confidence": "high",
    "reversible": true,
    "actionable": true,
    "reuse_post": null,
    "image_id": null,
    "target_level": "adset",
    "target_id": "120210000000000001",
    "target_name": "Retargeting winter",
    "dismissed_reason": null,
    "action_id": null,
    "variant": {
      "reference_ad_id": "120210000000000009",
      "headline": "Veranda op maat, binnen 4 weken geplaatst",
      "primary_text": "Langer buiten zitten zonder gedoe? Onze aluminium veranda wordt op maat gemaakt en binnen vier weken geplaatst. Vraag vandaag een vrijblijvende offerte aan.",
      "description": "Op maat gemaakt",
      "cta_type": "GET_QUOTE"
    },
    "blueprint": {
      "branch": "veranda",
      "city": "Nijmegen",
      "radius_km": 40,
      "age_min": 30,
      "age_max": 65,
      "daily_budget_cents": 1500,
      "has_pixel": true,
      "landing_url": "https://configurator.klantly.com/offerte-aanvragen/01k7x?utm_source=facebook",
      "image_id": "12",
      "headline": "Veranda op maat van Veranda Boys",
      "primary_text": "Langer buiten zitten, ook in het najaar? Veranda Boys maakt veranda's op maat. Vraag vrijblijvend een offerte aan.",
      "description": "Vrijblijvende offerte",
      "cta_type": "GET_QUOTE",
      "peer_accounts": 7,
      "peer_median_cpl": "31.20"
    },
    "decided_at": null,
    "expires_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Voorbeeld van een advertentie

GET /api/v1/meta-copilot/ads/{ad}/preview

Het adres van het voorbeeld zoals Meta de advertentie toont (format: MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY of DESKTOP_FEED_STANDARD; standaard de feed op een telefoon). Zet het adres in een iframe. Alleen voor een advertentie van het eigen advertentieaccount (anders 404); kan Meta geen voorbeeld maken, dan 409. Het adres is enkele uren geldig.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Padparameters

NaamTypeOmschrijving
ad verplicht string De id van de advertentie van de concurrent (uit de lijst van gevolgde concurrenten).

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/preview" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/preview');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/preview', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/ads/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/preview",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_ad_preview",
    "ad_id": "120211234567890",
    "format": "MOBILE_FEED_STANDARD",
    "url": "https://www.facebook.com/ads/api/preview_iframe.php?d=AQ...&t=AQ..."
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Beelden in de bibliotheek opvragen

GET /api/v1/meta-copilot/images

De beelden en video's die het bedrijf heeft geüpload voor advertentievarianten, nieuwste eerst, met per bestand een ondertekende downloadlink. Van een video die Meta nog verwerkt wordt de stand bij het opvragen bijgewerkt. Geen cursor.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/images" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/images');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/images', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/images",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "meta_copilot_image",
      "id": "12",
      "kind": "image",
      "video_status": null,
      "name": "Veranda antraciet avond",
      "width": 1200,
      "height": 1200,
      "size": 348211,
      "usable": true,
      "download_url": "https://app.klantly.com/api/files/quote-attachment/9d3f9e56-af10-4123-b345-e6f7a8b9c0d5?expires=1789000000&signature=8f1c…",
      "created_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Stand van een nieuwe campagne ophalen

GET /api/v1/meta-copilot/starter

De herkende branche (uit de AI-agent, de offertes en het bedrijfsprofiel), de startvragen met per vraag het antwoord van het bedrijf en het voorstel van de co-pilot (wat verkoop je, in welk gebied, waar komt een klant terecht, hoeveel per dag, welk beeld, welke pagina), of alles compleet is en wat er anders nog ontbreekt (blocked: no_image, no_page of no_landing). Werkt ook op een account zonder campagnes.

Scope
meta_copilot.read — De stand en de meldingen van de Meta co-pilot lezen
Vereiste functie
meta_copilot

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/meta-copilot/starter" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'meta-copilot/starter');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/starter', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/meta-copilot/starter",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_starter",
    "branch": "veranda",
    "branch_label": "veranda's en overkappingen",
    "branch_confidence": "high",
    "complete": false,
    "blocked": "no_image",
    "has_active_campaign": false,
    "questions": []
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Antwoorden op de startvragen opslaan

PUT /api/v1/meta-copilot/starter/intake

Elk veld is los te sturen; null haalt een antwoord weg zodat weer het voorstel van de co-pilot geldt. product is een branche uit de lijst; landing is een sleutel uit de opties (form:<id> of website) of url:https://…; daily_budget_cents tussen 500 en 20000 en nooit boven het dagplafond van het mandaat (anders 422); image_id een beeld uit de bibliotheek. Geeft de bijgewerkte stand terug.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Body (JSON)

VeldTypeOmschrijving
product optioneel string De branche: veranda, dakkapel, aanbouw, kozijnen, zonwering, vloeren, badkamer, keuken of generic. kan leeg zijn (null) · een van: veranda, dakkapel, aanbouw, kozijnen, zonwering, vloeren, badkamer, keuken, generic
area_city optioneel string De plaats waar het werkgebied om heen ligt. kan leeg zijn (null) · maximaal 120 tekens
area_radius_km optioneel integer De straal in kilometers (5–80). kan leeg zijn (null) · van 5 tot 80
landing optioneel string Waar een klant terechtkomt: een sleutel uit de opties (form:<id> of website) of url:https://… voor een eigen adres. kan leeg zijn (null) · maximaal 600 tekens
daily_budget_cents optioneel integer Het dagbudget in centen (500–20000), nooit boven het dagplafond van het mandaat. kan leeg zijn (null) · van 500 tot 20000
image_id optioneel integer Een beeld of video uit de bibliotheek. kan leeg zijn (null)
page_id optioneel string De Facebookpagina die als afzender dient. kan leeg zijn (null) · maximaal 40 tekens

Voorbeeldverzoek

cURL
curl -X PUT "https://app.klantly.com/api/v1/meta-copilot/starter/intake" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product": "veranda",
  "area_city": "Nijmegen",
  "area_radius_km": 40,
  "daily_budget_cents": 1500
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PUT', 'meta-copilot/starter/intake', [
    'json' => [
        'product' => 'veranda',
        'area_city' => 'Nijmegen',
        'area_radius_km' => 40,
        'daily_budget_cents' => 1500,
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/starter/intake', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "product": "veranda",
  "area_city": "Nijmegen",
  "area_radius_km": 40,
  "daily_budget_cents": 1500
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.put(
    "https://app.klantly.com/api/v1/meta-copilot/starter/intake",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "product": "veranda",
        "area_city": "Nijmegen",
        "area_radius_km": 40,
        "daily_budget_cents": 1500
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_starter",
    "branch": "veranda",
    "branch_label": "veranda's en overkappingen",
    "branch_confidence": "high",
    "complete": false,
    "blocked": "no_image",
    "has_active_campaign": false,
    "questions": []
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een nieuwe campagne voorstellen

POST /api/v1/meta-copilot/starter/propose

De co-pilot maakt het plan voor een complete campagne (campagne, advertentieset en advertentie) uit de antwoorden, de opzet die bij vergelijkbare bedrijven in dezelfde branche de goedkoopste aanvragen gaf (anders het playbook van de branche) en een advertentietekst van het model, en zet het als kans van de soort campaign_blueprint klaar (status 201, met blueprint). Die kans accepteren is de goedkeuring: alles wordt gepauzeerd aangemaakt en pas daarna live. Nooit autonoom. 409 als de vragen niet compleet zijn, er geen beeld of pagina is, of de co-pilot uit staat. Kost één modelaanroep.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/starter/propose" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/starter/propose', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/starter/propose', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/starter/propose",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 201

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_opportunity",
    "id": "318",
    "source": "signal",
    "kind": "wasted_spend",
    "status": "open",
    "title": "\"Retargeting winter\" gaf € 184,20 uit zonder één conversie",
    "body": "In de laatste 30 dagen is er € 184,20 besteed en zijn er 212 klikken geweest, maar geen enkele conversie.",
    "impact_cents": 18420,
    "confidence": "high",
    "reversible": true,
    "actionable": true,
    "reuse_post": null,
    "image_id": null,
    "target_level": "adset",
    "target_id": "120210000000000001",
    "target_name": "Retargeting winter",
    "dismissed_reason": null,
    "action_id": null,
    "variant": {
      "reference_ad_id": "120210000000000009",
      "headline": "Veranda op maat, binnen 4 weken geplaatst",
      "primary_text": "Langer buiten zitten zonder gedoe? Onze aluminium veranda wordt op maat gemaakt en binnen vier weken geplaatst. Vraag vandaag een vrijblijvende offerte aan.",
      "description": "Op maat gemaakt",
      "cta_type": "GET_QUOTE"
    },
    "blueprint": {
      "branch": "veranda",
      "city": "Nijmegen",
      "radius_km": 40,
      "age_min": 30,
      "age_max": 65,
      "daily_budget_cents": 1500,
      "has_pixel": true,
      "landing_url": "https://configurator.klantly.com/offerte-aanvragen/01k7x?utm_source=facebook",
      "image_id": "12",
      "headline": "Veranda op maat van Veranda Boys",
      "primary_text": "Langer buiten zitten, ook in het najaar? Veranda Boys maakt veranda's op maat. Vraag vrijblijvend een offerte aan.",
      "description": "Vrijblijvende offerte",
      "cta_type": "GET_QUOTE",
      "peer_accounts": 7,
      "peer_median_cpl": "31.20"
    },
    "decided_at": null,
    "expires_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een beeld uploaden

POST /api/v1/meta-copilot/images

Voegt een beeld of video toe aan de bibliotheek van de co-pilot en registreert het in dezelfde aanroep bij Meta (adimages of advideos). Verstuur het als multipart/form-data met het veld file: een beeld (jpg, png of webp, minimaal 600 × 600 pixels, tot 10 MB) of een video (mp4 of mov, tot 30 MB); hooguit 30 per account. Een variant (voorstel of kans met create_ad_variant) kan het daarna dragen via image_id bij approve of accept; bij een video pas zodra Meta hem heeft verwerkt (video_status ready). 409 conflict als het beeld te klein of de video te groot is, het maximum is bereikt, Meta het weigert of er geen actieve Meta-koppeling is.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Body (JSON)

VeldTypeOmschrijving
file verplicht string (binary) Het beeld of de video zelf, als multipart/form-data. Beeld: jpg, png of webp, minimaal 600 × 600 pixels, maximaal 10 MB. Video: mp4 of mov, maximaal 30 MB; Meta verwerkt hem nog even na (video_status).
name optioneel string De naam (de bestandsnaam zonder extensie, of de meegegeven name). kan leeg zijn (null) · maximaal 255 tekens

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/meta-copilot/images" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'meta-copilot/images');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/images', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/meta-copilot/images",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 201

Voorbeeldantwoord
{
  "data": {
    "object": "meta_copilot_image",
    "id": "12",
    "kind": "image",
    "video_status": null,
    "name": "Veranda antraciet avond",
    "width": 1200,
    "height": 1200,
    "size": 348211,
    "usable": true,
    "download_url": "https://app.klantly.com/api/files/quote-attachment/9d3f9e56-af10-4123-b345-e6f7a8b9c0d5?expires=1789000000&signature=8f1c…",
    "created_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Een beeld verwijderen

DELETE /api/v1/meta-copilot/images/{image}

Haalt het beeld uit de bibliotheek; een al aangemaakte advertentie houdt het beeld bij Meta.

Scope
meta_copilot.write — De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm)
Vereiste functie
meta_copilot

Padparameters

NaamTypeOmschrijving
image verplicht string De id van het beeld in de bibliotheek.

Voorbeeldverzoek

cURL
curl -X DELETE "https://app.klantly.com/api/v1/meta-copilot/images/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('DELETE', 'meta-copilot/images/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/meta-copilot/images/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.delete(
    "https://app.klantly.com/api/v1/meta-copilot/images/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "note",
    "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92",
    "deleted": true
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Het object

Alle velden zijn altijd aanwezig; een veld zonder waarde is null.

VeldTypeOmschrijving
object string Altijd "meta_copilot".
ad_account_id string Het Meta-advertentieaccount, in de act_-vorm.
ad_account_name string De naam van het advertentieaccount bij Meta. kan leeg zijn (null)
currency string De valuta van het account.
mode string De stand: off, shadow (meekijken, niets wijzigen), copilot (alles ter goedkeuring) of autopilot (binnen het mandaat zelf doorvoeren). een van: off, shadow, copilot, autopilot
profile string Het mandaatprofiel: careful, standard of broad. kan leeg zijn (null) · een van: careful, standard, broad
goal_metric string Waar de co-pilot op stuurt. kan leeg zijn (null) · een van: cost_per_quote, cost_per_lead, cost_per_conversion, roas
goal_value string De doelwaarde, als tekst met twee decimalen. kan leeg zijn (null)
monthly_budget string De maandafspraak voor advertentiebudget. kan leeg zijn (null)
autonomous_classes array<string> De actieklassen die de co-pilot zelf mag doorvoeren; leeg in de schaduwstand.
open_alerts integer Aantal open meldingen.
pending_proposals integer Aantal voorstellen die op een besluit wachten.
enabled_at string (date-time) Wanneer de co-pilot is aangezet. kan leeg zijn (null)
tier string De tier van het abonnement: copilot (schaduw en co-pilot, advertentiebudget tot € 2.500 per maand), autopilot (ook autopilot, tot € 7.500) of plus (onbeperkt, dagelijkse operationele ronde); null zonder co-pilot. kan leeg zijn (null) · een van: copilot, autopilot, plus
ad_budget_ceiling string Het advertentiebudget per maand tot waar de co-pilot schuift op deze tier, als tekst met twee decimalen; null = onbeperkt. kan leeg zijn (null)
on_expiry string Wat er met een voorstel gebeurt dat niet op tijd is beoordeeld: lapse (vervalt, de standaard) of apply (wordt na de deadline alsnog doorgevoerd, binnen alle vaste grenzen). een van: lapse, apply
stopped_at string (date-time) Wanneer de co-pilot voor het laatst is gestopt. kan leeg zijn (null)
connection_active boolean Of de Meta-koppeling werkt.
running object Of de co-pilot nu bezig is: null als er niets loopt. kan leeg zijn (null)
running.state string queued (de ronde is aangevraagd en wacht op zijn beurt) of running (de ronde loopt). een van: queued, running
running.since string (date-time) Sinds wanneer. kan leeg zijn (null)
running.kind string Soort ronde: operational of strategy; null zolang hij nog wacht. kan leeg zijn (null) · een van: operational, strategy