Ads

An ad belongs to one ad group and contains the creative shown to a user.

The ad object

{
  "id": "ad_67f480795c61f3e66f163c24",
  "ad_group_id": "adgrp_67f480455c61f3e66f163c23",
  "campaign_id": "cmpn_67f480125c61f3e66f163c22",
  "name": "Planner launch card",
  "status": "paused",
  "review_status": "in_review",
  "review": {
    "status": "in_review"
  },
  "creative": {
    "title": "Plan work faster",
    "body": "Bring tasks, docs, and meetings together.",
    "target_url": "https://example.com/workspace-planner",
    "image_url": "https://example.com/assets/planner-card.png",
    "price": "$12/month"
  },
  "created_at": 1744070521,
  "updated_at": 1744070521
}

Field	Type	Description
id	string	Ad ID, prefixed with ad_.
ad_group_id	string	Parent ad-group ID.
campaign_id	string	Parent campaign ID.
name	string	Internal ad name.
status	string	active, paused, or archived.
review_status	string	Creative review status. New ads are in_review.
review.status	string	The same creative review status.
creative	object	The complete creative.
created_at	integer	Creation time as a Unix timestamp in seconds.
updated_at	integer	Last update time as a Unix timestamp in seconds.

Create an ad

POST /ads

Field	Type	Required	Description
ad_group_id	string	Yes	Parent ad-group ID in the current ad account.
name	string	Yes	From 3 to 1,000 characters.
creative	object	Yes	The complete creative object.
creative.title	string	Yes	From 3 to 50 characters.
creative.body	string	Yes	From 1 to 100 characters.
creative.target_url	string	Yes	An HTTP or HTTPS URL, up to 2,048 characters.
creative.image_url	string	No	An HTTP or HTTPS image URL.
creative.price	string	No	Optional price text.
status	string	No	active or paused. Defaults to paused.

curl -X POST "https://api.withgrowl.com/v1/adm/ads" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_group_id": "adgrp_67f480455c61f3e66f163c23",
    "name": "Planner launch card",
    "status": "paused",
    "creative": {
      "title": "Plan work faster",
      "body": "Bring tasks, docs, and meetings together.",
      "target_url": "https://example.com/workspace-planner",
      "image_url": "https://example.com/assets/planner-card.png",
      "price": "$12/month"
    }
  }'

List ads

GET /ads

The endpoint supports the shared limit, after, before, and order pagination parameters. Pass ad_group_id to return only the ads under one ad group. The filter is optional.

curl "https://api.withgrowl.com/v1/adm/ads?ad_group_id=adgrp_67f480455c61f3e66f163c23&limit=20" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

Retrieve an ad

GET /ads/{ad_id}

curl "https://api.withgrowl.com/v1/adm/ads/ad_67f480795c61f3e66f163c24" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

Update an ad

POST /ads/{ad_id}

You can update name and creative. When changing a creative, send the complete creative object, including title, body, and target_url.

The parent ad group cannot be changed. Use a state action instead of including status in an update.

curl -X POST "https://api.withgrowl.com/v1/adm/ads/ad_67f480795c61f3e66f163c24" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Planner launch card v2",
    "creative": {
      "title": "Organize work in one place",
      "body": "Bring tasks, docs, and meetings together.",
      "target_url": "https://example.com/workspace-planner",
      "image_url": "https://example.com/assets/planner-card-v2.png",
      "price": "$12/month"
    }
  }'

Change ad state

Each endpoint returns the updated ad object.

• POST /ads/{ad_id}/activate
• POST /ads/{ad_id}/pause
• POST /ads/{ad_id}/archive

curl -X POST "https://api.withgrowl.com/v1/adm/ads/ad_67f480795c61f3e66f163c24/activate" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

Archiving is permanent. Repeating the archive action succeeds, but other updates and state changes on an archived ad return 422.