Skip to main content
POST
Typescript (SDK)

Authorizations

Authorization
string
header
required

API key in the format: Bearer {api_token}

Headers

Idempotency-Key
string

Makes this write safe to retry: a repeat with the same key replays the first response instead of creating a second resource. Scoped to the account, remembered for 24 hours; reusing a key with a different payload is an error.

Maximum string length: 255

Body

application/json

Ad to create.

account_id
string
ad_account_id
string
name
string
goal
string
budget_amount
number

Budget for the new ad set (or campaign, with budget_level=campaign). Whole currency units, NOT cents: 20 = $20.00. Meta's own Marketing API takes this number in minor units, so it is an easy and expensive mix-up — 2000 here buys $2000.00 of ads, not $20.00.

budget_type
string

daily or lifetime. A lifetime budget also needs end_date.

headline
string
body
string
call_to_action
string
image_url
string
countries
string[]

Countries to target, as ISO 3166-1 alpha-2 codes, e.g. ["US", "CA"]. Defaults to the US.

age_min
integer

Youngest age to target.

Required range: 13 <= x <= 65
age_max
integer

Oldest age to target. 65 means 65 and over.

Required range: 13 <= x <= 65
gender
enum<string>

Target men or women only. Applied on Meta, TikTok and Pinterest; ignored on Google, LinkedIn and X. Defaults to all.

Available options:
all,
male,
female
special_ad_categories
enum<string>[]

Meta only. Declare what the ad offers: HOUSING (homes for sale or rent, mortgages, home insurance), EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES (loans, credit, insurance, investing), ISSUES_ELECTIONS_POLITICS or ONLINE_GAMBLING_AND_GAMING. It is set on the new campaign and this API cannot add it later. With the first three, Meta rejects narrowed targeting: omit age_min, age_max and gender, and use no ZIP codes, lookalikes or location exclusions.

Available options:
HOUSING,
EMPLOYMENT,
FINANCIAL_PRODUCTS_SERVICES,
ISSUES_ELECTIONS_POLITICS,
ONLINE_GAMBLING_AND_GAMING
special_ad_category_country
string[]

Meta only. Countries the category applies to, as ISO 3166-1 alpha-2 codes, e.g. ["US"]. Send the countries the ad targets. Requires special_ad_categories.

Response

Created ad.

Created ad.