Ads | Brand API Reference v12

List All Ads

get

Lists existing ads, returned by creation date with the most recently created ad appearing first. The list can be filtered by various parameters.

Authorizations

AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters

AccountSIDstringRequired

Query parameters

CampaignIdstringOptional

Filter ads by a specific campaign (program) ID.

Typestring · enumOptional

Filter ads by their type.

Possible values:

DealIdstringOptional

Filter ads associated with a specific deal ID.

MobileReadybooleanOptional

Filter ads based on whether they are optimized for mobile.

DateCreatedStartstring · date-timeOptional

Start of the date range for when ads were created.

DateCreatedEndstring · date-timeOptional

End of the date range for when ads were created.

DateLastUpdatedStartstring · date-timeOptional

Start of the date range for when ads were last updated.

DateLastUpdatedEndstring · date-timeOptional

End of the date range for when ads were last updated.

Responses

200

A paginated list of ad objects.

application/json

@pagestringOptional

get/Advertisers/{AccountSID}/Ads

cURL

curl -L \
  --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads' \
  --user '{AccountSID}:{AuthToken}' \
  --header 'Accept: */*'

200

A paginated list of ad objects.

{
  "@page": "text",
  "Ads": [
    {
      "Id": "892081",
      "Name": "Summer Sale 2020 250x250",
      "Description": "Our best deals this summer creative.",
      "CampaignId": "1000",
      "CampaignName": "Acme Campaign",
      "AdType": "BANNER",
      "LandingPage": "http://www.test.com/6234652",
      "MobileFallbacks": {
        "Android": "text",
        "IOS": "text"
      },
      "DateCreated": "2024-02-29T22:03:35-08:00",
      "DateLastUpdated": "2024-02-29T22:03:35-08:00",
      "CustomAdServingUrl": "",
      "IabAdUnit": "CUSTOM",
      "ThirdPartyServableAdCreativeHeight": "250",
      "ThirdPartyServableAdCreativeWidth": "250",
      "BannerAlternativeTag": "summersale",
      "LinkText": "",
      "CouponLinkName": "text",
      "GetHtmlCodeType": "HTML_AND_IFRAME",
      "Labels": "sale,US",
      "AllowDeepLinking": "true",
      "Language": "ENGLISH",
      "LimitedTimeStartDate": "2020-09-16T17:01:28-07:00",
      "LimitedTimeEndDate": "",
      "RestrictedMediaPartners": [
        "text"
      ],
      "RestrictedMediaPartnerGroups": [
        "text"
      ],
      "Season": "SUMMER",
      "Uri": "/Advertisers/{AccountSID}/Ads/892081",
      "DealId": "85433",
      "DealName": "Summer Sale 2020",
      "AdCodeTemplate": "text",
      "CouponAllowCustomPromoCode": "text",
      "CustomisationCharge": "text",
      "MobileReady": "text",
      "PhoneTracking": "text",
      "PromoCodeTracking": "text",
      "TopSeller": "text",
      "DealDescription": "text",
      "DealState": "text",
      "DealType": "text",
      "DealScope": "text",
      "DealProducts": [
        "text"
      ],
      "DealCategories": "text",
      "DiscountType": "text",
      "DiscountAmount": "text",
      "DiscountCurrency": "text",
      "DiscountPercent": "text",
      "DiscountMaximumPercent": "text",
      "DiscountPercentRangeStart": "text",
      "DiscountPercentRangeEnd": "text",
      "Gift": "text",
      "RebateAmount": "text",
      "RebateCurrency": "text",
      "DealDefaultPromoCode": "text",
      "MinimumPurchaseAmount": "text",
      "MinimumPurchaseAmountCurrency": "text",
      "MaximumSavingsAmount": "text",
      "MaximumSavingsCurrency": "text",
      "BogoBuyQuantity": "text",
      "BogoBuyScope": "text",
      "BogoBuyName": "text",
      "BogoBuyImageUrl": "text",
      "BogoGetQuantity": "text",
      "BogoGetScope": "text",
      "BogoGetDiscountType": "text",
      "BogoGetName": "text",
      "BogoGetImageUrl": "text",
      "BogoGetDiscountAmount": "text",
      "BogoGetDiscountCurrency": "text",
      "BogoGetDiscountPercent": "text",
      "PurchaseLimitQuantity": "text",
      "DealStartDate": "2026-07-16T11:03:58.812Z",
      "DealEndDate": "2026-07-16T11:03:58.812Z",
      "SynchAdsPromoCodes": "text",
      "DealRestrictedMediaPartners": [
        "text"
      ],
      "DealRestrictedMediaPartnerGroups": [
        "text"
      ]
    }
  ]
}

Create an Ad

post

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.

Authorizations

AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters

AccountSIDstringRequired

Body

Schema for creating and updating an Ad. Some fields are conditionally required based on AdType.

NamestringOptionalExample: Summer Sale 2020 250x250

CampaignIdstringOptionalExample: 1000

AdTypestring · enumOptionalExample: BANNERPossible values:

LanguagestringOptional

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.

Example: ENGLISH

DescriptionstringOptionalExample: Our best deals this summer creative.

LandingPagestring · uriOptionalExample: http://www.test.com/6234652

CustomAdServingUrlstring · uriOptional

Required for BANNER if not using AdCodeTemplate or BannerCreativeFile.

AdCodeTemplatestringOptional

Required for BANNER if not using CustomAdServingUrl or BannerCreativeFile.

BannerCreativeFilestring · binaryOptional

Creative file for a BANNER ad. Use multipart/form-data.

CouponLinkNamestringOptional

Required for COUPON ad type.

CouponAllowCustomPromoCodebooleanOptional

Whether the ad allows partners to use a custom promo code (instead of the default coupon code).

Example: false

CustomisationChargenumber · decimalOptional

The charge applied when partners customise this ad.

Example: 0

LinkTextstringOptional

Required for TEXT_LINK ad type.

IabAdUnitstringOptionalExample: CUSTOM

ThirdPartyServableAdCreativeHeightstringOptionalExample: 250

ThirdPartyServableAdCreativeWidthstringOptionalExample: 250

BannerAlternativeTagstringOptional

Only for BANNER ad type.

Example: summersale

GetHtmlCodeTypestring · enumOptionalExample: HTML_AND_IFRAMEPossible values:

LabelsstringOptionalExample: sale,US

AllowDeepLinkingstringOptionalExample: true

LimitedTimeStartDatestring · date-timeOptionalExample: 2026-09-16T17:01:28-07:00

LimitedTimeEndDatestring · date-timeOptionalExample: 2026-12-31T23:59:59-07:00

TargetMediaPartnersstring[]Optional

Array of partner IDs to restrict the ad to.

TargetMediaPartnerGroupsstring[]Optional

Array of partner group IDs to restrict the ad to.

SeasonstringOptional

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

MobileReadystringOptionalExample: true

PhoneTrackingstringOptionalExample: false

PromoCodeTrackingstringOptionalExample: false

TopSellerstringOptionalExample: false

DealIdstringOptional

Responses

200

The ad was created successfully.

application/json

StatusstringOptionalExample: OK

Uristring · uri-referenceOptionalExample: /Advertisers/{AccountSID}/Ads/600000

post/Advertisers/{AccountSID}/Ads

cURL

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: */*'

