Create Campaign

Create a new marketing campaign in DRAFT state.

POST/api/v1/marketing/dispatch

Request

curl -X POST "<BASE_URL>/api/v1/marketing/dispatch" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-CQRS-Action: CREATE_CAMPAIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": {
      "amount": 12.5,
      "currencyCode": "USD"
    },
    "kind": "EMAIL",
    "name": "string",
    "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

Authorization

Minimum role: ManagerThe caller must hold this role or a higher one.
Action: CREATE_CAMPAIGN

Headers

AuthorizationstringRequired
Access token of the signed-in user, as a Bearer token. It identifies the user, their role and the workspace.
X-CQRS-ActionstringRequired
Names the command to run. Must be CREATE_CAMPAIGN for this endpoint.
Content-TypestringRequired
Always application/json.
X-Idempotency-KeystringOptional
A key you choose that is unique to this attempt. A command repeated with the same key is not applied a second time.
X-Correlation-IdstringOptional
Your own identifier for the request. Returned in the x-correlation-id response header; generated when you leave it out.

Request body

budgetobjectRequired
No description yet.
2 child fields
- amountnumberRequired
  No description yet.
- currencyCodestringRequired
  No description yet.
kindenumRequired
No description yet.
Allowed values
- EMAIL
- AD_REMARKETING
- MULTI_CHANNEL
- SOCIAL
namestringRequired
No description yet.
minimum length 1
tenant_iduuidRequired
No description yet.
account_iduuid or nullOptional
No description yet.
ad_groupsarray of objectOptional
Operator-authored ad-group rows. Lands on the aggregate as ad_group_specs — the runtime ad_groups (AI ad variants) is a different concept and stays engine-owned.
6 child fields
- descriptionsstringOptional
  One description per line (Google wants 2–4).
- final_urlstringOptional
  No description yet.
- headlinesstringOptional
  One headline per line (Google wants 3–15).
- keywordsstringOptional
  One keyword per line.
- namestringOptional
  No description yet.
- negativesstringOptional
  One negative keyword per line.
