Meta Ads

Create, boost and measure Facebook and Instagram ads with POST /v1/ads/create and a connected Meta Ads token. This section covers the campaign tree (campaigns, ad sets, ads, creatives), targeting and audiences, the ad types that need their own request shape, measurement (insights, pixels, conversions) and the reads you need around a running ad account. You need a connection with the ads scopes and an ad account (act_<n>) it can act on. Use an existing ad account or create one in the customer's own business portfolio. Ads are included with usage-based billing; a legacy plan without ads gets a 403 on every call here.

Quick reference

Before you start

Creating Meta ads needs 4 things on the Meta side: a Meta Business account with at least one ad account (act_<n>, existing or created through the API), a Facebook Page (ads publish as the Page, and Instagram placements need an Instagram professional account linked to that Page), the ads scopes on the connected account, and a pixel or dataset for any conversion-optimized goal (conversion campaigns).

Meta reviews every ad. A successful create means the ad exists, not that it delivers: reviewStatus (in_review, approved, rejected, with_issues) is separate from the delivery status, and both appear on every node the tree returns.

Connect

Call GET /v1/connect/facebook/ads with profileId. Meta has two login options:

• Classic, the default (loginMode=classic), uses the connected Facebook posting account and its token. An active parent with ads_management and ads_read can be reused without another OAuth round trip.
• Facebook Login for Business (loginMode=business, also accepted on GET /v1/connect/instagram/ads) creates an independent metaads connection with a Business Integration System User token. No posting account is created or required. Open the returned authUrl in a browser to complete consent.

Meta needs a Page as the actor for ad creatives, so select a Page for either path when creating ads. Business login refuses a grant with no Page (no_pages_granted). Connections and billing explains which accounts each path creates and which ones bill. The connecting accounts guide covers Page selection, and the classic ads-only flow covers headless connections and scoping sync to specific ad accounts.

OAuth scopes

ads_management covers campaign management, Reach and Frequency and the Business Manager list. Creating an ad account also requires business_management and business admin access. Accounts connected before ads were enabled on the team do not carry these scopes: reconnect them, and read Account health to see what a connected account was granted. The general scope rule is on the connecting accounts guide.

Find your ad account id

Ad-account operations use accountId (the connected posting or Meta Ads account) and adAccountId (the Meta ad account). Call GET /v1/ads/accounts to list the ad accounts the connection can reach. Creating a new ad account instead takes an active metaads account as accountId and the owning businessId.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: adAccounts } = await zernio.adaccounts.listAdAccounts({
  query: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' }
});

const adAccountId = adAccounts.accounts[0].id;

Response (200):

{
  "accounts": [
    {
      "id": "act_1234567890",
      "name": "Acme",
      "currency": "USD",
      "accountStatus": 1,
      "timezoneName": "America/New_York",
      "minimumDailyBudget": 1,
      "selectable": true,
      "unusableReason": null
    }
  ]
}

accounts[].id is the adAccountId for every other call. Budgets and bids are whole units of currency (75 is $75.00 on a USD account), never cents.

Create an ad account

POST /v1/ads/accounts creates a Meta ad account in the customer's own business portfolio. Discover portfolios with GET /v1/ads/businesses, then send accountId (an active metaads connection), businessId, name, currency and timezoneId. The connection needs business_management and business admin access. System-user tokens can return an empty businesses list; supply the known business ID in that case.

timezoneId is Meta's numeric timezone ID, not an IANA name. The reference links Meta's timezone list. Use the returned adAccountId with the existing ads endpoints.

This call is not idempotent and Zernio never automatically retries it. After a timeout or a 502 with details.creationStatus: "unknown", check the business in Ads Manager before creating again. A 201 with connectionUpdated: false still means the account exists: follow the returned recovery instructions to reconnect with its ID and the previous scoped IDs, instead of repeating the create.

Connections and billing

A Meta Ads connection is its own account, with platform: "metaads" and its own accountId. What else exists next to it depends on how it was connected:

The hidden Facebook account is not shown in the dashboard, cannot be posted to (ACCOUNT_NOT_ENABLED_FOR_POSTING) and is not billed. GET /v1/accounts returns it with enabled: false. Connecting the same Page later through GET /v1/connect/facebook, as the same Facebook user, turns that row into a normal Facebook account with the same accountId, and from then on it bills.

A metaads account is for ads only. It cannot serve organic Facebook or Instagram Insights: the Page insights and Instagram account insights endpoints answer 400 INVALID_FIELD_VALUE for its accountId. For posting, the inbox and organic Insights on the same Page, connect it with GET /v1/connect/facebook and select-page (or connect the Instagram account). That creates a separate facebook account with its own accountId, billed on its own.

Billing counts every active account once across your team, metaads included:

• One metaads account counts once, however many ad accounts it reaches. Running ads also meter separately per active ad (Ads pricing).
• A Facebook Page and an Instagram account connected for posting count once each. A business-login metaads account plus the same Page connected organically is 2 accounts.
• Hidden (enabled: false) and disconnected accounts do not count.
• The first 2 accounts are free. Connecting another without a card on file answers 402 with code: "PAYMENT_REQUIRED" and reason: "free_tier_exceeded"; on an OAuth redirect it arrives as error=payment_required. See Payment method required.

Pricing has the rates.

A Page is missing

The Page lists (GET /v1/connect/facebook/select-page and the Pages stored on a metaads account) show exactly the Pages Meta's token grants. Zernio does not filter out Pages already connected elsewhere. A missing Page was not ticked on Meta's Page step. Meta pre-fills the previous selection, so ask the user to connect again, click "Edit previous settings" and tick the Page. When no Page is granted at all, the redirect carries error=no_facebook_pages and an error_reason (pages_permission_declined, no_pages_granted or granted_pages_not_listed), described in If it fails.

Headless connections

In the classic headless flow, the connect_token on the redirect is valid for 15 minutes. Send it as X-Connect-Token to the list and select Page calls. Business login has no headless Page step and does not accept X-Connect-Token for one: pass pageId on GET /v1/connect/facebook/ads, or change the default Page afterwards with PUT /v1/accounts/{accountId}/facebook-page.

The campaign tree

Every Meta ad lives in a 3-level tree. Each level owns different settings, and that decides which endpoint you call:

You rarely build the tree level by level. POST /v1/ads/create creates all 3 in one call, POST /v1/ads/boost wraps an existing post the same way, and GET /v1/ads/tree reads the hierarchy back with rolled-up metrics. Which level holds the budget (CBO or ABO) decides which update endpoint accepts a budget change; the campaigns page explains budgetLevel.

Pages

Build the ads

Measure what they did

Operate and look things up

Common errors

3 errors are section-wide rather than endpoint-specific.

Everything below the platform boundary comes back as type: "platform_error" with Meta's own message and subcode in platformError. The reference lists the subcodes worth recognizing on sight.

Related

• Connecting accounts: the ads-only connect flow and Page selection.
• Facebook and Instagram: the posting accounts an ad runs as.
• Create standalone ad: every field of the create request.
• Webhooks for ads: lead.received and ad status events.
• Error handling: the envelope every 4xx uses, including platform_error with Meta's own code.