200

The ad was created successfully.

{
  "Status": "OK",
  "Uri": "/Advertisers/{AccountSID}/Ads/600000"
}

Get Ad Details

get

Retrieves the details of an existing ad by its unique impact.com Ad ID.

Authorizations

AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters

AccountSIDstringRequired

AdIdstringRequired

The unique identifier for the ad.

Responses

200

An ad object.

application/json

IdstringOptionalExample: 892081

NamestringOptionalExample: Summer Sale 2020 250x250

DescriptionstringOptionalExample: Our best deals this summer creative.

CampaignIdstringOptionalExample: 1000

CampaignNamestringOptionalExample: Acme Campaign

AdTypestring · enumOptionalExample: BANNERPossible values:

LandingPagestring · uriOptionalExample: http://www.test.com/6234652

DateCreatedstring · date-timeOptionalExample: 2024-02-29T22:03:35-08:00

DateLastUpdatedstring · date-timeOptionalExample: 2024-02-29T22:03:35-08:00

CustomAdServingUrlstring · uriOptional

IabAdUnitstringOptionalExample: CUSTOM

ThirdPartyServableAdCreativeHeightstringOptionalExample: 250

ThirdPartyServableAdCreativeWidthstringOptionalExample: 250

BannerAlternativeTagstringOptionalExample: summersale

LinkTextstringOptional

CouponLinkNamestringOptional

GetHtmlCodeTypestring · enumOptionalExample: HTML_AND_IFRAMEPossible values:

LabelsstringOptional

Comma-separated key terms.

Example: sale,US

AllowDeepLinkingstringOptionalExample: true

LanguagestringOptional

Example: ENGLISH

