Skip to main content
Version: v3

Upsert ad

PUT 
/ad-publishing/facebook/ads

Create or update a Facebook ad

Request​

Version stringrequired

API Version

Available optionsv3
application/json

Bodyrequired

    idstring

    Ad identifier

    locationIdstringrequired

    Location identifier

    namestring

    Ad name

    primaryTextstring

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

    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.

    descriptionstring

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

    imageUrlstring

    Ad image URL

    mediaTypestring

    Ad media type

    Available optionsSINGLECAROUSEL
    mediaobject[]

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

    multiAdvertiserAdsboolean

    Enable multi-advertiser ads

    campaignIdstringrequired

    Parent campaign ID

    adsetIdstringrequired

    Parent ad set ID

    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.

    conversationFormIdstring

    Conversation form ID

    destinationLinkstring

    Destination link URL

    destinationFormIdstring

    Destination form ID

    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.

application/json

The saved ad

Schema
    idstringrequired

    Ad identifier

    namestringrequired

    Ad name

    campaignIdstringrequired

    Parent campaign id

    adsetIdstringrequired

    Parent ad set id

    fbAdIdstring

    Facebook ad id, set once published

    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
    fbErrorstringnullable

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

    mediaTypestringrequired

    Creative format

    ctastring

    Call-to-action button

    multiAdvertiserAdsbooleanrequired

    Whether multi-advertiser ads are enabled

    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.

    headlinestring

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

    descriptionstring

    Single description

    mediaobject[]required

    Creative media

    destinationFormIdstring

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

    destinationLinkstringnullable

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

    unpublishedChangesboolean

    Whether the ad has edits not yet published

    createdAtstringrequired

    Created at

    updatedAtstringrequired

    Updated at