openapi: 3.1.0
info:
  title: Brand API - Ads
  description: >-
    API for managing ads, which represent the creative content used to refer
    traffic from a partner to one of your properties. This includes creating,
    retrieving, updating, and listing ads such as banners, text links, and
    coupons.
  version: v12
  x-gitbook-description-document:
    object: document
    data:
      schemaVersion: 9
    nodes:
    - object: block
      type: paragraph
      isVoid: false
      data: {}
      nodes:
      - object: text
        leaves:
        - object: leaf
          text: >-
            API for managing ads, which represent the creative content
            used to refer traffic from a partner to one of your
            properties. This includes creating, retrieving, updating, and
            listing ads such as banners, text links, and coupons.
          marks: []
        key: Aae66TBWS8Xe
      key: 8Z2v9L4MpFdw
    key: e2uDp2STMEXa
  x-gitbook-description-html: >-
    <p>API for managing ads, which represent the creative content used to refer
    traffic from a partner to one of your properties. This includes creating,
    retrieving, updating, and listing ads such as banners, text links, and
    coupons.</p>
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/Ads:
    get:
      summary: List All Ads
      description: >-
        Lists existing ads, returned by creation date with the most recently
        created ad appearing first. The list can be filtered by various
        parameters.
      operationId: listAds
      tags:
      - Ads
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: CampaignId
        in: query
        schema:
          type: string
        description: Filter ads by a specific campaign (program) ID.
        x-gitbook-description-html: <p>Filter ads by a specific campaign (program) ID.</p>
      - name: Type
        in: query
        schema:
          type: string
          enum:
          - BANNER
          - TEXT_LINK
          - COUPON
        description: Filter ads by their type.
        x-gitbook-description-html: <p>Filter ads by their type.</p>
      - name: DealId
        in: query
        schema:
          type: string
        description: Filter ads associated with a specific deal ID.
        x-gitbook-description-html: <p>Filter ads associated with a specific deal ID.</p>
      - name: MobileReady
        in: query
        schema:
          type: boolean
        description: Filter ads based on whether they are optimized for mobile.
        x-gitbook-description-html: <p>Filter ads based on whether they are optimized for mobile.</p>
      - name: DateCreatedStart
        in: query
        schema:
          type: string
          format: date-time
        description: Start of the date range for when ads were created.
        x-gitbook-description-html: <p>Start of the date range for when ads were created.</p>
      - name: DateCreatedEnd
        in: query
        schema:
          type: string
          format: date-time
        description: End of the date range for when ads were created.
        x-gitbook-description-html: <p>End of the date range for when ads were created.</p>
      - name: DateLastUpdatedStart
        in: query
        schema:
          type: string
          format: date-time
        description: Start of the date range for when ads were last updated.
        x-gitbook-description-html: <p>Start of the date range for when ads were last updated.</p>
      - name: DateLastUpdatedEnd
        in: query
        schema:
          type: string
          format: date-time
        description: End of the date range for when ads were last updated.
        x-gitbook-description-html: <p>End of the date range for when ads were last updated.</p>
      responses:
        '200':
          description: A paginated list of ad objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@page':
                    type: string
                  Ads:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ad'
          x-gitbook-description-html: <p>A paginated list of ad objects.</p>
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
          - object: text
            leaves:
            - object: leaf
              text: >-
                Lists existing ads, returned by creation date with the
                most recently created ad appearing first. The list can be
                filtered by various parameters.
              marks: []
            key: NXP45X3oZsEt
          key: KJ5WT1PiqdgH
        key: yElVLxDev0lR
      x-gitbook-description-html: >-
        <p>Lists existing ads, returned by creation date with the most recently
        created ad appearing first. The list can be filtered by various
        parameters.</p>
    post:
      summary: Create an Ad
      description: >-
        Creates a new Banner, Coupon, or Text Link ad. Use `multipart/form-data`
        if uploading a creative file, otherwise use
        `application/x-www-form-urlencoded`.
      operationId: createAd
      tags:
      - Ads
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: The details of the ad to create.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AdCreateUpdate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AdCreateUpdate'
        x-gitbook-description-html: <p>The details of the ad to create.</p>
      responses:
        '200':
          description: The ad was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: OK
                  Uri:
                    type: string
                    format: uri-reference
                    example: /Advertisers/{AccountSID}/Ads/600000
          x-gitbook-description-html: <p>The ad was created successfully.</p>
      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: */*'
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
          - object: text
            leaves:
            - object: leaf
              text: 'Creates a new Banner, Coupon, or Text Link ad. Use '
              marks: []
            - object: leaf
              text: multipart/form-data
              marks:
              - object: mark
                type: code
                data: {}
            - object: leaf
              text: ' if uploading a creative file, otherwise use '
              marks: []
            - object: leaf
              text: application/x-www-form-urlencoded
              marks:
              - object: mark
                type: code
                data: {}
            - object: leaf
              text: .
              marks: []
            key: IdFMfQ5Z7mua
          key: 66gEc08i4cME
        key: rBju5TmoEGIq
      x-gitbook-description-html: >-
        <p>Creates a new Banner, Coupon, or Text Link ad. Use
        <code>multipart/form-data</code> if uploading a creative file, otherwise
        use <code>application/x-www-form-urlencoded</code>.</p>
  /Advertisers/{AccountSID}/Ads/{AdId}:
    get:
      summary: Get Ad Details
      description: Retrieves the details of an existing ad by its unique impact.com Ad ID.
      operationId: getAdById
      tags:
      - Ads
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: AdId
        in: path
        required: true
        description: The unique identifier for the ad.
        schema:
          type: string
        x-gitbook-description-html: <p>The unique identifier for the ad.</p>
      responses:
        '200':
          description: An ad object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
          x-gitbook-description-html: <p>An ad object.</p>
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads/{AdId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
          - object: text
            leaves:
            - object: leaf
              text: >-
                Retrieves the details of an existing ad by its unique
                impact.com Ad ID.
              marks: []
            key: pOlrtxjbsRSv
          key: J1X3PYnxsMOj
        key: 5W27kYBZ4b60
      x-gitbook-description-html: >-
        <p>Retrieves the details of an existing ad by its unique impact.com Ad
        ID.</p>
    put:
      summary: Update an Ad
      description: >-
        Updates an existing ad, including its creative file if needed. Use
        `multipart/form-data` if uploading a creative file.
      operationId: updateAd
      tags:
      - Ads
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: AdId
        in: path
        required: true
        description: The unique identifier for the ad to update.
        schema:
          type: string
        x-gitbook-description-html: <p>The unique identifier for the ad to update.</p>
      requestBody:
        description: The ad properties to update.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AdCreateUpdate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AdCreateUpdate'
        x-gitbook-description-html: <p>The ad properties to update.</p>
      responses:
        '200':
          description: The ad was updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: OK
                  Uri:
                    type: string
                    format: uri-reference
                    example: /Advertisers/{AccountSID}/Ads/892081
          x-gitbook-description-html: <p>The ad was updated successfully.</p>
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request PUT \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads/{AdId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
          - object: text
            leaves:
            - object: leaf
              text: >-
                Updates an existing ad, including its creative file if
                needed. Use 
              marks: []
            - object: leaf
              text: multipart/form-data
              marks:
              - object: mark
                type: code
                data: {}
            - object: leaf
              text: ' if uploading a creative file.'
              marks: []
            key: bxYgg1dNn7rn
          key: dMeqJxlkKdXK
        key: 4u4cYwxrMTpR
      x-gitbook-description-html: >-
        <p>Updates an existing ad, including its creative file if needed. Use
        <code>multipart/form-data</code> if uploading a creative file.</p>
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
      x-gitbook-description-html: >-
        <p>Use your AccountSID as the username and AuthToken as the
        password.</p>
  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
          format: uri
          example: http://www.test.com/6234652
        MobileFallbacks:
          type: object
          properties:
            Android:
              type: string
              description: The SystemAppId of the Android mobile app.
              x-gitbook-description-html: <p>The SystemAppId of the Android mobile app.</p>
            IOS:
              type: string
              description: The SystemAppId of the iOS mobile app.
              x-gitbook-description-html: <p>The SystemAppId of the iOS mobile app.</p>
        DateCreated:
          type: string
          format: date-time
          example: '2024-02-29T22:03:35-08:00'
        DateLastUpdated:
          type: string
          format: date-time
          example: '2024-02-29T22:03:35-08:00'
        CustomAdServingUrl:
          type: string
          format: uri
          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
          enum:
          - HTML_AND_IFRAME
          - IFRAME_ONLY
          example: HTML_AND_IFRAME
        Labels:
          type: string
          description: Comma-separated key terms.
          example: sale,US
          x-gitbook-description-html: <p>Comma-separated key terms.</p>
        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: ''
        RestrictedMediaPartners:
          type: array
          items:
            type: string
        RestrictedMediaPartnerGroups:
          type: array
          items:
            type: string
        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`.'
        Uri:
          type: string
          format: uri-reference
          example: /Advertisers/{AccountSID}/Ads/892081
        DealId:
          type: string
          example: '85433'
        DealName:
          type: string
          example: Summer Sale 2020
        AdCodeTemplate:
          type: string
        CouponAllowCustomPromoCode:
          type: string
        CustomisationCharge:
          type: string
        MobileReady:
          type: string
        PhoneTracking:
          type: string
        PromoCodeTracking:
          type: string
        TopSeller:
          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
    AdCreateUpdate:
      type: object
      description: >-
        Schema for creating and updating an Ad. Some fields are conditionally
        required based on AdType.
      properties:
        Name:
          type: string
          example: Summer Sale 2020 250x250
        CampaignId:
          type: string
          example: '1000'
        AdType:
          type: string
          enum:
          - BANNER
          - TEXT_LINK
          - COUPON
          example: BANNER
        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
          format: uri
          example: http://www.test.com/6234652
        CustomAdServingUrl:
          type: string
          format: uri
          description: >-
            Required for BANNER if not using AdCodeTemplate or
            BannerCreativeFile.
          x-gitbook-description-html: >-
            <p>Required for BANNER if not using AdCodeTemplate or
            BannerCreativeFile.</p>
        AdCodeTemplate:
          type: string
          description: >-
            Required for BANNER if not using CustomAdServingUrl or
            BannerCreativeFile.
          x-gitbook-description-html: >-
            <p>Required for BANNER if not using CustomAdServingUrl or
            BannerCreativeFile.</p>
        BannerCreativeFile:
          type: string
          format: binary
          description: Creative file for a BANNER ad. Use multipart/form-data.
          x-gitbook-description-html: <p>Creative file for a BANNER ad. Use multipart/form-data.</p>
        CouponLinkName:
          type: string
          description: Required for COUPON ad type.
          x-gitbook-description-html: <p>Required for COUPON ad type.</p>
        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
          description: Required for TEXT_LINK ad type.
          x-gitbook-description-html: <p>Required for TEXT_LINK ad type.</p>
        IabAdUnit:
          type: string
          example: CUSTOM
        ThirdPartyServableAdCreativeHeight:
          type: string
          example: '250'
        ThirdPartyServableAdCreativeWidth:
          type: string
          example: '250'
        BannerAlternativeTag:
          type: string
          description: Only for BANNER ad type.
          x-gitbook-description-html: <p>Only for BANNER ad type.</p>
          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'
        TargetMediaPartners:
          type: array
          items:
            type: string
          description: Array of partner IDs to restrict the ad to.
          x-gitbook-description-html: <p>Array of partner IDs to restrict the ad to.</p>
        TargetMediaPartnerGroups:
          type: array
          items:
            type: string
          description: Array of partner group IDs to restrict the ad to.
          x-gitbook-description-html: <p>Array of partner group IDs to restrict the ad to.</p>
        MobileFallbacks:
          type: object
          properties:
            Android:
              type: string
            IOS:
              type: string
        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`.'
        MobileReady:
          type: string
          example: 'true'
        PhoneTracking:
          type: string
          example: 'false'
        PromoCodeTracking:
          type: string
          example: 'false'
        TopSeller:
          type: string
          example: 'false'
        DealId:
          type: string
      x-gitbook-description-html: >-
        <p>Schema for creating and updating an Ad. Some fields are conditionally
        required based on AdType.</p>
x-default-client: cURL
