Ads · Ad Campaigns

Update ad

Updates an ad.

PUThttps://api.pozy.ai/v1/ads/{adId}
Facebook and Instagram, Google Workspace, TikTok, LinkedIn, Pinterest and X and 1 moreupdateAd

Guides: Ads, Meta Ads, TikTok Ads

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Keys with the ads resource group disabled get 403 resource_group_disabled. Authentication

Path parameters

NameTypeNotes
adIdrequiredstring

Request body

application/json, required

  • headlinesarray of object

    At least 1 item. Up to 15 items.

    • textstringrequired

      1 to 30 characters.

    • pinnedFieldstring

      One of HEADLINE_1, HEADLINE_2, HEADLINE_3.

  • descriptionsarray of object

    At least 1 item. Up to 5 items.

    • textstringrequired

      1 to 90 characters.

    • pinnedFieldstring

      One of DESCRIPTION_1, DESCRIPTION_2.

  • finalUrlsarray of string (URL)

    At least 1 item.

  • assetGroupobject
    7 child fields
    • finalUrlstring (URL)

      Matches ^https?://.

    • headlinesarray of string

      At least 3 items. Up to 15 items. Each item: 1 to 30 characters.

    • longHeadlinestring

      1 to 90 characters.

    • descriptionsarray of string

      At least 2 items. Up to 5 items. Each item: 1 to 90 characters.

    • businessNamestring

      1 to 25 characters.

    • imagesobject
      3 child fields
      • landscapearray of string (URL)

        At least 1 item. Up to 20 items. Each item: matches ^https?://.

      • squarearray of string (URL)

        At least 1 item. Up to 20 items. Each item: matches ^https?://.

      • logoarray of string (URL)

        At least 1 item. Up to 5 items. Each item: matches ^https?://.

    • youtubeVideoIdsarray of string

      At least 1 item. Up to 5 items. Each item: matches ^[A-Za-z0-9_-]{11}$.

  • demandGenobject
    11 child fields
    • finalUrlstring (URL)
    • businessNamestring

      Up to 25 characters.

    • headlinesarray of string

      At least 1 item. Up to 5 items. Each item: up to 40 characters.

    • longHeadlinesarray of string

      At least 1 item. Up to 5 items. Each item: up to 90 characters.

    • descriptionsarray of string

      At least 1 item. Up to 5 items. Each item: up to 90 characters.

    • callToActionstring

      Up to 25 characters.

    • imagesobject
      4 child fields
      • landscapearray of string (URL)

        At least 1 item. Up to 20 items.

      • squarearray of string (URL)

        At least 1 item. Up to 20 items.

      • portraitarray of string (URL)

        At least 1 item. Up to 20 items.

      • logoarray of string (URL)

        At least 1 item. Up to 5 items.

    • youtubeVideoIdsarray of string

      At least 1 item. Up to 5 items. Each item: matches ^[A-Za-z0-9_-]{11}$.

    • channelsarray of string

      At least 1 item. Each item: one of youtube_in_stream, youtube_in_feed, youtube_shorts, discover, gmail, display.

    • audienceobject
      5 child fields
      • userListsarray of string

        At least 1 item. Up to 20 items.

      • userInterestsarray of string

        At least 1 item. Up to 20 items.

      • customAudiencesarray of string

        At least 1 item. Up to 20 items.

      • ageRangesarray of object

        At least 1 item. Up to 6 items.

        2 child fields
        • minintegerrequired

          One of 18, 25, 35, 45, 55, 65.

        • maxinteger

          One of 24, 34, 44, 54, 64.

      • gendersarray of string

        At least 1 item. Up to 3 items. Each item: one of male, female, undetermined.

    • audienceIdstring
  • statusstring

    One of active, paused.

  • budgetobject
    • amountnumber
    • typestring

      One of daily, lifetime.

  • targetingobject
    10 child fields
    • keywordsarray of string or object

      One of:

      string
      Option 2 (2 fields)
      • textstringrequired

        Up to 80 characters.

      • matchTypestring

        One of exact, phrase, broad.

    • negativeKeywordsarray of string or object

      One of:

      string
      Option 2 (2 fields)
      • textstringrequired

        Up to 80 characters.

      • matchTypestring

        One of exact, phrase, broad.

    • devicesarray of string or object

      One of:

      string
      Option 2 (2 fields)
      • devicestringrequired

        One of MOBILE, DESKTOP, TABLET, CONNECTED_TV.

      • bidModifiernumber

        0 to 10.

    • ageMininteger

      13 to 65.

    • ageMaxinteger

      13 to 65.

    • countriesarray of string
    • locationsarray of string or object

      One of:

      array of string
      Option 2 (5 fields)
      • countriesarray of string
      • regionsarray of object
        2 child fields
        • keystringrequired
        • namestring
      • citiesarray of object
        2 child fields
        • keystringrequired
        • namestring
      • zipsarray of object
        2 child fields
        • keystringrequired
        • namestring
      • metrosarray of object
        2 child fields
        • keystringrequired
        • namestring
    • languagesarray of string
    • interestsarray of object
      2 child fields
      • idstringrequired
      • namestringrequired
    • advantage_audienceinteger

      One of 0, 1.

  • creativeobject
    14 child fields
    • promotionobject

      Can be null.

    • creativeFeaturesmap of string
    • headlinestring
    • longHeadlinestring

      1 to 90 characters.

    • businessNamestring

      1 to 25 characters.

    • squareImageUrlstring (URL)
    • bodystring
    • descriptionstring

      Up to 255 characters.

    • callToActionstring
    • linkUrlstring (URL)
    • imageUrlstring (URL)
    • videoUrlstring (URL)
    • videoIdstring
    • existingCreativeIdstring
  • namestring

    Up to 255 characters.

