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.
| Need | Targeting tactic |
|---|---|
| Reach shoppers based on audience attributes or behavior | Behavioral |
| Reach shoppers based on taxonomy or content relevance | Contextual |
| Retrieve IDs for ad group targeting setup | Behavioral or Contextual |
| Populate targeting pickers in a UI | Behavioral or Contextual |
| Retrieve brand audiences | Behavioral |
Before you begin
- Valid
advertiserId - Understanding of targeting tactics and audience types
Endpoint
POST /api/v2/targeting/list
POST /api/v2/targeting/listRequest 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:
behavioralcontextual
-
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
UsestartIndexandcountto 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
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
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
isDisabled=false. Disabled targets should not be used in ad group or audience workflows. Behavioral filter parameters
| Parameter | Description |
|---|---|
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 asretail,brand,custom,persona, ordemographic. -
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 ifisDisabled=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 tiersWhen 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 Reach Definition Corresponding tiers Low Minimal expansion, more focused relevance tier_1,tier_2Medium Balanced reach and relevance tier_3,tier_4High Broadest expansion, best for discovery campaigns tier_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
Updated 26 days ago