LimitedTimeStartDatestring · date-timeOptionalExample: 2020-09-16T17:01:28-07:00

LimitedTimeEndDatestring · date-timeOptional

RestrictedMediaPartnersstring[]Optional

RestrictedMediaPartnerGroupsstring[]Optional

SeasonstringOptional

Example: SUMMER

Uristring · uri-referenceOptionalExample: /Advertisers/{AccountSID}/Ads/892081

DealIdstringOptionalExample: 85433

DealNamestringOptionalExample: Summer Sale 2020

AdCodeTemplatestringOptional

CouponAllowCustomPromoCodestringOptional

CustomisationChargestringOptional

MobileReadystringOptional

PhoneTrackingstringOptional

PromoCodeTrackingstringOptional

TopSellerstringOptional

DealDescriptionstringOptional

DealStatestringOptional

DealTypestringOptional

DealScopestringOptional

DealProductsstring[]Optional

DealCategoriesstringOptional

DiscountTypestringOptional

DiscountAmountstringOptional

DiscountCurrencystringOptional

DiscountPercentstringOptional

DiscountMaximumPercentstringOptional

DiscountPercentRangeStartstringOptional

DiscountPercentRangeEndstringOptional

GiftstringOptional

RebateAmountstringOptional

RebateCurrencystringOptional

DealDefaultPromoCodestringOptional

MinimumPurchaseAmountstringOptional

MinimumPurchaseAmountCurrencystringOptional

MaximumSavingsAmountstringOptional

MaximumSavingsCurrencystringOptional

BogoBuyQuantitystringOptional

BogoBuyScopestringOptional

BogoBuyNamestringOptional

BogoBuyImageUrlstringOptional

BogoGetQuantitystringOptional

BogoGetScopestringOptional

BogoGetDiscountTypestringOptional

BogoGetNamestringOptional

BogoGetImageUrlstringOptional

BogoGetDiscountAmountstringOptional

BogoGetDiscountCurrencystringOptional

BogoGetDiscountPercentstringOptional

PurchaseLimitQuantitystringOptional

DealStartDatestring · date-timeOptional

DealEndDatestring · date-timeOptional

SynchAdsPromoCodesstringOptional

DealRestrictedMediaPartnersstring[]Optional

DealRestrictedMediaPartnerGroupsstring[]Optional

get/Advertisers/{AccountSID}/Ads/{AdId}

cURL

curl -L \
  --url 'https://api.impact.com/Advertisers/{AccountSID}/Ads/{AdId}' \
  --user '{AccountSID}:{AuthToken}' \
  --header 'Accept: */*'

200

An ad object.

{
  "Id": "892081",
  "Name": "Summer Sale 2020 250x250",
  "Description": "Our best deals this summer creative.",
  "CampaignId": "1000",
  "CampaignName": "Acme Campaign",
  "AdType": "BANNER",
  "LandingPage": "http://www.test.com/6234652",
  "MobileFallbacks": {
    "Android": "text",
    "IOS": "text"
  },
  "DateCreated": "2024-02-29T22:03:35-08:00",
  "DateLastUpdated": "2024-02-29T22:03:35-08:00",
  "CustomAdServingUrl": "",
  "IabAdUnit": "CUSTOM",
  "ThirdPartyServableAdCreativeHeight": "250",
  "ThirdPartyServableAdCreativeWidth": "250",
  "BannerAlternativeTag": "summersale",
  "LinkText": "",
  "CouponLinkName": "text",
  "GetHtmlCodeType": "HTML_AND_IFRAME",
  "Labels": "sale,US",
  "AllowDeepLinking": "true",
  "Language": "ENGLISH",
  "LimitedTimeStartDate": "2020-09-16T17:01:28-07:00",
  "LimitedTimeEndDate": "",
  "RestrictedMediaPartners": [
    "text"
  ],
  "RestrictedMediaPartnerGroups": [
    "text"
  ],
  "Season": "SUMMER",
  "Uri": "/Advertisers/{AccountSID}/Ads/892081",
  "DealId": "85433",
  "DealName": "Summer Sale 2020",
  "AdCodeTemplate": "text",
  "CouponAllowCustomPromoCode": "text",
  "CustomisationCharge": "text",
  "MobileReady": "text",
  "PhoneTracking": "text",
  "PromoCodeTracking": "text",
  "TopSeller": "text",
  "DealDescription": "text",
  "DealState": "text",
  "DealType": "text",
  "DealScope": "text",
  "DealProducts": [
    "text"
  ],
  "DealCategories": "text",
  "DiscountType": "text",
  "DiscountAmount": "text",
  "DiscountCurrency": "text",
  "DiscountPercent": "text",
  "DiscountMaximumPercent": "text",
  "DiscountPercentRangeStart": "text",
  "DiscountPercentRangeEnd": "text",
  "Gift": "text",
  "RebateAmount": "text",
  "RebateCurrency": "text",
  "DealDefaultPromoCode": "text",
  "MinimumPurchaseAmount": "text",
  "MinimumPurchaseAmountCurrency": "text",
  "MaximumSavingsAmount": "text",
  "MaximumSavingsCurrency": "text",
  "BogoBuyQuantity": "text",
  "BogoBuyScope": "text",
  "BogoBuyName": "text",
  "BogoBuyImageUrl": "text",
  "BogoGetQuantity": "text",
  "BogoGetScope": "text",
  "BogoGetDiscountType": "text",
  "BogoGetName": "text",
  "BogoGetImageUrl": "text",
  "BogoGetDiscountAmount": "text",
  "BogoGetDiscountCurrency": "text",
  "BogoGetDiscountPercent": "text",
  "PurchaseLimitQuantity": "text",
  "DealStartDate": "2026-07-16T11:03:58.812Z",
  "DealEndDate": "2026-07-16T11:03:58.812Z",
  "SynchAdsPromoCodes": "text",
  "DealRestrictedMediaPartners": [
    "text"
  ],
  "DealRestrictedMediaPartnerGroups": [
    "text"
  ]
}