Example

curl -X PUT "https://api.pozy.ai/v1/ads/6f40fa2fb0a7e728dd1a73b7" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "headlines": [
    {
      "text": "Hello from Pozy"
    }
  ],
  "descriptions": [
    {
      "text": "Hello from Pozy"
    }
  ],
  "finalUrls": [
    "https://pozy.ai/media/example-1.jpg"
  ],
  "assetGroup": {
    "finalUrl": "https://pozy.ai/media/example-1.jpg",
    "headlines": [
      "string"
    ],
    "longHeadline": "string"
  }
}'

Response

200 on success

  • adobject
    36 child fields
    • _idstring
    • namestring
    • platformstring

      One of facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit.

    • profileIdstring
    • statusobject
    • configuredStatusstring

      Can be null.

    • reviewStatusobject
    • adTypestring

      One of boost, standalone.

    • creativeTypestring

      One of carousel, video, document, image. Can be null.

    • goalstring

      One of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants.

    • isExternalboolean
    • syncedboolean
    • budgetobject

      Can be null.

      5 child fields
      • amountnumber
      • typestring

        One of daily, lifetime.

      • dailynumber
      • lifetimenumber
      • pacingstring
    • metricsobject

      One of:

      Ad Metrics (38 fields)
      • spendnumber
      • impressionsinteger
      • reachinteger
      • clicksinteger
      • ctrnumber
      • cpcnumber
      • cpmnumber
      • engagementinteger
      • conversionsnumber
      • allConversionsnumber
      • costPerConversionnumber
      • actionsmap of integer
      • actionValuesmap of number
      • purchaseValuenumber
      • roasnumber
      • costPerActionmap of number
      • outboundClicksinteger
      • outboundClicksCtrnumber
      • inlineLinkClicksinteger
      • inlineLinkClickCtrnumber
      • uniqueClicksinteger
      • uniqueCtrnumber
      • videoPlayActionsinteger
      • video30SecWatchedActionsinteger
      • videoThruplayWatchedActionsinteger
      • videoP25WatchedActionsinteger
      • videoP50WatchedActionsinteger
      • videoP75WatchedActionsinteger
      • videoP95WatchedActionsinteger
      • videoP100WatchedActionsinteger
      • video2SecWatchedActionsinteger
      • video6SecWatchedActionsinteger
      • video6SecFocusedViewsinteger
      • videoAvgTimeWatchedActionsnumber
      • costPerThruplaynumber
      • funnelobject
        13 child fields
        • landingPageViewsinteger
        • contentViewsinteger
        • searchesinteger
        • wishlistAddsinteger
        • cartAddsinteger
        • checkoutsInitiatedinteger
        • paymentInfoAddsinteger
        • purchasesinteger
        • leadsinteger
        • registrationsCompletedinteger
        • appInstallsinteger
        • messagingConversationsStartedinteger
        • messagingFirstRepliesinteger
      • engagementBreakdownobject
        9 child fields
        • postEngagementinteger
        • pageEngagementinteger
        • reactionsinteger
        • commentsinteger
        • sharesinteger
        • savesinteger
        • pageLikesinteger
        • videoViewsinteger
        • linkClicksinteger
      • lastSyncedAtstring (date-time)
    • platformAdIdstring
    • platformAdAccountIdstring
    • platformCampaignIdstring
    • platformAdSetIdstring
    • campaignNamestring
    • adSetNamestring
    • platformObjectivestring

      Can be null.

    • optimizationGoalstring

      Can be null.

    • costTypestring

      Can be null.

    • servingStatusesarray of string
    • platformAdAccountNamestring

      Can be null.

    • platformCreatedAtstring (date-time)

      Can be null.

    • bidStrategystring
    • bidAmountnumber

      Can be null.

    • roasAverageFloornumber

      Can be null.

    • promotedObjectobject

      Can be null.

      5 child fields
      • custom_event_typestring
      • pixel_idstring
      • page_idstring
      • application_idstring
      • product_set_idstring
    • creativeobject

      Can be null.

      43 child fields
      • assetGroupobject
        8 child fields
        • namestring

          1 to 128 characters.

        • finalUrlstring (URL)required

          Matches ^https?://.

        • headlinesarray of stringrequired

          At least 3 items. Up to 15 items. Each item: 1 to 30 characters.

        • longHeadlinestringrequired

          1 to 90 characters.

        • descriptionsarray of stringrequired

          At least 2 items. Up to 5 items. Each item: 1 to 90 characters.

        • businessNamestringrequired

          1 to 25 characters.

        • imagesobjectrequired
          3 child fields
          • landscapearray of string (URL)required

            At least 1 item. Up to 20 items. Each item: matches ^https?://.

          • squarearray of string (URL)required

            At least 1 item. Up to 20 items. Each item: matches ^https?://.

          • logoarray of string (URL)required

            At least 1 item. Up to 5 items. Each item: matches ^https?://.

        • youtubeVideoIdstring

          Matches ^[A-Za-z0-9_-]{11}$.

      • assetGroupResourceNamestring
      • headlinesarray of string or object

        Up to 15 items.

        One of:

        string
        Google Rsa Headline (2 fields)
        • textstringrequired

          1 to 30 characters.

        • pinnedFieldstring

          One of HEADLINE_1, HEADLINE_2, HEADLINE_3.

      • descriptionsarray of string or object

        Up to 4 items.

        One of:

        string
        Google Rsa Description (2 fields)
        • textstringrequired

          1 to 90 characters.

        • pinnedFieldstring

          One of DESCRIPTION_1, DESCRIPTION_2.

      • headlinestring
      • bodiesarray of string
      • descriptionstring
      • callToActionstring
      • leadGenFormIdstring
      • imageHashstring
      • urlTagsstring

        Can be null.

      • finalUrlsarray of string (URL)

        At least 1 item.

      • thumbnailUrlstring

        Can be null.

      • imageUrlstring
      • assetResourceNamestring
      • assetsobject
        2 child fields
        • marketingImagesarray of object
          1 child field
          • resourceNamestring
        • squareMarketingImagesarray of object
          1 child field
          • resourceNamestring
      • videoIdstring

        Can be null.

      • videoUrlstring

        Can be null.

      • creativeIdstring

        Can be null.

      • creativeFeaturesmap of string
      • catalogobject
        3 child fields
        • productSetIdstring
        • formatstring

          One of single_image, carousel_images_multi_items, carousel_images_single_item, carousel_slideshows.

        • formatTransformationSpecarray of object
          2 child fields
          • formatstring
          • data_sourcearray of string
      • objectTypestring
      • objectStoryIdstring

        Can be null.

      • effectiveObjectStoryIdstring

        Can be null.

      • pageIdstring

        Can be null.

      • effectiveInstagramMediaIdstring

        Can be null.

      • instagramUserIdstring

        Can be null.

      • instagramPermalinkUrlstring

        Can be null.

      • mediaUrlsarray of string
      • carouselCardsarray of object
        7 child fields
        • imageUrlstring
        • imageHashstring
        • headlinestring
        • descriptionstring
        • linkUrlstring
        • callToActionstring
        • videoIdstring
      • isServingboolean

        Can be null.

      • adFormatstring

        Can be null.

      • servingHoldReasonsarray of string
      • bodystring
      • googleHeadlinestring
      • googleDescriptionstring
      • youtubeVideoIdsarray of string
      • linkUrlstring
      • whatsappPhoneNumberstring
      • instagramVideoFallbackobject
        4 child fields
        • kindstringrequired

          One of instagram_video_reuploaded, instagram_video_rehosted_copy.

        • linkedToOriginalPostbooleanrequired
        • videoIdstringrequired
        • platformErrorobjectrequired
          4 child fields
          • codeinteger
          • subcodeinteger
          • messagestringrequired
          • fbtraceIdstring
      • pinterestImageUrlstring
      • pinterestTitlestring
      • pinterestDescriptionstring
    • targetingobject
    • scheduleobject

      Can be null.

      2 child fields
      • startDatestring (date-time)
      • endDatestring (date-time)
    • rejectionReasonstring
    • createdAtstring (date-time)
    • updatedAtstring (date-time)
  • messagestring
