HomeGuidesAPI ReferenceRelease Notes
Guides

Create the Creatives

Create creatives for a specific advertiser

📘

URL: POST/api/v1/creatives

Request Parameters

ParameterDescriptionTypeRequiredPossible Values
advertiserIdThe ID of the specific advertiserintegerYA valid advertiser Id
metadataFields belonging in a creative:
  • name: Name of the creative. String data type, required field. Max length of name can be 255 characters
  • folderId: The folder id where you want to create your creative in. UUID data type, optional field.
    Note: If folderId is null, the creative will be created in home directory of user group
  • templateId: ID of the template. Its fixed value is 436 at present. Integer data type
JSON objectYThe values:
  • name
  • folderId
  • templateId
adUnitsAd units on creative platform:
marqueeDesktop, marqueeApp, skylineDesktop, skylineApp, skylineDesktopV2, skylineAppV2, skylineDesktopV3, skylineAppV3, brandboxDesktop, brandboxApp, galleryDesktop, galleryApp
Note: Only 8 ad units are required : marqueeDesktop, marqueeApp, skylineDesktop, skylineApp, brandboxDesktop, brandboxApp, galleryDesktop, galleryApp. please consider all others optional

Each ad unit contains following fields:
  • headline: Required field. Character limit 25 characters. Data type is string
  • subhead: Required field. Character limit 30 characters. Data type is string
    Note: subHead should always end with one of these characters ".", "!", "?", "*"
  • cta: Call to action. Required field. Character limit 16 characters. Data type is string
    Note: cta must be drafted in sentence casing to avoid error.
  • backgroundColorHex: Color hex is always "#" followed by 6 digits between 0 and F on the hexadecimal scale.
    • This field only applies to Skyline v3 ad units and is optional
  • textColor: ENUM [gray, white]
    • This field only applies to Skyline v3 ad units and is optional
  • imageAltText: Field to provide description of whats visually represented in your ad. Data type is string. Required field. Character limit 150 characters
  • logoAltText: Field to provide description to logo image. Data type is string. Required field. Character limit 150 characters
  • legalDisclaimerLabel: Optional field, data type is string.This is the title text of the popup disclaimer. legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Data type is string up to 12 characters. Set an empty string to disable the disclaimer popup.
  • legalDisclaimerPopUpCopy: Optional field, This is the text of the popup disclaimer. legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Data type is string up to 600 characters. Set an empty string to disable the disclaimer popup.
  • legalDisclaimerText: This is disclaimer text that will appear in the image. Optional field. Data type is string up to 600 characters. Set an empty string to clear the value.
    Note: You may utilize legalDisclaimerText
    either on its own or in conjunction with a popup disclaimer (legalDisclaimerLabel
    and legalDisclaimerPopUpCopy)
  • variantId: Defines the spec for the ad unit. Required field. Its fixed value is 436 at present. Data type is string
  • images: This field is for details of the images being uploaded: desktop/mobile (according to adunit) image and desktop/mobile logo image.
    Note: For Desktop adunits (marqueeDesktop, skylineDesktop, skylineDesktopV2, skylineDesktopV3, brandboxDesktop, galleryDesktop) allowed values for name are "desktopImage" and "desktopLogo"
    For App adunits (marqueeApp, skylineApp, skylineAppV2, skylineAppV3, brandboxApp, galleryApp) allowed values for name are "mobileImage" and "mobileLogo"
    • assetId: data type UUID string.
      Note: Use the assetId you receive from response of POST/api/v1/assets/photo
    • crop: Only applicable for desktop image and mobile image. Not applicable for desktop/mobile logo image. It's an optional field. If you decide to crop the image, you cannot use both focal and rectangular values together.
      Note: Sending in a new image will reset crop settings.
      • focal: focal crop can be passed as part of a lifestyle image in any/all ad units. If set, the same Focal point crop settings will be applied to all ad units and will also overwrite any previously set rectangular crop settings.
        Focal will set the focus of the image at the specified x and y coordinates where x is horizontal, y is vertical, the origin is at the top left corner, and the range is between 0 and 1 exclusive.
        To remove the focal crop, the request body must include the ad unit with its image fields and an empty crop object. This action is supported in PATCH and PUT methods, but not in POST. Note that, Focal crop will be removed from all ad units irrespective of the number of ad units passed without the focal crop attribute.
        • x: coordinate of the horizontal, ex: 0.2
        • y: coordinate of the vertical, ex: 0.4
      • rectangular: Rectangular crop settings can be modified for each ad unit. To remove the rectangular crop, request body must specify the ad unit(s) from which it is to be removed, including the image fields and an empty crop object. This action is supported in PATCH and PUT methods, but not in POST
        • x: use x to crop image from left side
        • y: use y to crop image from top. Values of both x and y range between 0 and 1
        • w: use w to crop width of the image
        • h: use h to crop height of the image.

    Note: The desktop/mobile Image
    and desktop/mobile logos should have:
    • Max file size 10 mb
    • Max dimensions 5000px*5000px
