HighLevel: Upsert ad

← Ad publishing operations · Get started

Operation gohighlevel.fb_upsert_ad

Provider route: PUT /ad-publishing/facebook/ads. 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"]["fbUpsertAd"]>[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.fbUpsertAd(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_ad(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 ad — request body — body

Referenced models: Upsert ad — 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 ad — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
adsetId	string	Required within parent	Parent ad set ID
campaignId	string	Required within parent	Parent campaign ID
conversationFormId	string	Optional	Conversation form ID
cta	string	Optional	Call to action type
description	string	Optional	Ad description text
destinationFormId	string	Optional	Destination form ID
destinationLink	string	Optional	Destination link URL
headline	string	Optional	Ad headline text
id	string	Optional	Ad identifier
imageUrl	string	Optional	Ad image URL
locationId	string	Required within parent	Location identifier
media	array	Optional	Media items (images or videos) attached to the ad creative
media[]	Model	Each item	Expand Upsert ad — request body — body media item
mediaType	string	Optional	Ad media type One of: SINGLE, CAROUSEL
multiAdvertiserAds	boolean	Optional	Enable multi-advertiser ads
name	string	Optional	Ad name
primaryText	string	Optional	Ad primary text

Referenced models: Upsert ad — request body — body media item

Upsert ad — request body — body media item

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Optional	Media description
headline	string	Optional	Media headline
link	string	Optional	Media destination link
name	string	Optional	Media file name
selectedPoster	number	Optional	Selected poster index (required when type is video)
src	string	Required within parent	Media source URL
thumbnailUrl	string	Optional	Thumbnail URL (required when type is video)
type	string	Required within parent	Media content type One of: image, video

Policy, approvals and errors

SDK function policy ID: gohighlevel.fb_upsert_ad. Catalog operation: fb-upsert-ad. 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