Ads · Ad Campaigns
Updates an ad.
https://api.pozy.ai/v1/ads/{adId}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
| Name | Type | Notes |
|---|---|---|
adIdrequired | string |
Request body
application/json, required
headlinesarray of objectAt least 1 item. Up to 15 items.
textstringrequired1 to 30 characters.
pinnedFieldstringOne of
HEADLINE_1,HEADLINE_2,HEADLINE_3.
descriptionsarray of objectAt least 1 item. Up to 5 items.
textstringrequired1 to 90 characters.
pinnedFieldstringOne of
DESCRIPTION_1,DESCRIPTION_2.
finalUrlsarray of string (URL)At least 1 item.
assetGroupobject7 child fields
finalUrlstring (URL)Matches
^https?://.headlinesarray of stringAt least 3 items. Up to 15 items. Each item: 1 to 30 characters.
longHeadlinestring1 to 90 characters.
descriptionsarray of stringAt least 2 items. Up to 5 items. Each item: 1 to 90 characters.
businessNamestring1 to 25 characters.
imagesobject3 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 stringAt least 1 item. Up to 5 items. Each item: matches
^[A-Za-z0-9_-]{11}$.
demandGenobject11 child fields
finalUrlstring (URL)businessNamestringUp to 25 characters.
headlinesarray of stringAt least 1 item. Up to 5 items. Each item: up to 40 characters.
longHeadlinesarray of stringAt least 1 item. Up to 5 items. Each item: up to 90 characters.
descriptionsarray of stringAt least 1 item. Up to 5 items. Each item: up to 90 characters.
callToActionstringUp to 25 characters.
imagesobject4 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 stringAt least 1 item. Up to 5 items. Each item: matches
^[A-Za-z0-9_-]{11}$.channelsarray of stringAt least 1 item. Each item: one of
youtube_in_stream,youtube_in_feed,youtube_shorts,discover,gmail,display.audienceobject5 child fields
userListsarray of stringAt least 1 item. Up to 20 items.
userInterestsarray of stringAt least 1 item. Up to 20 items.
customAudiencesarray of stringAt least 1 item. Up to 20 items.
ageRangesarray of objectAt least 1 item. Up to 6 items.
2 child fields
minintegerrequiredOne of
18,25,35,45,55,65.maxintegerOne of
24,34,44,54,64.
gendersarray of stringAt least 1 item. Up to 3 items. Each item: one of
male,female,undetermined.
audienceIdstring
statusstringOne of
active,paused.budgetobjectamountnumbertypestringOne of
daily,lifetime.
targetingobject10 child fields
keywordsarray of string or objectOne of:
string
Option 2 (2 fields)
textstringrequiredUp to 80 characters.
matchTypestringOne of
exact,phrase,broad.
negativeKeywordsarray of string or objectOne of:
string
Option 2 (2 fields)
textstringrequiredUp to 80 characters.
matchTypestringOne of
exact,phrase,broad.
devicesarray of string or objectOne of:
string
Option 2 (2 fields)
devicestringrequiredOne of
MOBILE,DESKTOP,TABLET,CONNECTED_TV.bidModifiernumber0 to 10.
ageMininteger13 to 65.
ageMaxinteger13 to 65.
countriesarray of stringlocationsarray of string or objectOne of:
array of string
Option 2 (5 fields)
countriesarray of stringregionsarray of object2 child fields
keystringrequirednamestring
citiesarray of object2 child fields
keystringrequirednamestring
zipsarray of object2 child fields
keystringrequirednamestring
metrosarray of object2 child fields
keystringrequirednamestring
languagesarray of stringinterestsarray of object2 child fields
idstringrequirednamestringrequired
advantage_audienceintegerOne of
0,1.
creativeobject14 child fields
promotionobjectCan be null.
creativeFeaturesmap of stringheadlinestringlongHeadlinestring1 to 90 characters.
businessNamestring1 to 25 characters.
squareImageUrlstring (URL)bodystringdescriptionstringUp to 255 characters.
callToActionstringlinkUrlstring (URL)imageUrlstring (URL)videoUrlstring (URL)videoIdstringexistingCreativeIdstring
namestringUp 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"
}
}'const res = await fetch("https://api.pozy.ai/v1/ads/6f40fa2fb0a7e728dd1a73b7", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.POZY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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"
}
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);import os
import requests
resp = requests.put(
"https://api.pozy.ai/v1/ads/6f40fa2fb0a7e728dd1a73b7",
headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
json={
"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",
},
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())Response
200 on success
adobject36 child fields
_idstringnamestringplatformstringOne of
facebook,instagram,tiktok,linkedin,pinterest,google,twitter,openai,reddit.profileIdstringstatusobjectconfiguredStatusstringCan be null.
reviewStatusobjectadTypestringOne of
boost,standalone.creativeTypestringOne of
carousel,video,document,image. Can be null.goalstringOne of
engagement,traffic,awareness,video_views,lead_generation,lead_conversion,conversions,app_promotion,catalog_sales,page_likes,page_visits,job_applicants.isExternalbooleansyncedbooleanbudgetobjectCan be null.
5 child fields
amountnumbertypestringOne of
daily,lifetime.dailynumberlifetimenumberpacingstring
metricsobjectOne of:
Ad Metrics (38 fields)
spendnumberimpressionsintegerreachintegerclicksintegerctrnumbercpcnumbercpmnumberengagementintegerconversionsnumberallConversionsnumbercostPerConversionnumberactionsmap of integeractionValuesmap of numberpurchaseValuenumberroasnumbercostPerActionmap of numberoutboundClicksintegeroutboundClicksCtrnumberinlineLinkClicksintegerinlineLinkClickCtrnumberuniqueClicksintegeruniqueCtrnumbervideoPlayActionsintegervideo30SecWatchedActionsintegervideoThruplayWatchedActionsintegervideoP25WatchedActionsintegervideoP50WatchedActionsintegervideoP75WatchedActionsintegervideoP95WatchedActionsintegervideoP100WatchedActionsintegervideo2SecWatchedActionsintegervideo6SecWatchedActionsintegervideo6SecFocusedViewsintegervideoAvgTimeWatchedActionsnumbercostPerThruplaynumberfunnelobject13 child fields
landingPageViewsintegercontentViewsintegersearchesintegerwishlistAddsintegercartAddsintegercheckoutsInitiatedintegerpaymentInfoAddsintegerpurchasesintegerleadsintegerregistrationsCompletedintegerappInstallsintegermessagingConversationsStartedintegermessagingFirstRepliesinteger
engagementBreakdownobject9 child fields
postEngagementintegerpageEngagementintegerreactionsintegercommentsintegersharesintegersavesintegerpageLikesintegervideoViewsintegerlinkClicksinteger
lastSyncedAtstring (date-time)
platformAdIdstringplatformAdAccountIdstringplatformCampaignIdstringplatformAdSetIdstringcampaignNamestringadSetNamestringplatformObjectivestringCan be null.
optimizationGoalstringCan be null.
costTypestringCan be null.
servingStatusesarray of stringplatformAdAccountNamestringCan be null.
platformCreatedAtstring (date-time)Can be null.
bidStrategystringbidAmountnumberCan be null.
roasAverageFloornumberCan be null.
promotedObjectobjectCan be null.
5 child fields
custom_event_typestringpixel_idstringpage_idstringapplication_idstringproduct_set_idstring
creativeobjectCan be null.
43 child fields
assetGroupobject8 child fields
namestring1 to 128 characters.
finalUrlstring (URL)requiredMatches
^https?://.headlinesarray of stringrequiredAt least 3 items. Up to 15 items. Each item: 1 to 30 characters.
longHeadlinestringrequired1 to 90 characters.
descriptionsarray of stringrequiredAt least 2 items. Up to 5 items. Each item: 1 to 90 characters.
businessNamestringrequired1 to 25 characters.
imagesobjectrequired3 child fields
landscapearray of string (URL)requiredAt least 1 item. Up to 20 items. Each item: matches
^https?://.squarearray of string (URL)requiredAt least 1 item. Up to 20 items. Each item: matches
^https?://.logoarray of string (URL)requiredAt least 1 item. Up to 5 items. Each item: matches
^https?://.
youtubeVideoIdstringMatches
^[A-Za-z0-9_-]{11}$.
assetGroupResourceNamestringheadlinesarray of string or objectUp to 15 items.
One of:
string
Google Rsa Headline (2 fields)
textstringrequired1 to 30 characters.
pinnedFieldstringOne of
HEADLINE_1,HEADLINE_2,HEADLINE_3.
descriptionsarray of string or objectUp to 4 items.
One of:
string
Google Rsa Description (2 fields)
textstringrequired1 to 90 characters.
pinnedFieldstringOne of
DESCRIPTION_1,DESCRIPTION_2.
headlinestringbodiesarray of stringdescriptionstringcallToActionstringleadGenFormIdstringimageHashstringurlTagsstringCan be null.
finalUrlsarray of string (URL)At least 1 item.
thumbnailUrlstringCan be null.
imageUrlstringassetResourceNamestringassetsobject2 child fields
marketingImagesarray of object1 child field
resourceNamestring
squareMarketingImagesarray of object1 child field
resourceNamestring
videoIdstringCan be null.
videoUrlstringCan be null.
creativeIdstringCan be null.
creativeFeaturesmap of stringcatalogobject3 child fields
productSetIdstringformatstringOne of
single_image,carousel_images_multi_items,carousel_images_single_item,carousel_slideshows.formatTransformationSpecarray of object2 child fields
formatstringdata_sourcearray of string
objectTypestringobjectStoryIdstringCan be null.
effectiveObjectStoryIdstringCan be null.
pageIdstringCan be null.
effectiveInstagramMediaIdstringCan be null.
instagramUserIdstringCan be null.
instagramPermalinkUrlstringCan be null.
mediaUrlsarray of stringcarouselCardsarray of object7 child fields
imageUrlstringimageHashstringheadlinestringdescriptionstringlinkUrlstringcallToActionstringvideoIdstring
isServingbooleanCan be null.
adFormatstringCan be null.
servingHoldReasonsarray of stringbodystringgoogleHeadlinestringgoogleDescriptionstringyoutubeVideoIdsarray of stringlinkUrlstringwhatsappPhoneNumberstringinstagramVideoFallbackobject4 child fields
kindstringrequiredOne of
instagram_video_reuploaded,instagram_video_rehosted_copy.linkedToOriginalPostbooleanrequiredvideoIdstringrequiredplatformErrorobjectrequired4 child fields
codeintegersubcodeintegermessagestringrequiredfbtraceIdstring
pinterestImageUrlstringpinterestTitlestringpinterestDescriptionstring
targetingobjectscheduleobjectCan be null.
2 child fields
startDatestring (date-time)endDatestring (date-time)
rejectionReasonstringcreatedAtstring (date-time)updatedAtstring (date-time)
messagestring
{
"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:
| 400 | invalid_request_error | A parameter or body field is missing or invalid. param names it. |
| 401 | authentication_error | The API key is missing, revoked or expired. |
| 403 | permission_error | The key is read-only, scoped to other profiles, or has this resource group disabled. |
| 404 | not_found | Nothing with that id exists in your workspace. |
| 429 | rate_limit_error | Too many requests this minute. Wait for Retry-After seconds. |
Every code is listed in Errors.