JSON objectYmarqueeDesktop
marqueeApp
skylineDesktop skylineApp skylineDesktopV2
skylineAppV2
skylineDesktopV3
skylineAppV3
brandboxDesktop brandboxApp galleryDesktop galleryApp

Creative Ad Unit Character Limits

Character limits vary across the various ad units, refer to the tables below for character length limits per ad unit.

marqueeDesktop / tablet

TextCharacter LimitRequired/Optional
headline25Required
subhead55Required
cta16Required
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

marqueeApp

TextCharacter LimitRequired/Optional
headline25Required
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

skylineDesktop

TextCharacter LimitRequired/Optional
headline25Required
subhead30Optional
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Optional
logoAltText150Required

skylineApp

TextCharacter LimitRequired/Optional
headline25Required
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
logoAltText150Required

skylineDesktopV2

TextCharacter LimitRequired/Optional
headline35Required
subhead40Optional
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Optional
logoAltText150Required

skylineAppV2

TextCharacter LimitRequired/Optional
headline35Required
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
logoAltText150Required

skylineDesktopV3

TextCharacter LimitRequired/Optional
headline35Required
subhead40Optional
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

skylineAppV3

TextCharacter LimitRequired/Optional
headline35Required
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

brandboxDesktop

TextCharacter LimitRequired/Optional
headline25Required
subhead55Required
cta16Required
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

brandboxApp

TextCharacter LimitRequired/Optional
headline25Required
subhead55Required
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

galleryDesktop full/mini

TextCharacter LimitRequired/Optional
headline25Required
subhead55Required
cta16Required
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

galleryApp

TextCharacter LimitRequired/Optional
headline25Required
cta16Required
legalDisclaimerText600Optional
legalDisclaimerLabel12Optional
legalDisclaimerPopUpCopy600Optional
imageAltText150Required
logoAltText150Required

👉

Please refer to the Appendix to find the required, optional, and non-required assets for each ad unit

Sample Error Messages Thrown for Create Creative API