ad_platformenum or nullOptional
No description yet.
Allowed values
- LINKEDIN
- GOOGLE
- FACEBOOK
- EMAIL
advertising_channelenum or nullOptional
The primary advertising blueprint (Google: Search/PMax, Meta: Feed/Story).
Allowed values
- SEARCH
- DISPLAY
- PERFORMANCE_MAX
- SOCIAL_FEED
- SOCIAL_VIDEO
- DEMAND_GEN
DEMAND_GEN
Google's YouTube + Discover + Gmail surface. Replaced Discovery in 2023 and is now absorbing both Video Action and standalone Display. Unlike PMax it exposes real per-surface channel controls.
attribution_modelenum or nullOptional
Multi-touch attribution algorithm selection. The retro causal_uplift computation reads this off the campaign at archival time.
Allowed values
- LAST_TOUCH
- FIRST_TOUCH
- LINEAR
- U_SHAPE
- TIME_DECAY
autonomous_orchestrationbooleanOptional
No description yet.
Default
false
bidding_strategyenum or nullOptional
Bidding strategy applied to the campaign on the native platform.
Allowed values
- TARGET_CPA
- TARGET_ROAS
- MAXIMIZE_CONVERSIONS
- MAXIMIZE_CLICKS
- MANUAL_CPC
- MAXIMIZE_CONVERSION_VALUE
- TARGET_IMPRESSION_SHARE
MAXIMIZE_CONVERSION_VALUE
Optimizes total conversion VALUE rather than conversion COUNT. This is the strategy a B2B seller wants once closed-won revenue flows back — count-based strategies reliably buy the cheapest leads, which in B2B are usually the worst.
TARGET_IMPRESSION_SHARE
Search-only on Google. Bids toward a share of impressions rather than a conversion outcome — brand defense, not performance.
budget_typeenum or nullOptional
How the budget is paced on the ad platform.
Allowed values
- DAILY
- LIFETIME
business_namestring or nullOptional
No description yet.
calloutsstring or nullOptional
No description yet.
causal_objectiveenum or nullOptional
Shifts the goal from "Predictive" (who will buy anyway) to "Causal" (who will buy *only if* they see this campaign).
Allowed values
- TRADITIONAL_CONVERSION
- MAXIMIZE_INCREMENTAL_UPLIFT
- MINIMIZE_CHURN_RISK
- OPTIMIZE_LIFETIME_VALUE
connector_binding_iduuid or nullOptional
No description yet.
connector_binding_idsarray of uuidOptional
No description yet.
display_long_headlinestring or nullOptional
No description yet.
display_marketing_image_urlstring or nullOptional
No description yet.
display_square_image_urlstring or nullOptional
No description yet.
excluded_location_idsarray of stringOptional
No description yet.
frequency_cap_maxinteger or nullOptional
No description yet.
at least 0
frequency_cap_window_hoursinteger or nullOptional
No description yet.
at least 0
goal_kindenum or nullOptional
No description yet.
Allowed values
- REVENUE
- LEADS
- MQLS
- SQLS
- CONVERSIONS
- PIPELINE
- ROAS
- IMPRESSIONS
- REACH
- CPM
- CLICKS
- SESSIONS
- CTR
- CPC
- ENGAGEMENT_RATE
- INTERACTIONS
- VIDEO_VIEWS
- CHURN_RATE
- LTV
- REPEAT_RATE
goal_target_valuenumber or nullOptional
No description yet.
google_ads_customer_idstring or nullOptional
No description yet.
linkedin_ad_formatenum or nullOptional
LinkedIn specific ad formats.
Allowed values
- SINGLE_IMAGE
- CAROUSEL
- DOCUMENT
- MESSAGE_AD
- CONVERSATION_AD
linkedin_targeting_modeenum or nullOptional
LinkedIn specific targeting mode. Outsmarts legacy "Matched Audiences" by allowing deep AI integration with the CRM's Buying Committee graph.
Allowed values
- BROAD
- ACCOUNT_LIST
- BUYING_COMMITTEE_MICRO_TARGETING
BUYING_COMMITTEE_MICRO_TARGETING
The "Beyond CRM" feature: Natively synchronizes the CRM's Stakeholder Graph to LinkedIn, ensuring budget is spent ONLY on High-Influence Economic Buyers and explicitly excluding identified Blockers.
location_intentenum or nullOptional
Who counts as "in" a targeted location — Google's geo_target_type_setting.
Allowed values
- PRESENCE_OR_INTEREST
- PRESENCE
PRESENCE_OR_INTEREST
People in, regularly in, or interested in the location — Google's own default, and the reach most campaigns want.
PRESENCE
Only people physically in the location. The safer read for local-service and regulated offers.
meta_ad_account_idstring or nullOptional
Which Meta ad account pays, and which Page the ads publish as. Two picks because Meta has two objects; both bare ids (no act_ prefix).
meta_age_maxinteger or nullOptional
No description yet.
meta_age_mininteger or nullOptional
No description yet.
meta_billing_eventenum or nullOptional
What Meta CHARGES for — distinct from what it optimizes toward.
Allowed values
- IMPRESSIONS
- LINK_CLICKS
meta_call_to_actionenum or nullOptional
The button on a Meta ad.
Allowed values
- LEARN_MORE
- SIGN_UP
- GET_QUOTE
- CONTACT_US
- BOOK_TRAVEL
- SUBSCRIBE
- DOWNLOAD
- APPLY_NOW
meta_countriesarray of stringOptional
ISO-3166 alpha-2 country codes. Meta targets by country code, NOT by the geo-constant ids Google uses — two vocabularies for one idea.
meta_gendersenum or nullOptional
Who an ad set targets by gender.
Allowed values
- ALL
- MEN
- WOMEN
meta_headlinestring or nullOptional
link_data.name — the bold line under the image.
meta_image_urlstring or nullOptional
Meta fetches this URL rather than us uploading bytes.
meta_linkstring or nullOptional
Where the click goes. The button, when present, must use the same link or Meta rejects the pair.
meta_link_descriptionstring or nullOptional
link_data.description — the smaller line under that.
meta_objectiveenum or nullOptional
What a Meta campaign is for — the ODAX objective.
Allowed values
- OUTCOME_AWARENESS
- OUTCOME_TRAFFIC
- OUTCOME_ENGAGEMENT
- OUTCOME_LEADS
- OUTCOME_SALES
- OUTCOME_APP_PROMOTION
OUTCOME_AWARENESS
Reach as many people as possible. The old silent default.
OUTCOME_TRAFFIC
Send people to a destination.
OUTCOME_ENGAGEMENT
Post engagement, video views, messages.
OUTCOME_LEADS
Collect leads — instant forms, calls, sign-ups. What a B2B seller almost always wants, and what the silent default was denying them.
OUTCOME_SALES
Purchases and conversions.
OUTCOME_APP_PROMOTION
App installs and in-app events.
meta_optimization_goalenum or nullOptional
Facebook/Meta specific optimization goals (controls the algorithm).
Allowed values
- LINK_CLICKS
- IMPRESSIONS
- REACH
- CONVERSIONS
- LEAD_GENERATION
- VALUE
meta_page_idstring or nullOptional
No description yet.
meta_placementsarray of enum or nullOptional
No description yet.
Allowed values
- AUTOMATIC
- FACEBOOK_FEED
- INSTAGRAM_FEED
- INSTAGRAM_STORIES
- AUDIENCE_NETWORK
- MESSENGER
meta_primary_textstring or nullOptional
The text above the image.
objectiveenum or nullOptional
What the campaign is trying to achieve. Drives bidding strategy on the channel adapters and attribution weighting in the retro causal_uplift.
Allowed values
- AWARENESS
- TRAFFIC
- ENGAGEMENT
- LEADS
- SALES
- RETENTION
owner_iduuid or nullOptional
No description yet.
platform_specanyOptional
No description yet.
scheduled_end_atdate-time or nullOptional
No description yet.
scheduled_start_atdate-time or nullOptional
No description yet.
segment_iduuid or nullOptional
No description yet.
sentiment_weightingenum or nullOptional
How account sentiment affects real-time ad bidding (Supernatural Layer).
Allowed values
- IGNORE_SENTIMENT
- THROTTLE_NEGATIVE
- SUPERNATURAL
sitelinksarray of objectOptional
No description yet.
4 child fields
- description1stringOptional
  No description yet.
