Ads API •References / ads / Create a Draft Ad

Create a Draft Ad

Creates a draft ad under a given ad account.

Request

ad_account_idstring [uuid]
Required
A unique identifier for an Ad Account.
Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a

ad_set_idstring [uuid]
Required
A unique identifier for the entity.
Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
statusstring
Status of the ad.
Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING", "PENDING_APPROVAL", "REJECTED", "UNRECOGNIZED"Example: "PENDING"
namestring
Name given to identify the ad draft.
Example: "New Ad Draft"
advertiser_namestring
Name of the advertiser for the ad draft.
Example: "Heart Dance Recordings"
Assets for the ad.
- asset_idstring [uuid]
  Required
  A unique identifier for an AUDIO, VIDEO or IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- companion_asset_idstring [uuid]
  A unique identifier for an IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- logo_asset_idstring [uuid]
  Required
  A unique identifier for an IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- canvas_asset_idstring [uuid]
  A unique identifier for an IMAGE or VIDEO asset with 9:16 aspect ratio.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
asset_formatstring
Format of the asset.
Allowed values: "AUDIO", "VIDEO", "IMAGE", "CATALOG"Example: "AUDIO"
taglinestring
Tagline to give listeners more context about your company or product. This will be displayed in the CTA card leavebehind.
Example: "Good Food for Good Dogs"
Array maximum length: 11
Third party viewability tracking via partner and url
- measurement_partnerstring
  Name of the third-party measurement partner.
  Allowed values: "IAS", "DCM", "UNSET"Example: "IAS"
- urlstring
  Third-party tracking URL.
  Example: "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"
The metadata for the behavior of the call-to-action button.
- keystring
  The identifier used for the call-to-action button. This will be translated using the locale.
  Allowed values: "APPLY_NOW", "BOOK_NOW", "BUY_NOW", "BUY_TICKETS", "CLICK_NOW", "DOWNLOAD", "FIND_STORES", "GET_COUPON", "GET_INFO", "LEARN_MORE", "LISTEN_NOW", "MORE_INFO", "ORDER_NOW", "PRE_SAVE", "SAVE_NOW", "SHARE", "SHOP_NOW", "SIGN_UP", "VISIT_PROFILE", "VISIT_SITE", "WATCH_NOW"Example: "LEARN_MORE"
- languagestring
  The language which the ad is presented.
  Allowed values: "ARABIC", "ARABIC_EGYPT", "BULGARIAN", "CHINESE", "CHINESE_HK", "CHINESE_TAIWAN", "CROATIAN", "CZECH", "DANISH", "DUTCH", "ENGLISH", "FINNISH", "FRENCH", "FRENCH_CANADA", "GERMAN", "GREEK", "HEBREW", "HUNGARIAN", "INDONESIAN", "ITALIAN", "JAPANESE", "KOREAN", "NORWEGIAN", "POLISH", "PORTUGUESE", "PORTUGUESE_PORTUGAL", "ROMANIAN", "RUSSIAN", "SLOVAK", "SPANISH", "SPANISH_ARGENTINA", "SPANISH_LATAM_CARIBBEAN", "SPANISH_MEXICO", "SWEDISH", "THAI", "TURKISH", "UKRAINIAN", "VIETNAMESE"Example: "ENGLISH"
- clickthrough_urlstring
  The link to the ads desired landing page.
  Example: "https://www.spotify.com"
placementsarray of strings
Placement of the ad.
Allowed values: "MUSIC", "PODCAST"Example: "MUSIC"
Catalog of things to be placed in a carousel type ad. Ad Set asset_format must be set to CATALOG.
- idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- namestring
  Name given to identify your catalog.
  Example: "Holiday Deals"
