Campaign Draft Steps

The campaign creation wizard is split into 4 steps, each backed by its own PATCH endpoint. You can update any step independently — the draft always saves, and the response tells you about any validation issues.

Step	Endpoint	What you edit
1	`PATCH /api/v1/campaigns/drafts/{id}/campaign-settings`	Budget, bidding, targeting, schedule
2	`PATCH /api/v1/campaigns/drafts/{id}/ad-groups`	Ad groups and their keywords
3	`PATCH /api/v1/campaigns/drafts/{id}/ads`	Responsive Search Ads (headlines, descriptions)
4	`PATCH /api/v1/campaigns/drafts/{id}/extensions`	Sitelinks, callouts, phone, snippets

All four endpoints share the same response format — the full refreshed draft plus a warnings array for the current step. Data always saves even when warnings are present; warnings are informational only.

Authentication

Every request requires a valid Bearer token from an approved user who has access to the draft.

Authorization: Bearer <access_token>

Shared response format

All step endpoints return DraftStepResponseSchema:

draft

CampaignDraftSchema

required

The full campaign draft after the update, with all related objects (ad groups, keywords, RSAs, extensions) prefetched.

warnings

ValidationErrorSchema[]

Validation warnings for this step. Each warning contains:

Show Warning object fields

field

string

required

JSON path to the problematic field (e.g. "daily_budget_micros").

code

string

required

Machine-readable error code (e.g. "REQUIRED", "INVALID_RANGE").

message

string

required

Human-readable description of the issue.

Step 1 — Campaign Settings

PATCH /api/v1/campaigns/drafts/{draft_id}/campaign-settings

Update campaign-level settings. Only provided fields are changed — omitted fields stay untouched.

Request fields

name

string

Internal draft name (1–128 characters).

campaign_name

string

The campaign name visible in Google Ads.

daily_budget_micros

integer

Daily budget in micros (1 000 000 micros = 1 currency unit).

bidding_strategy

object

Bidding strategy configuration.

default_match_type

string

Default keyword match type ("BROAD", "PHRASE", "EXACT").

language_ids

integer[]

Google Ads language criterion IDs.

location_targets

object[]

Geo-targeting locations.

network_settings

object

Search / Display network toggles.

ad_schedule

object

Day-of-week and hour bid adjustments.

start_date

string (date)

Campaign start date (YYYY-MM-DD).

end_date

string (date)

Campaign end date (YYYY-MM-DD).

conversion_goals

object[]

Conversion goal configurations.

Example

curl -X PATCH https://dev-api.cattix.com/api/v1/campaigns/drafts/42/campaign-settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Summer Sale 2026",
    "daily_budget_micros": 5000000,
    "start_date": "2026-06-01",
    "end_date": "2026-08-31"
  }'

Response

{
  "draft": {
    "id": 42,
    "name": "CATTIX | 2026-02-10 | car",
    "campaign_name": "Summer Sale 2026",
    "daily_budget_micros": 5000000,
    "start_date": "2026-06-01",
    "end_date": "2026-08-31",
    "...": "..."
  },
  "warnings": [
    {
      "field": "bidding_strategy",
      "code": "REQUIRED",
      "message": "Bidding strategy is required"
    }
  ]
}

Step 2 — Ad Groups

PATCH /api/v1/campaigns/drafts/{draft_id}/ad-groups

Bulk-patch ad groups and their nested keywords in one request. Each item identifies the ad group by id.

Request fields

ad_groups

PatchAdGroupItem[]

required

Array of ad group patches.

Show Ad group item fields

integer

required

ID of the ad group to update.

name

string

Ad group name.

cpc_bid_micros

integer

Default CPC bid in micros.

keywords

PatchKeywordItem[]

Nested keyword patches for this ad group.

Show Keyword item fields

integer

required

ID of the keyword to update.

text

string

Keyword text.

match_type

string

"BROAD", "PHRASE", or "EXACT".

cpc_bid_micros

integer

Keyword-level CPC bid in micros (overrides ad group bid).

final_url

string

Landing page URL for this keyword.

Example

curl -X PATCH https://dev-api.cattix.com/api/v1/campaigns/drafts/42/ad-groups \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_groups": [
      {
        "id": 988,
        "name": "Brand Terms",
        "cpc_bid_micros": 750000,
        "keywords": [
          { "id": 27467, "text": "cattix crm", "match_type": "PHRASE" },
          { "id": 27468, "cpc_bid_micros": 1000000 }
        ]
      }
    ]
  }'

Response

{
  "draft": { "id": 42, "...": "..." },
  "warnings": [
    {
      "field": "ad_groups[fa8820c2-d5fd-4ba6-9f78-0f4804df94a9].keywords",
      "code": "REQUIRED",
      "message": "Ad group 'Brand Terms' must have at least one keyword"
    }
  ]
}

