HighLevel: Upsert adset

← Ad publishing operations · Get started

Operation gohighlevel.fb_upsert_adset

Provider route: PUT /ad-publishing/facebook/adsets. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["adPublishing"]["fbUpsertAdset"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.adPublishing.fbUpsertAdset(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.ad_publishing.fb_upsert_adset(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Upsert adset — request body — body

Referenced models: Upsert adset — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root

Schemas

Upsert adset — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
audience	JSON	Optional	Targeting audience configuration including geo-locations, locales, placements, and custom audiences
audience (allOf 1)	Model	All variants apply	Expand Upsert adset — request body — body / audience / placementType: auto, manual
budget	JSON	Optional	Ad set budget config
budget (allOf 1)	Model	All variants apply	Expand Upsert adset — request body — body / budget / budgetType: DAILY, LIFETIME
campaignId	string	Required within parent	Parent campaign ID
conversionLocation	string	Optional	Conversion location
customEventType	string	Optional	Custom event type
id	string	Optional	Ad set identifier
instagramActorId	string	Optional	Instagram actor ID
locationId	string	Required within parent	Location identifier
messagingPlatforms	array	Optional	Messaging platforms
messagingPlatforms[]	string	Each item	One of: WHATSAPP, MESSENGER, INSTAGRAM_DIRECT
name	string	Optional	Ad set name
pageId	string	Optional	Facebook page ID
pixelId	string	Optional	Conversion pixel ID
whatsappNumber	string	Optional	WhatsApp phone number

Referenced models: Upsert adset — request body — body / budget / budgetType: DAILY, LIFETIME, Upsert adset — request body — body / audience / placementType: auto, manual

Upsert adset — request body — body / budget / budgetType: DAILY, LIFETIME

Field	Type	Presence	Description and constraints
$	object	Root
amount	number	Required within parent	Budget amount
budgetType	string	Required within parent	Budget type One of: DAILY, LIFETIME
scheduleEndDate	string	Optional	Schedule end date
scheduleStartDate	string	Optional	Schedule start date

Upsert adset — request body — body / audience / placementType: auto, manual

Field	Type	Presence	Description and constraints
$	object	Root
ageMax	number	Optional	Maximum age for targeting
ageMin	number	Optional	Minimum age for targeting
genders	array	Optional	Gender targeting (1 = male, 2 = female)
genders[]	number	Each item
geoLocations	array	Required within parent	Geographic locations to target or exclude
geoLocations[]	Model	Each item	Expand Upsert adset — request body — body / audience / placementType: auto, manual geo Locations item
interests	array	Optional	Interest-based targeting criteria
interests[]	Model	Each item	Expand Upsert adset — request body — body / audience / placementType: auto, manual interests item
locales	array	Optional	Language locales to target
locales[]	Model	Each item	Expand Upsert adset — request body — body / audience / placementType: auto, manual locales item
lookalike	array	Optional	Lookalike audiences to target
lookalike[]	Model	Each item	Expand Upsert adset — request body — body / audience / placementType: auto, manual lookalike item
placementType	string	Optional	Placement strategy — "auto" lets Facebook choose, "manual" uses the placements config One of: auto, manual
placements	JSON	Optional	Ad placement positions per platform (only used when placementType is "manual")
placements (allOf 1)	Model	All variants apply	Expand Upsert adset — request body — body / audience / placementType: auto, manual placements facebook, instagram, messenger
retargeting	array	Optional	Retargeting custom audiences to target
retargeting[]	Model	Each item	Expand Upsert adset — request body — body / audience / placementType: auto, manual lookalike item

Referenced models: Upsert adset — request body — body / audience / placementType: auto, manual lookalike item, Upsert adset — request body — body / audience / placementType: auto, manual interests item, Upsert adset — request body — body / audience / placementType: auto, manual locales item, Upsert adset — request body — body / audience / placementType: auto, manual geo Locations item, Upsert adset — request body — body / audience / placementType: auto, manual placements facebook, instagram, messenger

Upsert adset — request body — body / audience / placementType: auto, manual lookalike item

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Custom audience ID
name	string	Required within parent	Custom audience name

Upsert adset — request body — body / audience / placementType: auto, manual interests item

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Interest ID
name	string	Required within parent	Interest name
type	string	Optional	Interest category type (defaults to "interests" if omitted)

Upsert adset — request body — body / audience / placementType: auto, manual locales item

Field	Type	Presence	Description and constraints
$	object	Root
key	number	Required within parent	Facebook locale key
name	string	Required within parent	Locale display name

Upsert adset — request body — body / audience / placementType: auto, manual geo Locations item

Field	Type	Presence	Description and constraints
$	object	Root
geometry	JSON	Optional	Geometry data for address-based targeting
geometry (allOf 1)	Model	All variants apply	Expand Upsert adset — request body — body / audience / placementType: auto, manual geo Locations item geometry location, location Type
key	string	Required within parent	Facebook location key
name	string	Required within parent	Location display name
radius	number	Optional	Targeting radius around the location (for city/address types)
radiusUnit	string	Optional	Unit for the targeting radius One of: km, mi
selectionType	string	Required within parent	Whether the location is included or excluded from targeting One of: include, exclude
type	string	Required within parent	Geographic location type One of: country, city, region, country_group, geo_market, large_geo_area, medium_geo_area, small_geo_area, subcity, neighborhood, zip, address

Referenced models: Upsert adset — request body — body / audience / placementType: auto, manual geo Locations item geometry location, location Type

Upsert adset — request body — body / audience / placementType: auto, manual placements facebook, instagram, messenger

Field	Type	Presence	Description and constraints
$	object	Root
facebook	array	Optional	Facebook placement positions
facebook[]	string	Each item
instagram	array	Optional	Instagram placement positions
instagram[]	string	Each item
messenger	array	Optional	Messenger placement positions
messenger[]	string	Each item

Upsert adset — request body — body / audience / placementType: auto, manual geo Locations item geometry location, location Type

Field	Type	Presence	Description and constraints
$	object	Root
location	object	Required within parent	Geographic coordinates
locationType	string	Required within parent	Geocoding result type

Policy, approvals and errors

SDK function policy ID: gohighlevel.fb_upsert_adset. Catalog operation: fb-upsert-adset. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["adPublishing.write"]

Pinned headers: {"Version": "v3"}

Official provider source