List Targeting

Retrieve behavioral audience and contextual targeting IDs for Onsite Display workflows.

Overview

Retrieve available targeting options for Onsite Display ad groups and audience workflows.

This endpoint returns both contextual targeting IDs and behavioral audience IDs required when configuring targeting in ad groups and building advanced audiences.

Availability

Supported for Onsite Display only.

How it works

The targeting list endpoint returns eligible targeting options and metadata based on the selected targeting tactic.

Supported targeting types include:

  • Behavioral audiences
  • Contextual targets

This endpoint supports:

  • Pagination
  • Search
  • Filtering by targeting type
  • Audience metadata retrieval

This is a read-only endpoint and does not modify advertiser configuration.

Discovery

Retrieve targeting and audience IDs.

Select tactic

Choose behavioral or contextual targeting.

Validate results

Confirm names, attributes, and disabled status.

Apply targeting

Use the selected IDs in ad group setup.

Activate workflows

Build audiences or finalize delivery configuration.

Choosing the right targeting tactic

Use the table below to select the targeting mode that matches your workflow.

NeedTargeting tactic
Reach shoppers based on audience attributes or behaviorBehavioral
Reach shoppers based on taxonomy or content relevanceContextual
Retrieve IDs for ad group targeting setupBehavioral or Contextual
Populate targeting pickers in a UIBehavioral or Contextual
Retrieve brand audiencesBehavioral

Before you begin

  • Valid advertiserId
  • Understanding of targeting tactics and audience types

Endpoint

POST /api/v2/targeting/list

View technical specifications


Request details

How this request is used

Use this endpoint to retrieve targeting IDs and metadata.

Use it for:

  • Ad group targeting setup
  • Advanced audience creation
  • Audience selection workflows
  • Dynamic targeting UI population

Key fields and behaviors

  • filter
    Narrow results based on tactic, ID, audience type, attribute, and related criteria.

    • filter[tactic]
      Determines which targeting family to return.

      Supported values:

      • behavioral
      • contextual
    • filter[id]
      Retrieves metadata for one or more specific targeting IDs.

      Useful for:

      • Audience validation
      • Existing targeting retrieval
      • Edit workflows
  • searchText
    Searches targeting names and metadata using keyword matching.

    Common uses:

    • Search-based UI workflows
    • Audience discovery
    • Contextual category lookup
  • Pagination
    Use startIndex and count to paginate large result sets.

Behavioral targeting filters

Behavioral audiences support additional filtering options beyond contextual targeting.

If filter[tactic]=behavioral, one of the following must be included:

  • filter[id]
  • filter[audienceType]
  • searchText

Audience types

Behavioral

Audience-based targeting

Use when you want to reach shoppers based on audience behavior, brand affinity, persona, demographic, or custom audience rules.

  • Supports audience-type filters
  • Supports attribute filters
  • Commonly used in ad group targeting and audience workflows
Contextual

Taxonomy-based targeting

Use when you want to reach shoppers based on taxonomy, content relevance, or contextual category structure.

  • Supports taxonomy hierarchy
  • Supports search and filtering
  • Commonly used for ad group contextual setup
Readiness check: only use targets with isDisabled=false. Disabled targets should not be used in ad group or audience workflows.

Behavioral filter parameters

ParameterDescription
filter[audienceType]Filter by audience classification
filter[attribute]Filter by audience attribute within the selected audience type

Sample requests

Filter contextual targets using ID and searchText
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v2/targeting/list' \ --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": 1, "filter[tactic]": "CONTEXTUAL", "filter[id]": [100, 10], "searchText": "Test", "startIndex": 0, "count": 10 }'
Filter behavioral targets by audience type and attribute
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v2/targeting/list' \ --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": 1, "filter[tactic]": "BEHAVIORAL", "filter[audienceType]": "RETAIL", "filter[attribute]": "HISTORICAL", "startIndex": 0, "count": 100 }'
Filter list of custom audiences
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v2/targeting/list' \ --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": 1, "filter[tactic]": "BEHAVIORAL", "filter[audienceType]": "CUSTOM", "filter[attribute]": "RULE_BASED", "startIndex": 0, "count": 100 }'
Filter list by demographic
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v2/targeting/list' \ --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": 1, "filter[tactic]": "BEHAVIORAL", "filter[audienceType]": "DEMOGRAPHIC", "filter[attribute]": "GENDER", "startIndex": 0, "count": 5 }'

Response details

What this response returns

The response returns targeting IDs and metadata for the requested targeting tactic. The response structure varies depending on the tactic filter included in the request.

