HighLevel: Upsert segment

← Ad publishing operations · Get started

Operation gohighlevel.google_upsert_segment

Provider route: PUT /ad-publishing/google/segments. 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"]["googleUpsertSegment"]>[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.googleUpsertSegment(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.google_upsert_segment(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.locationId	string	Required within parent
query.type	string	Required within parent	One of: CUSTOM_SEGMENTS, WEBSITE_VISITOR, CUSTOMER_MATCH, LOOKALIKE
body	Model	Required within parent	Expand Upsert segment — request body — body

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

Field	Type	Presence	Description and constraints
$	object	Root
countryCodes	array	Optional	Country codes
countryCodes[]	string	Each item
description	string	Optional	Segment description
expansionLevel	string	Optional	Expansion level One of: BALANCED, BROAD, NARROW
id	string	Optional	Segment identifier
members	array	Optional	Segment members — keywords, URLs, or apps that define the custom segment
members[]	Model	Each item	Expand Upsert segment — request body — body members item
membershipLifeSpan	number	Optional	Membership life span
membershipStatus	string	Optional	Membership status
name	string	Required within parent	Segment name
ruleBasedUserList	JSON	Optional	Rule-based user list config
ruleBasedUserList (allOf 1)	Model	All variants apply	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED
seedUserListIds	array	Optional	Seed user list IDs
seedUserListIds[]	string	Each item
status	string	Optional	Segment status
type	string	Optional	Segment type

Referenced models: Upsert segment — request body — body members item, Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED

Upsert segment — request body — body members item

Field	Type	Presence	Description and constraints
$	object	Root
app	string	Optional	App identifier
keyword	string	Optional	Keyword value
memberType	string	Required within parent	Member type One of: KEYWORD, URL, APP
url	string	Optional	URL value

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED

Field	Type	Presence	Description and constraints
$	object	Root
flexibleRuleUserList	JSON	Required within parent	Flexible rule user list configuration
flexibleRuleUserList (allOf 1)	Model	All variants apply	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator
prepopulationStatus	string	Optional	Prepopulation status One of: REQUESTED

Referenced models: Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator

Field	Type	Presence	Description and constraints
$	object	Root
exclusiveOperands	array	Required within parent	Exclusive rule operands
exclusiveOperands[]	Model	Each item	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item
inclusiveOperands	array	Required within parent	Inclusive rule operands
inclusiveOperands[]	Model	Each item	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item
inclusiveRuleOperator	string	Optional	Operator for combining inclusive operands

Referenced models: Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item

Field	Type	Presence	Description and constraints
$	object	Root
lookbackWindowDays	number	Required within parent	Lookback window in days
rule	JSON	Required within parent	Rule definition
rule (allOf 1)	Model	All variants apply	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups

Referenced models: Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups

Field	Type	Presence	Description and constraints
$	object	Root
ruleItemGroups	array	Required within parent	List of rule item groups
ruleItemGroups[]	Model	Each item	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item

Referenced models: Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item

Field	Type	Presence	Description and constraints
$	object	Root
ruleItems	array	Required within parent	List of rule items
ruleItems[]	Model	Each item	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item rule Items item

Referenced models: Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item rule Items item

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item rule Items item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Required within parent	Rule item name One of: url__, referrer__
stringRuleItem	JSON	Required within parent	String rule item condition
stringRuleItem (allOf 1)	Model	All variants apply	Expand Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item rule Items item string Rule Item operator, value

Referenced models: Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item rule Items item string Rule Item operator, value

Upsert segment — request body — body / ruleBasedUserList / prepopulationStatus: REQUESTED flexible Rule User List exclusive Operands, inclusive Operands, inclusive Rule Operator exclusive Operands item rule rule Item Groups rule Item Groups item rule Items item string Rule Item operator, value

Field	Type	Presence	Description and constraints
$	object	Root
operator	string	Required within parent	Rule operator
value	string	Required within parent	Rule value

Policy, approvals and errors

SDK function policy ID: gohighlevel.google_upsert_segment. Catalog operation: google-upsert-segment. 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