ads

Update an ad

Changed on

Partial update. Send only the fields you want to change; omitted fields keep their values, and a field you do send replaces the stored value in full (arrays included). Changes reach the ad platforms on the next sync.

Errors

  • 404 NOT_FOUND: no ad with this id in the active Space.
  • 400 VALIDATION_ERROR: the body failed validation; details.issues[] names each field.
  • 409 COMPETITOR_SIMILARITY: the copy is too close to an ad by a competitor this business tracks, or names one. details says which ad it collided with and whether overridable is true; resend with competitorSimilarityAck: true to save manual copy anyway (recorded on the ad). Generated copy can never override.
put/api/v1/ads/{id}

Request

  • Base URL: https://api.growomat.com
  • URL: https://api.growomat.com/api/v1/ads/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

The ad id.

Headers

X-Space-Idstring

The Space to work in, for example spc_8f3aK2. Omit it to use your personal Space. List your Spaces returns the ids. A Space that does not exist returns 404 SPACE_NOT_FOUND; one you are not a member of returns 403 NOT_A_MEMBER.

Request body

angleIdstring

The angle (claim) this ad argues. Results are reported per angle.

conceptIdstring

The concept (way of making the claim) this ad is a rendition of.

angleProvenance'generated' | 'user' | 'inferred'

Where the angle stamp came from: written by Growomat, set by you, or inferred from the copy. Defaults to user when you set angleId yourself.

competitorSimilarityAckboolean

Save manual copy that the competitor similarity check flagged. Only honoured when the refusal said overridable: true; the decision is recorded on the ad.

_nativeNativeExtensions

Settings that exist on one platform only, keyed by platform id (for example google-ads). Each value is a free-form object that is stored and returned exactly as sent; keys Growomat does not know are kept. Absent by default.

Keys read by platforms whose ad is a post (on the ad, with the campaign as fallback): postType (TEXT or IMAGE), postTitle, postBody, callToAction, imageUrl, videoUrl, videoThumbnailUrl, carouselCards ([{ imageUrl, destinationUrl }]), communities, interests.

Delivery keys read on the campaign: objective, goalType, startTime, endTime, optimizationGoal, conversionPixelId.

adGroupIdstring

The ad group this ad belongs to.

campaignIdstring

The campaign of that ad group.

type'RESPONSIVE_SEARCH_AD' | 'RESPONSIVE_DISPLAY_AD' | 'PERFORMANCE_MAX_ASSET_GROUP' | 'VIDEO_AD' | 'REDDIT_TEXT_POST' | 'REDDIT_IMAGE_POST' | 'REDDIT_VIDEO_POST' | 'REDDIT_CAROUSEL_POST' | 'META_LINK_AD' | 'META_IMAGE_AD' | 'META_VIDEO_AD' | 'META_CAROUSEL_AD' | 'OPENAI_CHAT_CARD' | 'OPENAI_PRODUCT_AD_TEMPLATE' | 'LINKEDIN_SINGLE_IMAGE' | 'LINKEDIN_TEXT_AD' | 'LINKEDIN_VIDEO' | 'LINKEDIN_CAROUSEL' | 'LINKEDIN_DOCUMENT'

Ad format. Defaults from the campaign type per platform; ads imported from a platform record the format that actually serves.

headlinePart1string

First headline. Up to 30 characters on search platforms.

headlinePart2string

Second headline. Up to 30 characters on search platforms.

headlinePart3string

Third headline, optional. Up to 30 characters on search platforms.

descriptionstring

First description line. Up to 90 characters on search platforms.

description2string

Second description line, optional. Up to 90 characters on search platforms.

finalUrlstring uri

The landing page.

path1string

First display-path segment shown after the domain in the ad.

path2string

Second display-path segment.

status'ENABLED' | 'PAUSED' | 'REMOVED'

A paused ad is not shown.

calloutsstring[]

Short phrases shown under the ad, for example "Free shipping".

customLabelsstring[]

Free-form labels for your own grouping and reporting.

trackingUrlTemplatestring

Tracking template for this ad; overrides the ad group's and the campaign's.

finalUrlSuffixstring

Query string appended to the final URL; overrides the ad group's and the campaign's.

urlCustomParametersobject

Custom {_name} parameters available to tracking templates.

Response

OK. The result is in data. List responses also carry meta with nextCursor and total.

dataunknown required

Changes