Ad Campaigns

Launch Ad Campaign

Launch a paid campaign on the platform, targeting this sync's audience.

THIS SPENDS THE CUSTOMER'S ADVERTISING BUDGET. The campaign goes live with daily_budget in currency from start_date, and the platform starts charging as soon as it serves. spend_cap and auto_pause_at are the guard rails; set them. Upload the creative first with POST /ad-campaigns/images.

READ status IN THE BODY. The app answers a refused launch (campaign not found, the platform rejecting it) with a 200 whose status is error, and this route passes that through unchanged rather than guessing an HTTP code for it. A launch can also partly succeed - the platform accepts the campaign and then rejects a creative in review - so follow up with POST /ad-campaigns/{campaign_id}/status-refresh.

post/audience-syncs/{config_id}/launch

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/audience-syncs/{config_id}/launch
  • Auth: HTTP bearer

Path parameters

config_idinteger required

The sync config whose audience the campaign targets.

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

namestring nullable

User-provided campaign name; auto-generated if empty

objectivestring
daily_budgetnumber
currencystring
start_datestring date
end_datestring date nullable
ad_copy_variant_indexinteger nullable
ad_image_document_idinteger nullable
creative_image_urlstring nullable
creative_image_url_squarestring nullable
creative_image_url_portraitstring nullable
logo_image_urlstring nullable
headlinestring nullable
primary_textstring nullable
ctastring nullable
destination_urlstring nullable
customer_match_modestring nullable

Google Customer Match mode: observation (default) | targeting | exclusion

geo_target_countrystring nullable

ISO 3166-1 alpha-2 country code for the location criterion (Google observation/exclusion modes)

google_campaign_subtypestring nullable

Google campaign subtype: display (default) | demand_gen | search

include_lookalike_audiencesboolean nullable

Demand Gen only: attach the lookalike segment derived from the Customer Match list

custom_segment_keywordsstring[] nullable

Demand Gen only: intent keywords for a custom segment (people who search these)

custom_segment_urlsstring[] nullable

Demand Gen only: competitor/relevant URLs for a custom segment (people who browse these)

search_keywordsobject[] nullable

Google Search only: [{text, match_type: broad|phrase|exact, negative: bool}]

rsa_headlinesstring[] nullable

Google Search only: 3-15 Responsive Search Ad headlines (≤30 chars each)

rsa_descriptionsstring[] nullable

Google Search only: 2-4 Responsive Search Ad descriptions (≤90 chars each)

video_asset_idsinteger[] nullable

Google Video only: 1-5 ids of the org's ad_video_assets rows to advertise

video_headlinesstring[] nullable

Google Video only: 3-5 headlines (≤40 chars each)

video_long_headlinesstring[] nullable

Google Video only: 3-5 long headlines (≤90 chars each)

video_descriptionsstring[] nullable

Google Video only: 3-5 descriptions (≤90 chars each)

video_business_namestring nullable

Google Video only: advertiser/brand name shown on the ad (≤25 chars)

video_ctastring nullable

Google Video only: CallToActionType enum value (e.g. LEARN_MORE, SIGN_UP)

selected_channelsobject nullable

Google Video only: placement switches — youtube_in_stream | youtube_in_feed | youtube_shorts | discover | gmail | display | maps (true/false)

auto_pause_atstring date-time nullable

Absolute UTC instant to auto-pause at (ISO-8601 with offset)

auto_pause_tzstring nullable

IANA zone the user picked in (display/intent only)

spend_capnumber nullable

Auto-pause once lifetime SERVED spend reaches this (account currency)

special_ad_categoriesstring[] nullable

Meta special ad categories: HOUSING | EMPLOYMENT | CREDIT | FINANCIAL_PRODUCTS_SERVICES | ISSUES_ELECTIONS_POLITICS | ONLINE_GAMBLING_AND_GAMING | NONE

Response

Successful Response

dataAdPayload required

One ad-platform object, or one handler response.

Changes

No recorded changes to this operation across all 2 revisions of this API.