- description2stringOptional
  No description yet.
- textstringOptional
  No description yet.
- urlstringOptional
  No description yet.
special_ad_categoriesarray of enum or nullOptional
No description yet.
Allowed values
- NONE
- CREDIT
- EMPLOYMENT
- HOUSING
- POLITICS
supernatural_prompt_iduuid or nullOptional
No description yet.
target_cpa_microsinteger or nullOptional
Target for a TargetCpa strategy, in micros (1 USD = 1_000_000) to match the platform unit and avoid a float round-trip on money.
target_language_idsarray of stringOptional
No description yet.
target_location_idsarray of stringOptional
Geo-constant ids, never names — campaignCriteria takes ids.
target_placementsstring or nullOptional
No description yet.
target_roasnumber or nullOptional
Target for a TargetRoas strategy. A ratio, NOT a percentage: 4.0 means a 400% return target.
template_iduuid or nullOptional
No description yet.
utm_campaignstring or nullOptional
No description yet.
utm_contentstring or nullOptional
No description yet.
utm_mediumstring or nullOptional
No description yet.
utm_sourcestring or nullOptional
No description yet.
utm_termstring or nullOptional
No description yet.

Response

Status 202. The command was applied. The body reports the outcome and, where the command changes a record, that record's new state.

successbooleanRequired
true when the command was applied.
error_messagestringRequired
Empty when the command was applied.
projected_stateobjectOptional
The record as it stands after the command.
event_payloadobjectOptional
The event the command recorded.
insightsarray of objectOptional
Advisory notes about the result. Each has a code, a message and an impact number.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400X-CQRS-Action is missing or names a command this route does not accept. Send CREATE_CAMPAIGN.
400DOMAIN_ROUTINGThe body is not a valid command. Check the required fields and their types.
401The access token is missing, expired or not valid.
401L1_AUTHThe caller's role is below manager or the caller has no access to this record.
403L1_POLICYA business rule refused the command. The message names the rule.
409L1_IDEMPOTENCYA command with this idempotency key was already applied.
409CONFLICTThe command would duplicate a record that must be unique.
500L3_COMMITThe command was valid but could not be saved.