Upsert adset

PUT 
/ad-publishing/facebook/adsets

Create or update a Facebook ad set

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

idstring

Ad set identifier

locationIdstringrequired

Location identifier

namestring

Ad set name

pageIdstring

Facebook page ID

instagramActorIdstring

Instagram actor ID

messagingPlatformsstring[]
Messaging platforms
Available optionsWHATSAPPMESSENGERINSTAGRAM_DIRECT
whatsappNumberstring

WhatsApp phone number

audienceobject

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

budgetobject

Ad set budget config

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.

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.

pixelIdstring

Conversion pixel ID

campaignIdstringrequired

Parent campaign ID

Example (auto)

{
  "id": "adset_123",
  "locationId": "loc_abc123",
  "name": "Targeting Group A",
  "pageId": "123456789",
  "instagramActorId": "ig_123",
  "messagingPlatforms": [
    "WHATSAPP"
  ],
  "whatsappNumber": "+1234567890",
  "audience": {
    "geoLocations": [
      {
        "key": "US",
        "name": "United States",
        "type": "country",
        "selectionType": "include"
      }
    ],
    "ageMin": 18,
    "ageMax": 65,
    "genders": [
      1,
      2
    ]
  },
  "budget": {
    "budgetType": "DAILY",
    "amount": 1000,
    "scheduleStartDate": "2024-01-01",
    "scheduleEndDate": "2024-01-31"
  },
  "conversionLocation": "website",
  "customEventType": "PURCHASE",
  "pixelId": "px_123",
  "campaignId": "camp_123"
}

application/json

The saved ad set

application/json

Schema

Schema

idstringrequired

Ad set identifier

namestringrequired

Ad set name

campaignIdstringrequired

Parent campaign id

fbAdSetIdstring

Facebook ad set 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.

pageIdstringrequired

Page the ads run under

instagramActorIdstringnullable

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

messagingPlatformsstring[]required

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

conversionLocationstring

Where the conversion happens

budgetobjectrequired

Budget configuration

audienceobjectrequired

Targeting

unpublishedChangesboolean

Whether the ad set has edits not yet published

createdAtstringrequired

Created at

updatedAtstringrequired

Updated at

Example (auto)

{
  "id": "6a323f3f4454921db1498cd8",
  "name": "Ad set 1",
  "campaignId": "6a323f3e4454921db1498ccf",
  "fbAdSetId": "120250378906150122",
  "publishingStatus": "PUBLISHED",
  "fbError": null,
  "pageId": "196684453527082",
  "instagramActorId": null,
  "messagingPlatforms": [],
  "conversionLocation": "on_ad",
  "budget": {
    "budgetType": "DAILY",
    "amount": 1,
    "actualAmount": 1
  },
  "audience": {
    "genders": [
      0
    ],
    "geoLocations": [
      {
        "key": "IN",
        "name": "India",
        "type": "country",
        "selectionType": "include",
        "radius": 17,
        "radiusUnit": "km",
        "geometry": {
          "location": {
            "lat": 20.593684,
            "lng": 78.96288
          },
          "locationType": "APPROXIMATE"
        }
      }
    ],
    "ageMin": 18,
    "ageMax": 65,
    "interests": [
      {
        "id": "6016286626383",
        "name": "Facebook access (mobile): tablets",
        "type": "behaviors"
      }
    ],
    "placements": {
      "facebook": [
        "feed",
        "story"
      ],
      "instagram": [
        "reels"
      ],
      "messenger": [
        "messenger_home"
      ]
    },
    "placementType": "manual"
  },
  "unpublishedChanges": false,
  "createdAt": "2026-06-17T06:31:27.129Z",
  "updatedAt": "2026-08-19T11:42:35.835Z"
}