Key fields to use

  • id
    Unique targeting or audience ID used in downstream APIs.

  • name
    Audience name for UI display and workflow selection.

  • audienceType
    Behavioral audience classification such as retail, brand, custom, persona, or demographic.

  • attribute
    Behavioral audience subtype.

  • reach
    Contextual reach expansion tiers. Used to understand available scale and inventory breadth.

  • isDisabled
    Indicates whether the target or audience can currently be used. Only use an audience if isDisabled=false.

  • code
    Indicates whether the update request succeeded or failed.

  • details
    Provides additional information about the request, including errors when applicable.

  • message
    Optional. High-level, human-readable summary of the error when available.

  • errors
    Detailed information about one or more errors. This is an array object with fields: field, errorType, description

Error Handling

If the request or an individual item fails, the response includes error information to help identify the issue and determine the corrective action. Use errorType for the error condition, field for the affected request field when applicable, and description for an explanation of the error and, when available, guidance on how to resolve it.
For the complete error response schema and endpoint-specific response definitions, see the API Reference. For guidance on HTTP status codes and how clients should handle them, see API status codes and error handling.

How to interpret results

Contextual responses

Returned when filter[tactic]=contextual. Includes:

  • Taxonomy path
  • Reach expansion tiers
  • Contextual targeting metadata
📌

Understanding Reach expansion tiers

When available inventory for selected categories is limited, Walmart's machin learning can expand targeting to related categories using omnichannel transaction and browsing data. In the Walmart Connect Ad Center, users can select a low, medium, or high expansion level.

Category ReachDefinitionCorresponding tiers
LowMinimal expansion, more focused relevancetier_1, tier_2
MediumBalanced reach and relevancetier_3, tier_4
HighBroadest expansion, best for discovery campaignstier_5, tier_6, tier_7

Behavioral responses

Returned when filter[tactic]=behavioral. Includes:

  • Audience classifications
  • Audience attributes
  • Audience targeting metadata

Sample responses

List of specific contextual targets by ID and searchText
{ "totalResults": 2, "contextual": [ { "id": 100, "name": "12 and up Test", "taxonPath": "toys & games|12 and up", "reach": ["TIER_1", "TIER_2", "TIER_3", "TIER_4", "TIER_5", "TIER_6", "TIER_7"], "isDisabled": false }, { "id": 10, "name": "Test 2 to 4", "taxonPath": "toys & games|2 to 4", "reach": ["TIER_1", "TIER_2", "TIER_3", "TIER_4", "TIER_5", "TIER_6", "TIER_7"], "isDisabled": false } ]
}
List of recent buyers of a category
{ "totalResults": 2, "behavioral": [ { "id": 1, "name": "X", "taxonPath": "Y|Z|X", "isDisabled": true, "audienceType": "RETAIL", "attribute": "HISTORICAL" }, { "id": 1, "name": "Y", "taxonPath": "Y|M|Y", "isDisabled": true, "audienceType": "RETAIL", "attribute": "HISTORICAL" } ]
}
List of audiences with specific audiencetype and attribute
{ "totalResults": 2, "behavioral": [ { "id": 1, "name": "X", "isDisabled": true, "audienceType": "BRAND", "attribute": "LAPSED_BUYERS" }, { "id": 1, "name": "Y", "isDisabled": true, "audienceType": "BRAND", "attribute": "LAPSED_BUYERS" } ]
}
List of Persona/Lifestyle audiences
{ "totalResults": 2, "behavioral": [ { "id": 1, "name": "X", "isDisabled": true, "audienceType": "PERSONA", "attribute": "LIFESTYLE" }, { "id": 1, "name": "Y", "isDisabled": true, "audienceType": "PERSONA", "attribute": "LIFESTYLE" } ]
}
List of rule-based custom audiences
{ "totalResults": 2, "behavioral": [ { "id": 1, "name": "czczcz", "isDisabled": true, "audienceType": "CUSTOM", "attribute": "RULE_BASED" }, { "id": 1, "name": "czczczcz", "isDisabled": true, "audienceType": "CUSTOM", "attribute": "RULE_BASED" } ]
}
List of demographic audiences by gender
{ "totalResults": 1, "behavioral": [ { "id": 1, "name": "Men test", "isDisabled": false, "audienceType": "DEMOGRAPHIC", "attribute": "GENDER" } ]
}
List audience matching supplied audience ID
{ "totalResults": 1, "behavioral": [ { "id": 123, "name": "Less than $24,999 test", "isDisabled": false, "audienceType": "DEMOGRAPHIC", "attribute": "HOUSEHOLD_INCOME" } ]
}
Sample Response - failure
[ { "code": "failure", "details": [ "string" ],    "message": "string",
    "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]

Common issues

  • Omitting required behavioral filters
  • Attempting to use disabled audiences
  • Using contextual targets without validating taxonomy hierarchy
  • Forgetting pagination for large audience sets

What happens next

After retrieving targeting IDs:

  • Select the targeting tactic for the ad group
  • Store the relevant targeting IDs
  • Use IDs in ad group targeting configuration
  • Optionally apply geotargeting overlays

Related pages


Did this page help you?