ScenarioError Message
field not found$.<fieldName>: null found, string expected
text validations
  • $.adUnits.marqueeDesktop.subhead: does not match the regex pattern .[.!?]
  • alternative: $.adUnits.marqueeDesktop.subhead: does not end with either a period, exclamation mark, question mark, or an asterisk

  • $.adUnits.marqueeDesktop.headline: may only be 25 characters long
  • $.adUnits.marqueeDesktop.headline: must be at least 1 characters long

  • $.adUnits.marqueeDesktop.cta: does not match the regex pattern ^[A-Z][a-z\\s]*[.!?]?`
  • alternative: $.adUnits.marqueeDesktop.cta: CTA should follow sentence casing

Headers

Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the API.YPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
WM_CONSUMER.IDWe will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.   YPlease use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information
WM_SEC.AUTH_SIGNATUREAuth signature as an API key.YUse the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSIONWe will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.Y1
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.YUse the signature generator code from Getting Started Guide to generate this value

Sample Request: Create Creative

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/creatives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: **************' \
--header 'WM_SEC.KEY_VERSION: 1' \
--header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": 123, "metadata": { "name": "New Creative", "folderId": "1a15de37-47c1-53ad-7c1a-2481d3c7a123", "templateId": "436" }, "adUnits": { "marqueeDesktop": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "legalDisclaimerLabel": "Legal Disclaimer", "legalDisclaimerPopUpCopy": "Body for the pop up disclaimer", "variantId": "436", "images": [ { "name": "desktopImage", "assetId": "<assetId>", "crop": { "focal": { "x": 0, "y": 0 }, "rectangular": { "x": 0, "y": 0, "w": 0, "h": 0 } } }, { "name": "desktopLogo", "assetId": "<assetId>" } ] }, "marqueeApp": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "mobileImage", "assetId": "<assetId>" }, { "name": "mobileLogo", "assetId": "<assetId>" } ] }, "skylineDesktop": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "desktopImage", "assetId": "<assetId>" }, { "name": "desktopLogo", "assetId": "<assetId>" } ] }, "skylineApp": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "mobileImage", "assetId": "<assetId>" }, { "name": "mobileLogo", "assetId": "<assetId>" } ] }, "skylineDesktopV2": { "headline": "Gentle & soft", "subhead": "Your subhead goes here", "logoAltText": "Parents Choice logo", "backgroundColorHex": "#abcdef", "textColor": "gray", "imageAltText": "image alt text", "legalDisclaimerText": "Disclaimer text", "legalDisclaimerLabel": "Disclaimer", "legalDisclaimerPopUpCopy": "Popup Disclaimer text", "images": [ { "name": "desktopImage", "assetId": "<asset_id>" }, { "name": "desktopLogo", "assetId": "<asset_id>" } ] }, "skylineAppV2": { "headline": "Gentle & soft", "logoAltText": "Parents Choice logo", "backgroundColorHex": "#000000", "textColor": "white", "imageAltText": "image alt text", "legalDisclaimerText": "Disclaimer text", "legalDisclaimerLabel": "Disclaimer", "legalDisclaimerPopUpCopy": "Popup Disclaimer text", "images": [ { "name": "mobileImage", "assetId": "<asset_id>" }, { "name": "mobileLogo", "assetId": "<asset_id>" } ] }, "skylineDesktopV3": { "headline": "Gentle & soft", "subhead": "Your subhead goes here", "logoAltText": "Parents Choice logo", "backgroundColorHex": "#abcdef", "textColor": "gray", "imageAltText": "image alt text", "legalDisclaimerText": "Disclaimer text", "legalDisclaimerLabel": "Disclaimer", "legalDisclaimerPopUpCopy": "Popup Disclaimer text", "images": [ { "name": "desktopImage", "assetId": "<asset_id>" }, { "name": "desktopLogo", "assetId": "<asset_id>" } ] }, "skylineAppV3": { "headline": "Gentle & soft", "logoAltText": "Parents Choice logo", "backgroundColorHex": "#000000", "textColor": "white", "imageAltText": "image alt text", "legalDisclaimerText": "Disclaimer text", "legalDisclaimerLabel": "Disclaimer", "legalDisclaimerPopUpCopy": "Popup Disclaimer text", "images": [ { "name": "mobileImage", "assetId": "<asset_id>" }, { "name": "mobileLogo", "assetId": "<asset_id>" } ] }, "brandboxDesktop": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "desktopImage", "assetId": "<assetId>" }, { "name": "desktopLogo", "assetId": "<assetId>" } ] }, "brandboxApp": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "mobileImage", "assetId": "<assetId>" }, { "name": "mobileLogo", "assetId": "<assetId>" } ] }, "galleryDesktop": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "desktopImage", "assetId": "<assetId>" }, { "name": "desktopLogo", "assetId": "<assetId>" } ] }, "galleryApp": { "headline": "Buy our product", "subhead": "It is cool", "cta": "NOW!", "imageAltText": "A picture of our product", "logoAltText": "Our company'\''s logo", "legalDisclaimerText": "Some text", "variantId": "436", "images": [ { "name": "mobileImage", "assetId": "<assetId>" }, { "name": "mobileLogo", "assetId": "<assetId>" } ] }, }
}'

Response

ElementDescriptionType
codeThe response code can have following values:
  • success
  • failure

Click here for more information about Status Codes and Errors		string
detailsPossible values of details:
  • Details of the error if value of response code is failure
  • It returns a string value "success" if value of response code is success
string
creativeIdID of the creative. It is returned in response only if code=successstring
messageDetails of the error if value of code is failure and validation errors were foundstring

Sample Response 1

[ { "code": "success", "details": ["success"], "creativeId": "e02a09b2-1e3c-2g22-bf47-8a123c35002a" }
]

Sample Response 2

[ { "code": "failure", "details": ["CREATIVE_VALIDATION_ERROR"], "message":"Found 8 validation error(s).\n$.adUnits.marqueeDesktop.headline: must be at least 1 characters long $.adUnits.marqueeDesktop.subhead does not end with a period(.), exclamation(!), question(?), or an asterisk(*). $.adUnits.marqueeDesktop.cta does not follow sentence casing. $.adUnits.marqueeDesktop.imageAltText: must be at least 1 characters long\n $.adUnits.marqueeDesktop.logoAltText: must be at least 1 characters long $.adUnits.marqueeDesktop.images: null found, array expected\n Disclaimer Pop up copy and Label should be used together. $.metadata.templateId: does not have a value in the enumeration [436]" }
]

Sample Response 1 - Failure

[ { "code": "failure", "message": "Found 1 validation error(s).n$.adUnits.skylineDesktopV3.backgroundColorHex: should be a valid hexadecimal color code", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Sample Response 2 - Failure

[ { "code": "failure", "message": "Found 1 validation error(s). $.adUnits.skylineDesktopV3.textColor:text color can only be 'white' or 'gray' ", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Note: textColor and backgroundColorHex must meet WCAG contrast requirements.

Sample Response 3 - Failure

[ { "code": "failure", "message": "Found 1 validation error. Background color does not meet WCAG contrast requirements with the provided text color. Please choose a different combination.", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Note: backgroundColorHex will be validated to not be within a tolerance zone of any Walmart reserved color. If validation does not pass, some related colors will be suggested.

Sample Response 4 - Failure

[ { "code": "failure", "message": "Found 1 validation error. Background color violates Walmart color guidelines: #ff0000. nHere are some color suggestions: #ED013B, #E40038, #DB0230, #D2012E, #C80226, #BF011E, #C00018, #B7000F, #B70006, #B50B00, #B01D00, #B32A00, #AF3100, #B33900, #BA4900, #C24D01, #C65401", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Sample Response 5 - Failure

[ { "code": "failure", "message": "Found 1 validation error. Text color 'white' is not valid with default background color (#F8F8F8)due to WCAG contrast requirements.", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Updated 7 days ago