- Item within a catalog
  idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  asset_idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  Metadata associated with attached asset_id. Only present in response.
  asset_typestring
  The type of asset.
  Allowed values: "AUDIO", "IMAGE", "VIDEO"Example: "IMAGE"
  asset_namestring
  Name of attached assetId.
  Example: "File name"
  asset_urlstring [uri]
  URL associated with attached asset_id.
  Example: "https://example.com/asset_id"
  skustring
  Client defined product ID. Must be unique to a catalog.
  Example: "SKU-7415695"
  positioninteger
  Required
  Preferred ordering to display the catalog items in ads.
  Example: 3
  clickthrough_urlstring [uri]
  The link to the ads desired landing page.
  Example: "https://www.spotify.com"
  microinteger [int64]
  Price multiplied by x10 to the 6th power. Ex: cost of $250, would be a cost_micro of 250000000.
  Example: 250000000
  currency_codestring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
  display_pricestring
  Displayable localized price. Only present in response.
  Example: "$19.99 USD"
  microinteger [int64]
  Price multiplied by x10 to the 6th power. Ex: cost of $250, would be a cost_micro of 250000000.
  Example: 250000000
  currency_codestring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
  display_sale_pricestring
  Displayable localized sale price. Only present in response.
  Example: "$14.99 USD"
  taglinestring
  Tagline to give listeners more context about your company or product. This will be displayed in the CTA card leavebehind.
  Pattern: ^\S.*\S$Length between 2 and 40Example: "Good Food for Good Dogs"
dv_client_codestring
DoubleVerify client code.
Example: "2097467"
weightinteger [int32]
The weight of the ad.
Range: 1 - 100Example: 10

Response

Metadata of created draft ad.

statusstring
Status of the ad.
Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING", "PENDING_APPROVAL", "REJECTED", "UNRECOGNIZED"Example: "PENDING"
draft_hierarchy_versioninteger
Read only
The version of the draft hierarchy. Required when publishing the campaign draft.
Minimum value: 1Example: 1
idstring [uuid]
A unique identifier for the entity.
Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
created_atstring [date-time]
Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example: "2026-01-23T04:56:07Z"
updated_atstring [date-time]
Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example: "2026-01-23T04:56:07Z"
ad_set_idstring [uuid]
Required
A unique identifier for the entity.
Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
namestring
Name given to identify the ad draft.
Example: "New Ad Draft"
advertiser_namestring
Name of the advertiser for the ad draft.
Example: "Heart Dance Recordings"
Assets for the ad.
- asset_idstring [uuid]
  Required
  A unique identifier for an AUDIO, VIDEO or IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- companion_asset_idstring [uuid]
  A unique identifier for an IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- logo_asset_idstring [uuid]
  Required
  A unique identifier for an IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- canvas_asset_idstring [uuid]
  A unique identifier for an IMAGE or VIDEO asset with 9:16 aspect ratio.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
asset_formatstring
Format of the asset.
Allowed values: "AUDIO", "VIDEO", "IMAGE", "CATALOG"Example: "AUDIO"
taglinestring
Tagline to give listeners more context about your company or product. This will be displayed in the CTA card leavebehind.
Example: "Good Food for Good Dogs"
Array maximum length: 11
Third party viewability tracking via partner and url
- measurement_partnerstring
  Name of the third-party measurement partner.
  Allowed values: "IAS", "DCM", "UNSET"Example: "IAS"
- urlstring
  Third-party tracking URL.
  Example: "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"
The metadata for the behavior of the call-to-action button.
- keystring
  The identifier used for the call-to-action button. This will be translated using the locale.
  Allowed values: "APPLY_NOW", "BOOK_NOW", "BUY_NOW", "BUY_TICKETS", "CLICK_NOW", "DOWNLOAD", "FIND_STORES", "GET_COUPON", "GET_INFO", "LEARN_MORE", "LISTEN_NOW", "MORE_INFO", "ORDER_NOW", "PRE_SAVE", "SAVE_NOW", "SHARE", "SHOP_NOW", "SIGN_UP", "VISIT_PROFILE", "VISIT_SITE", "WATCH_NOW"Example: "LEARN_MORE"