Update an Ad

put

Updates an existing ad, including its creative file if needed. Use multipart/form-data if uploading a creative file.

Authorizations

AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters

AccountSIDstringRequired

AdIdstringRequired

The unique identifier for the ad to update.

Body

Schema for creating and updating an Ad. Some fields are conditionally required based on AdType.

NamestringOptionalExample: Summer Sale 2020 250x250

CampaignIdstringOptionalExample: 1000

AdTypestring · enumOptionalExample: BANNERPossible values:

LanguagestringOptional

Example: ENGLISH

DescriptionstringOptionalExample: Our best deals this summer creative.

LandingPagestring · uriOptionalExample: http://www.test.com/6234652

CustomAdServingUrlstring · uriOptional

Required for BANNER if not using AdCodeTemplate or BannerCreativeFile.

AdCodeTemplatestringOptional

Required for BANNER if not using CustomAdServingUrl or BannerCreativeFile.

BannerCreativeFilestring · binaryOptional

Creative file for a BANNER ad. Use multipart/form-data.

CouponLinkNamestringOptional

Required for COUPON ad type.

CouponAllowCustomPromoCodebooleanOptional

Whether the ad allows partners to use a custom promo code (instead of the default coupon code).

Example: false

CustomisationChargenumber · decimalOptional

The charge applied when partners customise this ad.

Example: 0

LinkTextstringOptional

Required for TEXT_LINK ad type.

IabAdUnitstringOptionalExample: CUSTOM

ThirdPartyServableAdCreativeHeightstringOptionalExample: 250

ThirdPartyServableAdCreativeWidthstringOptionalExample: 250

BannerAlternativeTagstringOptional

Only for BANNER ad type.

Example: summersale

GetHtmlCodeTypestring · enumOptionalExample: HTML_AND_IFRAMEPossible values:

LabelsstringOptionalExample: sale,US

AllowDeepLinkingstringOptionalExample: true

LimitedTimeStartDatestring · date-timeOptionalExample: 2026-09-16T17:01:28-07:00

LimitedTimeEndDatestring · date-timeOptionalExample: 2026-12-31T23:59:59-07:00

TargetMediaPartnersstring[]Optional

Array of partner IDs to restrict the ad to.

TargetMediaPartnerGroupsstring[]Optional

Array of partner group IDs to restrict the ad to.

SeasonstringOptional

Example: SUMMER

MobileReadystringOptionalExample: true

PhoneTrackingstringOptionalExample: false

PromoCodeTrackingstringOptionalExample: false

TopSellerstringOptionalExample: false

DealIdstringOptional

Responses

200

The ad was updated successfully.

application/json

StatusstringOptionalExample: OK

Uristring · uri-referenceOptionalExample: /Advertisers/{AccountSID}/Ads/892081

put/Advertisers/{AccountSID}/Ads/{AdId}

cURL

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: */*'

200

The ad was updated successfully.

{
  "Status": "OK",
  "Uri": "/Advertisers/{AccountSID}/Ads/892081"
}

PreviousAds NextModels

Last updated 1 month ago