200 response
{
  "ad": {
    "_id": "635d87e261ae344ef27fd1df",
    "name": "Acme",
    "platform": "facebook",
    "profileId": "6a0b6573846efc28aaa9a3ff",
    "status": {},
    "configuredStatus": "active",
    "reviewStatus": {},
    "adType": "boost",
    "creativeType": "carousel",
    "goal": "engagement",
    "isExternal": true,
    "synced": true,
    "budget": {
      "amount": 12.5,
      "type": "daily",
      "daily": 12.5,
      "lifetime": 12.5,
      "pacing": "string"
    },
    "metrics": {
      "spend": 12.5,
      "impressions": 1,
      "reach": 1,
      "clicks": 1,
      "ctr": 12.5,
      "cpc": 12.5,
      "cpm": 12.5,
      "engagement": 1,
      "conversions": 12.5,
      "allConversions": 12.5,
      "costPerConversion": 12.5,
      "actions": {
        "key": 1
      },
      "actionValues": {
        "key": 12.5
      },
      "purchaseValue": 12.5,
      "roas": 12.5,
      "costPerAction": {
        "key": 12.5
      },
      "outboundClicks": 1,
      "outboundClicksCtr": 12.5,
      "inlineLinkClicks": 1,
      "inlineLinkClickCtr": 12.5,
      "uniqueClicks": 1,
      "uniqueCtr": 12.5,
      "videoPlayActions": 1,
      "video30SecWatchedActions": 1,
      "videoThruplayWatchedActions": 1,
      "videoP25WatchedActions": 1,
      "videoP50WatchedActions": 1,
      "videoP75WatchedActions": 1,
      "videoP95WatchedActions": 1,
      "videoP100WatchedActions": 1,
      "video2SecWatchedActions": 1,
      "video6SecWatchedActions": 1,
      "video6SecFocusedViews": 1,
      "videoAvgTimeWatchedActions": 12.5,
      "costPerThruplay": 12.5,
      "funnel": {
        "landingPageViews": 1,
        "contentViews": 1,
        "searches": 1,
        "wishlistAdds": 1,
        "cartAdds": 1,
        "checkoutsInitiated": 1,
        "paymentInfoAdds": 1,
        "purchases": 1,
        "leads": 1,
        "registrationsCompleted": 1,
        "appInstalls": 1,
        "messagingConversationsStarted": 1,
        "messagingFirstReplies": 1
      },
      "engagementBreakdown": {
        "postEngagement": 1,
        "pageEngagement": 1,
        "reactions": 1,
        "comments": 1,
        "shares": 1,
        "saves": 1,
        "pageLikes": 1,
        "videoViews": 1,
        "linkClicks": 1
      },
      "lastSyncedAt": "2026-10-02T09:00:00.000Z"
    },
    "platformAdId": "64149c3e561c1c5ac800f87a",
    "platformAdAccountId": "673c621a82c88059710de3fd",
    "platformCampaignId": "68f1e8569b986839e821d8ba",
    "platformAdSetId": "6749c05fd96acf71ce38cbc7",
    "campaignName": "Acme",
    "adSetName": "Acme",
    "platformObjective": "instagram",
    "optimizationGoal": "string",
    "costType": "string",
    "servingStatuses": [
      "active"
    ],
    "platformAdAccountName": "instagram",
    "platformCreatedAt": "2026-10-02T09:00:00.000Z",
    "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
    "bidAmount": 12.5,
    "roasAverageFloor": 12.5,
    "promotedObject": {
      "custom_event_type": "string",
      "pixel_id": "61ea7ce64c184295e2220bf7",
      "page_id": "60cae484a825fef31dae565c",
      "application_id": "6a49643c60aa0c1725a69ce7",
      "product_set_id": "6a424f3abe2064286a5e3a4b"
    },
    "creative": {
      "assetGroup": {
        "name": "Acme",
        "finalUrl": "https://pozy.ai/media/example-1.jpg",
        "headlines": [
          "string"
        ],
        "longHeadline": "string",
        "descriptions": [
          "string"
        ],
        "businessName": "Acme",
        "images": {
          "landscape": [
            "https://pozy.ai/media/example-1.jpg"
          ],
          "square": [
            "https://pozy.ai/media/example-1.jpg"
          ],
          "logo": [
            "https://pozy.ai/media/example-1.jpg"
          ]
        },
        "youtubeVideoId": "65303c153dd819143b179354"
      },
      "assetGroupResourceName": "Acme",
      "headlines": [
        "string"
      ],
      "descriptions": [
        "string"
      ],
      "headline": "Launch day",
      "bodies": [
        "string"
      ],
      "description": "A short description",
      "callToAction": "string",
      "leadGenFormId": "66d3effa66e41a45e5deee45",
      "imageHash": "string",
      "urlTags": "https://pozy.ai/media/example-1.jpg",
      "finalUrls": [
        "https://pozy.ai/media/example-1.jpg"
      ],
      "thumbnailUrl": "https://pozy.ai/media/example-1.jpg",
      "imageUrl": "https://pozy.ai/media/example-1.jpg",
      "assetResourceName": "Acme",
      "assets": {
        "marketingImages": [
          {
            "resourceName": "Acme"
          }
        ],
        "squareMarketingImages": [
          {
            "resourceName": "Acme"
          }
        ]
      },
      "videoId": "65fd297a0da74ab358dd11e9",
      "videoUrl": "https://pozy.ai/media/example-1.jpg",
      "creativeId": "68c59681516c848d73eebe49",
      "creativeFeatures": {
        "key": "OPT_IN"
      },
      "catalog": {
        "productSetId": "6cdea2a8973aaa3d924aa2e8",
        "format": "single_image",
        "formatTransformationSpec": [
          {
            "format": "string",
            "data_source": [
              "string"
            ]
          }
        ]
      },
      "objectType": "string",
      "objectStoryId": "64c3ae81d059271ce0c220b5",
      "effectiveObjectStoryId": "67c37b0ffda71894bd7eea2c",
      "pageId": "675e1e95e076854531b4d051",
      "effectiveInstagramMediaId": "612675e5315fb71660656b0b",
      "instagramUserId": "665a608ca13236ff56e25aae",
      "instagramPermalinkUrl": "https://pozy.ai/media/example-1.jpg",
      "mediaUrls": [
        "https://pozy.ai/media/example-1.jpg"
      ],
      "carouselCards": [
        {
          "imageUrl": "https://pozy.ai/media/example-1.jpg",
          "imageHash": "string",
          "headline": "Launch day",
          "description": "A short description",
          "linkUrl": "https://pozy.ai/media/example-1.jpg",
          "callToAction": "string",
          "videoId": "65fd297a0da74ab358dd11e9"
        }
      ],
      "isServing": true,
      "adFormat": "string",
      "servingHoldReasons": [
        "string"
      ],
      "body": "string",
      "googleHeadline": "string",
      "googleDescription": "string",
      "youtubeVideoIds": [
        "string"
      ],
      "linkUrl": "https://pozy.ai/media/example-1.jpg",
      "whatsappPhoneNumber": "+14155550123",
      "instagramVideoFallback": {
        "kind": "instagram_video_reuploaded",
        "linkedToOriginalPost": true,
        "videoId": "65fd297a0da74ab358dd11e9",
        "platformError": {
          "code": 1,
          "subcode": 1,
          "message": "Hello from Pozy",
          "fbtraceId": "683a6bd99e02a3ca186c487f"
        }
      },
      "pinterestImageUrl": "https://pozy.ai/media/example-1.jpg",
      "pinterestTitle": "string",
      "pinterestDescription": "string"
    },
    "targeting": {},
    "schedule": {
      "startDate": "2026-10-02T09:00:00.000Z",
      "endDate": "2026-10-02T09:00:00.000Z"
    },
    "rejectionReason": "string",
    "createdAt": "2026-10-02T09:00:00.000Z",
    "updatedAt": "2026-10-02T09:00:00.000Z"
  },
  "message": "Hello from Pozy"
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400invalid_request_errorA parameter or body field is missing or invalid. param names it.
401authentication_errorThe API key is missing, revoked or expired.
403permission_errorThe key is read-only, scoped to other profiles, or has this resource group disabled.
404not_foundNothing with that id exists in your workspace.
429rate_limit_errorToo many requests this minute. Wait for Retry-After seconds.

Every code is listed in Errors.

More in Ad Campaigns

GETList adsGETList Google Ads recommendationsPOSTApply Google Ads recommendationsPOSTDismiss Google Ads recommendationsGETList portfolio bid strategiesPOSTCreate portfolio bid strategyPATCHUpdate portfolio bid strategyGETList shared budgetsPOSTCreate a shared budgetGETList Search keywordsPOSTAdd Search ad-group keywordsPATCHPause or enable a Search keywordDELRemove a Search keywordGETList campaignsPOSTCreate a standalone campaignPUTPause or resume a campaignGETRead a campaign's ad schedule (dayparting)PUTReplace a campaign's ad schedule (dayparting)GETRead a campaign's current biddingGETGet live campaign detailsPUTUpdate a campaignDELDelete a campaignGETList campaign-level negative keywordsPUTReplace campaign-level negative keywordsPOSTPause or resume many campaignsPOSTDuplicate a campaignGETRead a Google campaign's device, location, excluded location, and language targetingPUTEdit a Google campaign's device, location, excluded location, or language targetingGETList ad setsPOSTCreate a standalone ad groupPOSTDuplicate an ad setPOSTDuplicate an adGETGet live ad-set detailsPUTUpdate an ad setDELDelete an ad setGETRead a Reddit ad group's targeting and schedulePUTPause or resume a single ad setGETGet campaign treeGETGet daily account metricsGETGet ad detailsDELCancel an adPUTPause or resume a single adGETList campaign assetsPOSTAttach campaign assetsPUTUpdate campaign assetsDELRemove campaign assetsGETList ad-group assetsPOSTAttach ad-group assetsPUTUpdate ad-group assetsDELRemove ad-group assetsGETRead the platform's review verdict for an adGETReview status of each creative in a TikTok Smart+ adGETList ads that need attentionPOSTDismiss an ads alertGETReview status of every TikTok Smart+ ad of an advertiserGETList campaign negative listsPUTReplace campaign negative listsPOSTBoost post as adGETList Performance Max asset groupsPOSTCreate a Performance Max asset groupGETGet a Performance Max asset groupPATCHUpdate a Performance Max asset groupDELRemove a Performance Max asset groupPOSTLink or unlink asset group assetsPUTReplace an asset group's listing-group treePOSTCreate standalone adGETGet campaign conversion goalsPATCHUpdate campaign conversion goals