Skip to content
Ads API •References / ads / Create an Ad

Create an Ad

Create a new Ad.

Request

  • ad_account_id
    string [uuid]
    Required

    A unique identifier for an Ad Account.

    Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a

Represents a create request.

  • advertiser_name
    string
    Required

    Name of the advertiser

    Length between 2 and 25Example: "Heart Dance Recordings"
  • Required

    Assets for the ad.

    • asset_id
      string [uuid]
      Required

      A unique identifier for an AUDIO, VIDEO or IMAGE asset.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • companion_asset_id
      string [uuid]

      A unique identifier for an IMAGE asset.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • logo_asset_id
      string [uuid]
      Required

      A unique identifier for an IMAGE asset.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • canvas_asset_id
      string [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"
  • name
    string
    Required

    Name given to identify the ad.

    Length between 2 and 200Example: "New Ad"
  • start_time
    string [date-time]

    Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

    Example: "2023-09-23T04:56:07Z"
  • end_time
    string [date-time]

    Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

    Example: "2023-09-23T04:56:07Z"
  • tagline
    string
    Required

    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"
  • Array maximum length: 11

    Third party viewability tracking via partner and url

    • measurement_partner
      string

      Name of the third-party measurement partner.

      Allowed values: "IAS", "DCM", "UNSET"Example: "IAS"
    • url
      string

      Third-party tracking URL.

      Example: "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"
  • ad_set_id
    string [uuid]
    Required

    A unique identifier for the entity.

    Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  • Required

    The metadata for the behavior of the call-to-action button.

    • key
      string

      The identifier used for the call-to-action button. This will be translated using the locale.

      Default: "LEARN_MORE"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"
    • language
      string

      The language which the ad is presented.

      Default: "ENGLISH"Allowed values: "ENGLISH", "FRENCH", "GERMAN", "ITALIAN", "PORTUGUESE", "SPANISH", "DANISH", "DUTCH", "FINNISH", "NORWEGIAN", "SWEDISH", "JAPANESE"Example: "ENGLISH"
    • clickthrough_url
      string

      The link to the ads desired landing page.

      Example: "https://www.spotify.com"
  • delivery
    string

    Toggles the delivery of the entity ON or OFF. Cannot be set in Ad Set PATCH request alongside other fields (delivery must be the only field present).

    Default: "ON"Allowed values: "ON", "OFF"Supported content-type(s): Example: "ON"

Response

Ad response.

  • id
    string [uuid]

    A unique identifier for the entity.

    Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"

  • The metadata for the behavior of the call-to-action button.

    • key
      string

      The identifier used for the call-to-action button. This will be translated using the locale.

      Example: "LEARN_MORE"
    • text
      string

      The post-translation text used for the call-to-action-button-text

      Example: "Learn more"
    • language
      string
    • clickthrough_url
      string
      Required

      The link to the ads desired landing page.

      Example: "https://www.spotify.com"
  • created_at
    string [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_at
    string [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"
  • start_time
    string [date-time]

    Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

    Example: "2023-09-23T04:56:07Z"
  • end_time
    string [date-time]

    Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

    Example: "2023-09-23T04:56:07Z"
  • delivery
    string

    Toggles the delivery of the entity ON or OFF.

    Allowed values: "ON", "OFF"Example: "ON"
  • ad_set_id
    string [uuid]

    A unique identifier for the entity.

    Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  • status
    string

    Status of the ad.

    Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING", "PENDING_APPROVAL", "REJECTED", "UNRECOGNIZED"Example: "PENDING"
  • reject_reason
    string

    Reason the ad has been put into the REJECTED state (if applicable).

    Example: "Your ad wasn’t approved. Create a new ad, or contact us at adstudio@spotify.com."

  • Rejection and remediation information and keys.

    Rejection and remediation text and keys.

    • rejection
      string

      Rejection reason.

      Example: "Clickthrough URL doesn't work"
    • rejection_key
      string

      Rejection reason key.

      Example: "AD_POLICY_VIOLATION_REJECTION"
    • remediation
      string

      Remediation information.

      Example: "Submit a new ad with an updated clickthrough URL."
    • remediation_key
      string

      Remediation key.

      Example: "AD_POLICY_VIOLATION_REMEDIATION"
  • ad_preview_url
    string [uri]

    Preview url of an ad.

    Example: "https://www.adstudio.spotify.com/preview/8ae1f562-1b4e-11ee-be56-0242ac120002"
  • advertiser_name
    string

    Name of the advertiser

    Length between 2 and 25Example: "Heart Dance Recordings"

  • Assets for the ad.

    • asset_id
      string [uuid]
      Required

      A unique identifier for an AUDIO, VIDEO or IMAGE asset.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • companion_asset_id
      string [uuid]
      Required

      A unique identifier for an IMAGE asset.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • logo_asset_id
      string [uuid]
      Required

      A unique identifier for an IMAGE asset.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • canvas_asset_id
      string [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"
  • name
    string

    Name given to identify the ad.

    Length between 2 and 200Example: "New Ad"
  • tagline
    string

    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"
  • Array maximum length: 11

    Third party viewability tracking via partner and url

    • measurement_partner
      string

      Name of the third-party measurement partner.

      Allowed values: "IAS", "DCM", "UNSET"Example: "IAS"
    • url
      string

      Third-party tracking URL.

      Example: "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"

Response sample