- languagestring
  The language which the ad is presented.
  Allowed values: "ARABIC", "ARABIC_EGYPT", "BULGARIAN", "CHINESE", "CHINESE_HK", "CHINESE_TAIWAN", "CROATIAN", "CZECH", "DANISH", "DUTCH", "ENGLISH", "FINNISH", "FRENCH", "FRENCH_CANADA", "GERMAN", "GREEK", "HEBREW", "HUNGARIAN", "INDONESIAN", "ITALIAN", "JAPANESE", "KOREAN", "NORWEGIAN", "POLISH", "PORTUGUESE", "PORTUGUESE_PORTUGAL", "ROMANIAN", "RUSSIAN", "SLOVAK", "SPANISH", "SPANISH_ARGENTINA", "SPANISH_LATAM_CARIBBEAN", "SPANISH_MEXICO", "SWEDISH", "THAI", "TURKISH", "UKRAINIAN", "VIETNAMESE"Example: "ENGLISH"
- clickthrough_urlstring
  The link to the ads desired landing page.
  Example: "https://www.spotify.com"
placementsarray of strings
Placement of the ad.
Allowed values: "MUSIC", "PODCAST"Example: "MUSIC"
Catalog of things to be placed in a carousel type ad. Ad Set asset_format must be set to CATALOG.
- idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- namestring
  Name given to identify your catalog.
  Example: "Holiday Deals"
- Item within a catalog
  idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  asset_idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  Metadata associated with attached asset_id. Only present in response.
  asset_typestring
  The type of asset.
  Allowed values: "AUDIO", "IMAGE", "VIDEO"Example: "IMAGE"
  asset_namestring
  Name of attached assetId.
  Example: "File name"
  asset_urlstring [uri]
  URL associated with attached asset_id.
  Example: "https://example.com/asset_id"
  skustring
  Client defined product ID. Must be unique to a catalog.
  Example: "SKU-7415695"
  positioninteger
  Required
  Preferred ordering to display the catalog items in ads.
  Example: 3
  clickthrough_urlstring [uri]
  The link to the ads desired landing page.
  Example: "https://www.spotify.com"
  microinteger [int64]
  Price multiplied by x10 to the 6th power. Ex: cost of $250, would be a cost_micro of 250000000.
  Example: 250000000
  currency_codestring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
  display_pricestring
  Displayable localized price. Only present in response.
  Example: "$19.99 USD"
  microinteger [int64]
  Price multiplied by x10 to the 6th power. Ex: cost of $250, would be a cost_micro of 250000000.
  Example: 250000000
  currency_codestring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
  display_sale_pricestring
  Displayable localized sale price. Only present in response.
  Example: "$14.99 USD"
  taglinestring
  Tagline to give listeners more context about your company or product. This will be displayed in the CTA card leavebehind.
  Pattern: ^\S.*\S$Length between 2 and 40Example: "Good Food for Good Dogs"
dv_client_codestring
DoubleVerify client code.
Example: "2097467"
weightinteger [int32]
The weight of the ad.
Range: 1 - 100Example: 10

Response sample

{  "status": "PENDING",  "draft_hierarchy_version": 1,  "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",  "created_at": "2026-01-23T04:56:07Z",  "updated_at": "2026-01-23T04:56:07Z",  "ad_set_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",  "name": "New Ad Draft",  "advertiser_name": "Heart Dance Recordings",  "assets": {    "asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",    "companion_asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",    "logo_asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",    "canvas_asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"  },  "asset_format": "AUDIO",  "tagline": "Good Food for Good Dogs",  "third_party_tracking": [    {      "measurement_partner": "IAS",      "url": "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"    }  ],  "call_to_action": {    "key": "LEARN_MORE",    "language": "ENGLISH",    "clickthrough_url": "https://www.spotify.com"  },  "placements": ["MUSIC"],  "catalog": {    "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",    "name": "Holiday Deals",    "catalog_items": [      {        "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",        "asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",        "asset": {          "asset_type": "IMAGE",          "asset_name": "File name",          "asset_url": "https://example.com/asset_id"        },        "sku": "SKU-7415695",        "position": 3,        "clickthrough_url": "https://www.spotify.com",        "price": {          "micro": 250000000,          "currency_code": "USD"        },        "display_price": "$19.99 USD",        "sale_price": {          "micro": 250000000,          "currency_code": "USD"        },        "display_sale_price": "$14.99 USD",        "tagline": "Good Food for Good Dogs"      }    ]  },  "dv_client_code": "2097467",  "weight": 10}