If a referenced ad group or keyword ID does not belong to the draft, the endpoint returns 404 with details about which IDs are missing.

Step 3 — Ads

PATCH /api/v1/campaigns/drafts/{draft_id}/ads

Bulk-patch Responsive Search Ads (RSAs). Each item identifies the RSA by id.

Request fields

responsive_search_ads

PatchRSAItem[]

required

Array of RSA patches.

Show RSA item fields

integer

required

ID of the RSA to update.

headlines

object[]

Array of headline objects with text and optional pinned_field.

descriptions

object[]

Array of description objects with text and optional pinned_field.

final_url

string

Landing page URL.

final_mobile_url

string

Mobile-specific landing page URL.

display_path_1

string

First display path segment (max 15 chars).

display_path_2

string

Second display path segment (max 15 chars).

tracking_url_template

string

Tracking URL template with {lpurl} placeholder.

Example

curl -X PATCH https://dev-api.cattix.com/api/v1/campaigns/drafts/42/ads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "responsive_search_ads": [
      {
        "id": 3315,
        "headlines": [
          { "text": "CATTIX" },
          { "text": "Source Inventory Smarter" },
          { "text": "Get Started for Free" }
        ],
        "final_url": "https://cattix.com/research-pro"
      }
    ]
  }'

Response

{
  "draft": { "id": 42, "...": "..." },
  "warnings": [
    {
      "field": "rsas.final_url",
      "code": "REQUIRED",
      "message": "2 RSA(s) are missing final_url. Please set landing page URLs."
    }
  ]
}

Step 4 — Extensions

PATCH /api/v1/campaigns/drafts/{draft_id}/extensions

Update the draft’s ad extensions (sitelinks, callouts, phone, structured snippets).

Request fields

extensions

object

Extensions configuration object.

Show Extensions fields

sitelinks

object[]

2–20 sitelink extensions, each with link_text, final_url, and optional description_1 / description_2.

callouts

object[]

Up to 20 callout extensions, each with callout_text.

phone

object

Phone extension with country_code and phone_number.

structured_snippets

object[]

Structured snippet extensions with header and values.

Example

curl -X PATCH https://dev-api.cattix.com/api/v1/campaigns/drafts/42/extensions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "extensions": {
      "sitelinks": [
        { "link_text": "Pricing", "final_url": "https://example.com/pricing" },
        { "link_text": "Contact Us", "final_url": "https://example.com/contact" }
      ],
      "callouts": [
        { "callout_text": "Free Trial" },
        { "callout_text": "24/7 Support" }
      ]
    }
  }'

Response

{
  "draft": { "id": 42, "...": "..." },
  "warnings": []
}

How warnings work

Every step endpoint runs its own set of validators after saving. This means:

Your changes are always persisted, even if warnings appear.
Warnings highlight issues that would block campaign submission (e.g. missing budget, too few keywords).
You can safely save incomplete data and come back later — the wizard is designed for iterative editing.

Typical warnings
Warning object

Step	Field	Code	Message
Campaign Settings	`bidding_strategy`	`REQUIRED`	Bidding strategy is required
Campaign Settings	`daily_budget_micros`	`REQUIRED`	Daily budget is required
Campaign Settings	`end_date`	`INVALID_RANGE`	End date must be after start date
Ad Groups	`ad_groups[{temp_id}].keywords`	`REQUIRED`	Ad group '' must have at least one keyword
Ads	`rsas`	`REQUIRED`	At least one completed RSA is required
Ads	`rsas.final_url`	`REQUIRED`	RSA(s) are missing final_url. Please set landing page URLs.
Extensions	`extensions.sitelinks`	`MIN_COUNT`	At least 2 sitelinks are required when sitelinks are provided

{
  "field": "bidding_strategy",
  "code": "REQUIRED",
  "message": "Bidding strategy is required"
}

Warnings do not prevent saving. Treat them as a checklist the user should resolve before submitting the campaign for review.

Getting started

Customization

Writing content

AI tools

Google Ads

Companies

Campaigns

Authentication

Shared response format

Step 1 — Campaign Settings

Request fields

Example

Step 2 — Ad Groups

Request fields

Example

Step 3 — Ads

Request fields

Example

Step 4 — Extensions

Request fields

Example

How warnings work

Getting started

Customization

Writing content

AI tools

Google Ads

Companies

Campaigns

​Authentication

​Shared response format

​Step 1 — Campaign Settings

​Request fields

​Example

​Step 2 — Ad Groups

​Request fields

​Example

​Step 3 — Ads

​Request fields

​Example

​Step 4 — Extensions

​Request fields

​Example

​How warnings work

Authentication

Shared response format

Step 1 — Campaign Settings

Request fields

Example

Step 2 — Ad Groups

Request fields

Example

Step 3 — Ads

Request fields

Example

Step 4 — Extensions

Request fields

Example

How warnings work