Facebook AdsVersion: v3

Upsert ad

PUT/ad-publishing/facebook/ads

Create or update a Facebook ad

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 identifier

Example:ad_123

locationIdstringrequired

Location identifier

Example:loc_abc123

namestring

Ad name

Example:My Ad Creative

primaryTextstring

Single primary text. Normalised into primaryTexts when that array is empty, so send primaryTexts instead unless you have exactly one variant.

Example:Check out our offer!

headlinestring

Ad-level headline for CAROUSEL ads — used for any card that does not set its own media[].headline. SINGLE (image and video) ads take their headline from the headlines array instead.

Example:Great Deal

descriptionstring

Single ad description. SINGLE (image and video) ads take their description from the descriptions array, and carousel cards from media[].description.

Example:Limited time offer

imageUrlstring

Ad image URL

Example:https://example.com/img.jpg

mediaTypestring

Ad media type

Available optionsSINGLECAROUSEL

Example:SINGLE

mediaobject[]

Media items (images or videos) attached to the ad creative

multiAdvertiserAdsboolean

Enable multi-advertiser ads

Example:false

campaignIdstringrequired

Parent campaign ID

Example:camp_123

adsetIdstringrequired

Parent ad set ID

Example:adset_123

ctastring

Call-to-action button. Valid values depend on the parent campaign objective (and, for sales, the ad set conversionLocation) — OUTCOME_LEADS: APPLY_NOW, DOWNLOAD, GET_OFFER, GET_QUOTE, LEARN_MORE, SIGN_UP, SUBSCRIBE; OUTCOME_TRAFFIC: APPLY_NOW, BOOK_TRAVEL, BUY_NOW, CONTACT_US, GET_OFFER, GET_PROMOTIONS, GET_QUOTE, LEARN_MORE, NO_BUTTON, ORDER_NOW, SHOP_NOW, SIGN_UP, SUBSCRIBE; OUTCOME_ENGAGEMENT: APPLY_NOW, BOOK_TRAVEL, CONTACT_US, GET_PROMOTIONS, GET_QUOTE, INQUIRE_NOW, LEARN_MORE, MESSAGE_PAGE, ORDER_NOW, SEND_UPDATES, SHOP_NOW, SIGN_UP, SUBSCRIBE; OUTCOME_SALES with conversionLocation: messaging: APPLY_NOW, BOOK_TRAVEL, CONTACT_US, GET_QUOTE, LEARN_MORE, MESSAGE_PAGE, ORDER_NOW, PLAY_GAME, SHOP_NOW, SIGN_UP, SUBSCRIBE; OUTCOME_SALES with conversionLocation: website: APPLY_NOW, BOOK_TRAVEL, BUY_TICKETS, CONTACT_US, GET_OFFER, GET_QUOTE, GET_SHOWTIMES, LEARN_MORE, LISTEN_NOW, ORDER_NOW, PLAY_GAME, SHOP_NOW, SIGN_UP, SUBSCRIBE, WATCH_MORE. Note BOOK_TRAVEL is the "Book now" button. Not validated server-side, so values outside this set are forwarded to Facebook and may be rejected there.

Example:LEARN_MORE

conversationFormIdstring

Conversation form ID

Example:conv_123

destinationLinkstring

Destination link URL

Example:https://example.com

destinationFormIdstring

Destination form ID

Example:form_123

primaryTextsobject[]

Primary text variants. Used by every media type. Supply more than one to run Facebook text variations; with a single entry it becomes the ad message. Prefer this over the singular primaryText.

headlinesobject[]

Headline variants. Applies to SINGLE (image and video) ads only — carousel ads take their per-card headline from media[].headline, falling back to the singular headline. Supply more than one to run Facebook text variations.

descriptionsobject[]

Description variants. Applies to SINGLE (image and video) ads only — carousel ads take their per-card description from media[].description. Supply more than one to run Facebook text variations.

Response

application/json

The saved ad

idstringrequired

Ad identifier

Example:6a323f3f4454921db1498ce1

namestringrequired

Ad name

Example:Ad 1

campaignIdstringrequired

Parent campaign id

Example:6a323f3e4454921db1498ccf

adsetIdstringrequired

Parent ad set id

Example:6a323f3f4454921db1498cd8

fbAdIdstring

Facebook ad id, set once published

Example:120250378908850122

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

mediaTypestringrequired

Creative format

Example:SINGLE

ctastring

Call-to-action button

Example:GET_OFFER

multiAdvertiserAdsbooleanrequired

Whether multi-advertiser ads are enabled

Example:true

primaryTextsobject[]required

Primary text variants. Used by SINGLE image and video ads.

headlinesobject[]required

Headline variants

descriptionsobject[]required

Description variants

primaryTextstring

Single primary text. Carried alongside primaryTexts, mirroring its first entry.

Example:Get an instant estimate

headlinestring

Single headline. Used by carousel ads; mirrors the first headlines entry otherwise.

Example:Free home valuation

descriptionstring

Single description

Example:Fast and hassle-free

mediaobject[]required

Creative media

destinationFormIdstring

Instant form the ad routes to, when the conversion location is on-ad

Example:36267736432839880

destinationLinkstringnullable

Click destination. null when the ad routes to an instant form instead.

Example:null

unpublishedChangesboolean

Whether the ad has edits not yet published

Example:false

createdAtstringrequired

Created at

Example:2026-06-17T06:31:27.661Z

updatedAtstringrequired

Updated at

Example:2026-08-19T11:45:39.340Z