Meta Ads
Meta Ads endpoints of the Zanfia Workspace API, with schemas and code samples.
Manage the Meta (Facebook/Instagram) ads behind your offers from the same connections the dashboard uses (Integrations → Ads). Every management route is addressed by a connection id and a Meta ad account id (act_…) and walks the campaign → ad set → ad → creative hierarchy: list and turn campaigns on/off, edit ad-set budgets (minor units) and schedules, page through ads, duplicate an ad into a new PAUSED one, and rebuild a single-image creative. GET /meta-ads/performance joins ingested daily spend with the Zanfia orders each ad produced (first-party revenue, spendScope per offer), GET /meta-ads/directory maps ad ids to names, and POST /meta-ads/sync-insights refreshes the spend data on demand. Errors: 404 connection-not-found, 409 connection-revoked / ad-account-not-accessible / creative-not-editable, 502 meta-graph-failed (with Meta’s reason in message). All routes require a Authorization: Bearer header — see Authentication.
Ads performance (spend vs. orders)
/meta-ads/performanceAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Query Parameters
Inclusive UTC start day, YYYY-MM-DD
Inclusive UTC end day, YYYY-MM-DD
Scope orders and spend to one offer (checkout)
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/performance?since=string&until=string"{ "rows": [ { "adId": "string", "adName": "string", "adsetId": "string", "campaignId": "string", "campaignName": "string", "checkoutId": "string", "spendMinor": 0, "currency": "string", "impressions": 0, "clicks": 0, "metaPurchases": 0, "orders": 0, "revenueMinor": 0, "roas": 0 } ], "daily": [ { "date": "string", "spendMinor": 0, "revenueMinor": 0, "orders": 0 } ], "totals": { "spendMinor": 0, "orders": 0, "revenueMinor": 0, "roas": 0 }, "unattributedMetaOrders": 0, "spendScope": "account"}{ "error": "string", "message": "string"}Ad directory (ids to names)
/meta-ads/directoryAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/directory"{ "entries": [ { "adId": "string", "adName": "string", "adsetId": "string", "campaignId": "string", "campaignName": "string", "destinationUrl": "string", "checkoutId": "string" } ], "truncated": true}{ "error": "string", "message": "string"}Sync insights now
/meta-ads/sync-insightsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/meta-ads/sync-insights" \ -H "Content-Type: application/json" \ -d '{}'{ "connections": 0, "daysWritten": 0, "failures": 0}{ "error": "string", "message": "string"}List campaigns
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/campaignsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Query Parameters
Include ARCHIVED/DELETED campaigns
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/connections/string/ad-accounts/string/campaigns"{ "campaigns": [ { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "objective": "string", "dailyBudgetMinor": 0, "lifetimeBudgetMinor": 0, "startTime": "string", "stopTime": "string" } ]}{ "error": "string", "message": "string"}Update a campaign
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/campaigns/{campaignId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Meta campaign id
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X PATCH "https://example.com/meta-ads/connections/string/ad-accounts/string/campaigns/string" \ -H "Content-Type: application/json" \ -d '{}'{ "campaign": { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "objective": "string", "dailyBudgetMinor": 0, "lifetimeBudgetMinor": 0, "startTime": "string", "stopTime": "string" }}{ "error": "string", "message": "string"}List ad sets
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/ad-setsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Query Parameters
Only ad sets of this campaign
Include ARCHIVED/DELETED ad sets
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/connections/string/ad-accounts/string/ad-sets"{ "adSets": [ { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "dailyBudgetMinor": 0, "lifetimeBudgetMinor": 0, "startTime": "string", "endTime": "string", "currency": "string" } ]}{ "error": "string", "message": "string"}Get an ad set
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/ad-sets/{adSetId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Meta ad set id
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/connections/string/ad-accounts/string/ad-sets/string"{ "adSet": { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "dailyBudgetMinor": 0, "lifetimeBudgetMinor": 0, "startTime": "string", "endTime": "string", "currency": "string" }}{ "error": "string", "message": "string"}Update an ad set
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/ad-sets/{adSetId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Meta ad set id
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X PATCH "https://example.com/meta-ads/connections/string/ad-accounts/string/ad-sets/string" \ -H "Content-Type: application/json" \ -d '{}'{ "adSet": { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "dailyBudgetMinor": 0, "lifetimeBudgetMinor": 0, "startTime": "string", "endTime": "string", "currency": "string" }}{ "error": "string", "message": "string"}List ads
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/adsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Query Parameters
Paging cursor from the previous page's after
Include ARCHIVED/DELETED ads
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/connections/string/ad-accounts/string/ads"{ "ads": [ { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "adsetId": "string", "createdTime": "string", "updatedTime": "string", "thumbnailUrl": "string", "creativeId": "string", "urlTags": "string", "destinationUrl": "string" } ], "hasMore": true, "after": "string"}{ "error": "string", "message": "string"}Create an ad (duplicate)
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/adsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Create a new ad by duplicating an existing one: same ad set and page, a new creative built from the source with the provided overrides. The new ad is ALWAYS created PAUSED (server-enforced safety rail).
Response Body
application/json
application/json
curl -X POST "https://example.com/meta-ads/connections/string/ad-accounts/string/ads" \ -H "Content-Type: application/json" \ -d '{ "sourceAdId": "string", "name": "string" }'{ "ad": { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "adsetId": "string", "createdTime": "string", "updatedTime": "string", "thumbnailUrl": "string", "creativeId": "string", "urlTags": "string", "destinationUrl": "string" }}{ "error": "string", "message": "string"}Update an ad
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/ads/{adId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Meta ad id
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X PATCH "https://example.com/meta-ads/connections/string/ad-accounts/string/ads/string" \ -H "Content-Type: application/json" \ -d '{}'{ "ad": { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "adsetId": "string", "createdTime": "string", "updatedTime": "string", "thumbnailUrl": "string", "creativeId": "string", "urlTags": "string", "destinationUrl": "string" }}{ "error": "string", "message": "string"}Get an ad's creative
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/ads/{adId}/creativeAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Meta ad id
Response Body
application/json
application/json
curl -X GET "https://example.com/meta-ads/connections/string/ad-accounts/string/ads/string/creative"{ "creative": { "id": "string", "name": "string", "editable": true, "message": "string", "headline": "string", "description": "string", "callToActionType": "string", "link": "string", "imageUrl": "string", "urlTags": "string" }}{ "error": "string", "message": "string"}Update an ad's creative
/meta-ads/connections/{connectionId}/ad-accounts/{adAccountId}/ads/{adId}/creativeAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Meta connection id (Integrations → Ads)
Meta ad account id (act_…)
Meta ad id
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X PATCH "https://example.com/meta-ads/connections/string/ad-accounts/string/ads/string/creative" \ -H "Content-Type: application/json" \ -d '{}'{ "ad": { "id": "string", "name": "string", "status": "string", "effectiveStatus": "string", "campaignId": "string", "adsetId": "string", "createdTime": "string", "updatedTime": "string", "thumbnailUrl": "string", "creativeId": "string", "urlTags": "string", "destinationUrl": "string" }, "creative": { "id": "string", "name": "string", "editable": true, "message": "string", "headline": "string", "description": "string", "callToActionType": "string", "link": "string", "imageUrl": "string", "urlTags": "string" }}{ "error": "string", "message": "string"}Was this article helpful?