Skip to main content
Facebook AdsVersion: v3

Upsert adset

PUT/ad-publishing/facebook/adsets

Create or update a Facebook ad set

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:adPublishing.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3
Example:v3

Body

application/json
idstring

Ad set identifier

Example:adset_123
locationIdstringrequired

Location identifier

Example:loc_abc123
namestring

Ad set name

Example:Targeting Group A
pageIdstring

Facebook page ID

Example:123456789
instagramActorIdstring

Instagram actor ID

Example:ig_123
messagingPlatformsstring[]

Messaging platforms

Available optionsWHATSAPPMESSENGERINSTAGRAM_DIRECT
Example:["WHATSAPP"]
whatsappNumberstring

WhatsApp phone number

Example:+1234567890
audienceobject

Targeting audience configuration including geo-locations, locales, placements, and custom audiences

budgetobject

Ad set budget config; schedule only under a campaign budget

bidAmountnumber

Bid cap or cost-per-result goal in account currency. Required when the campaign bid strategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.

Example:2.5
conversionLocationstring

Where the conversion happens. Valid values depend on the parent campaign objective — OUTCOME_LEADS: on_ad (instant form), website, website_and_lead_form; OUTCOME_SALES: website (pixel), messaging. Not validated server-side, so values outside this set are forwarded to Facebook and may be rejected there.

Example:website
customEventTypestring

Facebook standard event optimised for. Only meaningful when conversionLocation is website (requires pixelId). Valid values depend on the parent campaign objective — OUTCOME_LEADS: COMPLETE_REGISTRATION, CONTACT, CONTENT_VIEW, FIND_LOCATION, LEAD, SCHEDULE, SEARCH, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE; OUTCOME_SALES: ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, COMPLETE_REGISTRATION, CONTENT_VIEW, DONATE, INITIATED_CHECKOUT, PURCHASE, SEARCH, START_TRIAL, SUBSCRIBE. Not validated server-side, so values outside this set are forwarded to Facebook and may be rejected there.

Example:PURCHASE
pixelIdstring

Conversion pixel ID

Example:px_123
campaignIdstringrequired

Parent campaign ID

Example:camp_123

Response

application/json

The saved ad set

idstringrequired

Ad set identifier

Example:6a323f3f4454921db1498cd8
namestringrequired

Ad set name

Example:Ad set 1
campaignIdstringrequired

Parent campaign id

Example:6a323f3e4454921db1498ccf
fbAdSetIdstring

Facebook ad set id, set once published

Example:120250378906150122
publishingStatusstringrequired

Publishing status. On a published entity this is not the state you asked for but the effective_status Meta reports, mapped back — a pause or resume re-reads it live, so an ad awaiting review comes back IN_REVIEW rather than PAUSED or PUBLISHED. Any effective status this service does not recognise also maps to IN_REVIEW.

Available optionsDRAFTSCHEDULEDPUBLISHINGPUBLISHEDPAUSEDIN_REVIEWWITH_ISSUESREJECTEDARCHIVEDFAILED
Example:PUBLISHED
fbErrorstringnullable

Publish error from Facebook. null on reads when there is none.

Example:null
pageIdstringrequired

Page the ads run under

Example:196684453527082
instagramActorIdstringnullable

Instagram account the ads run under. null when not linked.

Example:null
messagingPlatformsstring[]required

Messaging destinations for click-to-message ads. Empty for other conversion locations.

Example:["MESSENGER","INSTAGRAM_DIRECT"]
conversionLocationstring

Where the conversion happens

Example:on_ad
budgetobjectrequired

Budget configuration

audienceobjectrequired

Targeting

unpublishedChangesboolean

Whether the ad set has edits not yet published

Example:false
createdAtstringrequired

Created at

Example:2026-06-17T06:31:27.129Z
updatedAtstringrequired

Updated at

Example:2026-08-19T11:42:35.835Z