openapi: 3.1.0
info:
  title: Brand Ads API
  version: v11
  description: "Manage content used to refer traffic from a partner to your properties. \nThis includes plain text links, banners, and coupons, along with their associated deals and promotional themes.\n"
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/Ads:
    post:
      operationId: createAd
      tags:
      - Ads
      summary: Create an ad
      description: "Creates a new ad. Note that for impact.com hosted creative assets, multipart/form-data is required. \nOnly Banner, Coupon, and Text Link ads can be created via API.\n"
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - Name
              - CampaignId
              - AdType
              - Language
              properties:
                Name:
                  type: string
                  example: Summer Sale 2020 250x250
                CampaignId:
                  type: string
                  example: '1000'
                AdType:
                  type: string
                  enum:
                  - BANNER
                  - COUPON
                  - TEXT_LINK
                  example: BANNER
                CustomAdServingUrl:
                  type: string
                AdCodeTemplate:
                  type: string
                CouponLinkName:
                  type: string
                CouponAllowCustomPromoCode:
                  type: boolean
                  description: Whether the ad allows partners to use a custom promo code (instead of the default coupon code).
                  example: false
                CustomisationCharge:
                  type: number
                  format: decimal
                  description: The charge applied when partners customise this ad.
                  example: 0.0
                LinkText:
                  type: string
                Language:
                  type: string
                  example: ENGLISH
                  description: 'The language of the ad creative. Possible values: `AFRIKAANS`, `ARABIC`, `BULGARIAN`, `CHINESE`, `CHINESE_TRADITIONAL`, `CZECH`, `DANISH`, `DUTCH`, `ENGLISH`, `ENGLISH_GB`, `ENGLISH_AU`, `ENGLISH_CA`, `ENGLISH_NZ`, `ENGLISH_ZA`, `ESTONIAN`, `FILIPINO`, `FINNISH`, `FRENCH`, `FRENCH_CA`, `GERMAN`, `HEBREW`, `HINDI`, `INDONESIAN`, `ITALIAN`, `JAPANESE`, `KOREAN`, `LATVIAN`, `LITHUANIAN`, `MALAY`, `MALTESE`, `NORWEGIAN`, `PORTUGUESE`, `PORTUGUESE_BR`, `POLISH`, `RUSSIAN`, `SLOVENIAN`, `SPANISH`, `SPANISH_MX`, `SWEDISH`, `THAI`, `TURKISH`, `VIETNAMESE`.'
                Description:
                  type: string
                  example: Our best deals this summer creative.
                LandingPage:
                  type: string
                  example: http://www.test.com/6234652
                MobileFallbacks.ANDROID:
                  type: string
                MobileFallbacks.IOS:
                  type: string
                IabAdUnit:
                  type: string
                  example: CUSTOM
                ThirdPartyServableAdCreativeHeight:
                  type: string
                  example: '250'
                ThirdPartyServableAdCreativeWidth:
                  type: string
                  example: '250'
                BannerAlternativeTag:
                  type: string
                  example: summersale
                GetHtmlCodeType:
                  type: string
                  enum:
                  - HTML_AND_IFRAME
                  - IFRAME_ONLY
                  example: HTML_AND_IFRAME
                Labels:
                  type: string
                  example: sale,US
                AllowDeepLinking:
                  type: string
                  example: 'true'
                LimitedTimeStartDate:
                  type: string
                  format: date-time
                  example: '2026-09-16T17:01:28-07:00'
                LimitedTimeEndDate:
                  type: string
                  format: date-time
                  example: '2026-12-31T23:59:59-07:00'
                Season:
                  type: string
                  example: SUMMER
                  description: 'If the ad has a seasonal promotional theme, this is the season the ad targets. Possible values: `ANZAC_DAY`, `AUGUST_CIVIC_HOLIDAY`, `AUSTRALIA_DAY`, `BACK_TO_SCHOOL`, `BLACK_FRIDAY`, `BOXING_DAY`, `CANADA_DAY`, `CYBER_MONDAY`, `END_OF_FINANCIAL_YEAR`, `FAMILY_DAY`, `FATHERS_DAY`, `GOOD_FRIDAY`, `HALLOWEEN`, `HANUKKAH`, `INDEPENDANCE_DAY`, `LABOR_DAY`, `MEMORIAL_DAY`, `MOTHERS_DAY`, `NEW_YEAR`, `PRESIDENTS_DAY`, `QUEENS_BIRTHDAY`, `REMEMBRANCE_DAY`, `SPRING`, `ST_PATRICKS_DAY`, `SUMMER`, `THANKSGIVING`, `VALENTINES_DAY`, `VICTORIA_DAY`, `WAITANGI_DAY`, `WINTER`, `OTHER`.'
      responses:
        '200':
          description: Success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
    get:
      operationId: listAds
      tags:
      - Ads
      summary: List all ads
      description: Returns an array of ad objects, ordered by creation date (newest first).
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: CampaignId
        in: query
        description: Filter ads by a specific campaign (program) ID.
        schema:
          type: string
      - name: Type
        in: query
        description: Filter ads by their type.
        schema:
          type: string
          enum:
          - BANNER
          - TEXT_LINK
          - COUPON
      - name: DealId
        in: query
        description: Filter ads associated with a specific deal ID.
        schema:
          type: string
      - name: MobileReady
        in: query
        description: Filter ads based on whether they are optimized for mobile.
        schema:
          type: boolean
      responses:
        '200':
          description: A list of ads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@page':
                    type: string
                  Ads:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ad'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Ads/{Id}:
    get:
      operationId: getAd
      tags:
      - Ads
      summary: Retrieve an ad
      description: Retrieves the details of an existing ad using its unique impact.com Ad Id.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: Id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns an ad object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads/{Id}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    put:
      operationId: updateAd
      tags:
      - Ads
      summary: Update an ad
      description: Updates an existing ad with the provided parameters.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: Id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                Name:
                  type: string
                  example: Summer Sale 2020 250x250
                Description:
                  type: string
                  example: Our best deals this summer creative.
                Labels:
                  type: string
                  example: sale,US
                AllowDeepLinking:
                  type: string
                  example: 'true'
                LandingPage:
                  type: string
                  example: http://www.test.com/6234652
                Language:
                  type: string
                  example: ENGLISH
                  description: 'The language of the ad creative. Possible values: `AFRIKAANS`, `ARABIC`, `BULGARIAN`, `CHINESE`, `CHINESE_TRADITIONAL`, `CZECH`, `DANISH`, `DUTCH`, `ENGLISH`, `ENGLISH_GB`, `ENGLISH_AU`, `ENGLISH_CA`, `ENGLISH_NZ`, `ENGLISH_ZA`, `ESTONIAN`, `FILIPINO`, `FINNISH`, `FRENCH`, `FRENCH_CA`, `GERMAN`, `HEBREW`, `HINDI`, `INDONESIAN`, `ITALIAN`, `JAPANESE`, `KOREAN`, `LATVIAN`, `LITHUANIAN`, `MALAY`, `MALTESE`, `NORWEGIAN`, `PORTUGUESE`, `PORTUGUESE_BR`, `POLISH`, `RUSSIAN`, `SLOVENIAN`, `SPANISH`, `SPANISH_MX`, `SWEDISH`, `THAI`, `TURKISH`, `VIETNAMESE`.'
                LimitedTimeStartDate:
                  type: string
                  format: date-time
                  example: '2026-09-16T17:01:28-07:00'
                LimitedTimeEndDate:
                  type: string
                  format: date-time
                  example: '2026-12-31T23:59:59-07:00'
                BannerAlternativeTag:
                  type: string
                  example: summersale
                CustomAdServingUrl:
                  type: string
                DealId:
                  type: string
                CouponAllowCustomPromoCode:
                  type: boolean
                  description: Whether the ad allows partners to use a custom promo code (instead of the default coupon code).
                  example: false
                CustomisationCharge:
                  type: number
                  format: decimal
                  description: The charge applied when partners customise this ad.
                  example: 0.0
                Season:
                  type: string
                  description: 'If the ad has a seasonal promotional theme, this is the season the ad targets. Possible values: `ANZAC_DAY`, `AUGUST_CIVIC_HOLIDAY`, `AUSTRALIA_DAY`, `BACK_TO_SCHOOL`, `BLACK_FRIDAY`, `BOXING_DAY`, `CANADA_DAY`, `CYBER_MONDAY`, `END_OF_FINANCIAL_YEAR`, `FAMILY_DAY`, `FATHERS_DAY`, `GOOD_FRIDAY`, `HALLOWEEN`, `HANUKKAH`, `INDEPENDANCE_DAY`, `LABOR_DAY`, `MEMORIAL_DAY`, `MOTHERS_DAY`, `NEW_YEAR`, `PRESIDENTS_DAY`, `QUEENS_BIRTHDAY`, `REMEMBRANCE_DAY`, `SPRING`, `ST_PATRICKS_DAY`, `SUMMER`, `THANKSGIVING`, `VALENTINES_DAY`, `VICTORIA_DAY`, `WAITANGI_DAY`, `WINTER`, `OTHER`.'
                  example: SUMMER
      responses:
        '200':
          description: Success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request PUT \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads/{Id}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
  schemas:
    Ad:
      type: object
      properties:
        Id:
          type: string
          example: '892081'
        Name:
          type: string
          example: Summer Sale 2020 250x250
        Description:
          type: string
          example: Our best deals this summer creative.
        CampaignId:
          type: string
          example: '1000'
        CampaignName:
          type: string
          example: Acme Campaign
        AdType:
          type: string
          enum:
          - BANNER
          - TEXT_LINK
          - COUPON
          example: BANNER
        LandingPage:
          type: string
          example: http://www.test.com/6234652
        MobileFallbacks:
          type: object
          properties:
            ANDROID:
              type: string
            IOS:
              type: string
        CustomAdServingUrl:
          type: string
          example: ''
        IabAdUnit:
          type: string
          example: CUSTOM
        ThirdPartyServableAdCreativeHeight:
          type: string
          example: '250'
        ThirdPartyServableAdCreativeWidth:
          type: string
          example: '250'
        BannerAlternativeTag:
          type: string
          example: summersale
        LinkText:
          type: string
          example: ''
        CouponLinkName:
          type: string
        GetHtmlCodeType:
          type: string
          example: HTML_AND_IFRAME
        Labels:
          type: string
          example: sale,US
        AllowDeepLinking:
          type: string
          example: 'true'
        Language:
          type: string
          example: ENGLISH
          description: 'The language of the ad creative. Possible values: `AFRIKAANS`, `ARABIC`, `BULGARIAN`, `CHINESE`, `CHINESE_TRADITIONAL`, `CZECH`, `DANISH`, `DUTCH`, `ENGLISH`, `ENGLISH_GB`, `ENGLISH_AU`, `ENGLISH_CA`, `ENGLISH_NZ`, `ENGLISH_ZA`, `ESTONIAN`, `FILIPINO`, `FINNISH`, `FRENCH`, `FRENCH_CA`, `GERMAN`, `HEBREW`, `HINDI`, `INDONESIAN`, `ITALIAN`, `JAPANESE`, `KOREAN`, `LATVIAN`, `LITHUANIAN`, `MALAY`, `MALTESE`, `NORWEGIAN`, `PORTUGUESE`, `PORTUGUESE_BR`, `POLISH`, `RUSSIAN`, `SLOVENIAN`, `SPANISH`, `SPANISH_MX`, `SWEDISH`, `THAI`, `TURKISH`, `VIETNAMESE`.'
        LimitedTimeStartDate:
          type: string
          format: date-time
          example: '2020-09-16T17:01:28-07:00'
        LimitedTimeEndDate:
          type: string
          format: date-time
          example: ''
        Season:
          type: string
          example: SUMMER
          description: 'If the ad has a seasonal promotional theme, this is the season the ad targets. Possible values: `ANZAC_DAY`, `AUGUST_CIVIC_HOLIDAY`, `AUSTRALIA_DAY`, `BACK_TO_SCHOOL`, `BLACK_FRIDAY`, `BOXING_DAY`, `CANADA_DAY`, `CYBER_MONDAY`, `END_OF_FINANCIAL_YEAR`, `FAMILY_DAY`, `FATHERS_DAY`, `GOOD_FRIDAY`, `HALLOWEEN`, `HANUKKAH`, `INDEPENDANCE_DAY`, `LABOR_DAY`, `MEMORIAL_DAY`, `MOTHERS_DAY`, `NEW_YEAR`, `PRESIDENTS_DAY`, `QUEENS_BIRTHDAY`, `REMEMBRANCE_DAY`, `SPRING`, `ST_PATRICKS_DAY`, `SUMMER`, `THANKSGIVING`, `VALENTINES_DAY`, `VICTORIA_DAY`, `WAITANGI_DAY`, `WINTER`, `OTHER`.'
        DealId:
          type: string
          example: '85433'
        DealName:
          type: string
          example: Summer Sale 2020
        DateCreated:
          type: string
          format: date-time
        DateLastUpdated:
          type: string
          format: date-time
        AdCodeTemplate:
          type: string
        CouponAllowCustomPromoCode:
          type: string
        CustomisationCharge:
          type: string
        MobileReady:
          type: string
        PhoneTracking:
          type: string
        PromoCodeTracking:
          type: string
        TopSeller:
          type: string
        RestrictedMediaPartners:
          type: array
          items:
            type: string
        RestrictedMediaPartnerGroups:
          type: array
          items:
            type: string
        DealDescription:
          type: string
        DealState:
          type: string
        DealType:
          type: string
        DealScope:
          type: string
        DealProducts:
          type: array
          items:
            type: string
        DealCategories:
          type: string
        DiscountType:
          type: string
        DiscountAmount:
          type: string
        DiscountCurrency:
          type: string
        DiscountPercent:
          type: string
        DiscountMaximumPercent:
          type: string
        DiscountPercentRangeStart:
          type: string
        DiscountPercentRangeEnd:
          type: string
        Gift:
          type: string
        RebateAmount:
          type: string
        RebateCurrency:
          type: string
        DealDefaultPromoCode:
          type: string
        MinimumPurchaseAmount:
          type: string
        MinimumPurchaseAmountCurrency:
          type: string
        MaximumSavingsAmount:
          type: string
        MaximumSavingsCurrency:
          type: string
        BogoBuyQuantity:
          type: string
        BogoBuyScope:
          type: string
        BogoBuyName:
          type: string
        BogoBuyImageUrl:
          type: string
        BogoGetQuantity:
          type: string
        BogoGetScope:
          type: string
        BogoGetDiscountType:
          type: string
        BogoGetName:
          type: string
        BogoGetImageUrl:
          type: string
        BogoGetDiscountAmount:
          type: string
        BogoGetDiscountCurrency:
          type: string
        BogoGetDiscountPercent:
          type: string
        PurchaseLimitQuantity:
          type: string
        DealStartDate:
          type: string
          format: date-time
        DealEndDate:
          type: string
          format: date-time
        SynchAdsPromoCodes:
          type: string
        DealRestrictedMediaPartners:
          type: array
          items:
            type: string
        DealRestrictedMediaPartnerGroups:
          type: array
          items:
            type: string
        Uri:
          type: string
          format: uri-reference
          example: /Advertisers/{AccountSID}/Ads/892081
    AdResponse:
      type: object
      properties:
        Status:
          type: string
        Uri:
          type: string
          format: uri-reference
x-default-client: cURL
