ENS Ads matches campaigns to users across three targeting dimensions: geographic location, device type, and content category. You supply these as parameters when calling GET /api/v1/campaigns/fetch, and the API uses them to return campaigns that are most relevant to the current user and page context. Providing accurate targeting data improves match quality, which leads to higher engagement and better results for advertisers on your platform.
Geographic targeting
Pass the user’s country as a two-letter ISO 3166-1 alpha-2 code in the location query parameter.
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=sidebar_top&location=US" \
-H "Authorization: Bearer YOUR_API_KEY"
| Country | Code |
|---|
| United States | US |
| United Kingdom | GB |
| France | FR |
| Japan | JP |
| Germany | DE |
| Canada | CA |
| Australia | AU |
| Brazil | BR |
location, the API returns campaigns without applying geographic filtering.
Always pass location when you can determine the user’s country — for example, from a GeoIP lookup or a user profile setting. Geographic targeting is one of the strongest signals for improving campaign relevance.
Device targeting
Pass the user’s device type in the device query parameter. The accepted values are:
| Value | When to use |
|---|
mobile | Smartphones and small-screen handheld devices |
desktop | Laptops and desktop computers |
tablet | Tablets and large-screen touch devices |
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=article_inline&location=GB&device=mobile" \
-H "Authorization: Bearer YOUR_API_KEY"
User-Agent header or a device detection library, rather than relying on client-side JavaScript, so the parameter is always present when the request is made.
Always pass device when it is known. Advertisers frequently target specific device types, so omitting this parameter may exclude campaigns that would otherwise be a good match.
Content category targeting
Campaigns are associated with a content category that describes the subject matter of the advertised product or service. While category is not a direct query parameter on the fetch endpoint, the campaign objects returned include a category field you can use to filter or contextually style ads on your page.
The full set of supported categories is:
| Category |
|---|
technology |
business |
sports |
entertainment |
health |
politics |
science |
lifestyle |
travel |
Combining all three dimensions
For best results, pass placement, location, and device together on every fetch request:
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=hero_section&location=JP&device=desktop&limit=5" \
-H "Authorization: Bearer YOUR_API_KEY"
limit parameter is optional (default 10, max 100) and controls the maximum number of campaigns returned. Reduce it when you only have room to display a small number of ads.
When you track an impression or click, pass the same location and device values you used during the fetch. This keeps targeting data consistent across the campaign lifecycle and ensures accurate performance reporting for advertisers.
Parameter summary
| Parameter | Type | Required | Description |
|---|
placement | string | Yes | The placement slot you are filling (e.g., header_banner) |
location | string | No | ISO 3166-1 alpha-2 country code (e.g., US, GB) |
device | string | No | mobile, desktop, or tablet |
limit | integer | No | Number of campaigns to return. Default 10, max 100 |