Skip to main content
Use this endpoint to retrieve available ad campaigns for a specific placement in your application. You pass targeting parameters — placement, location, and device type — and the API returns a list of campaigns that match. Call this endpoint server-side before rendering an ad slot so you can select and display the right campaign for the current user context.

​
Endpoint

GET https://ads.enslive.live/api/v1/campaigns/fetch

​
Request example

curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?limit=10&placement=header_banner&location=US&device=mobile" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query parameters

​
placement
string
required
The target placement ID that identifies where the ad will appear in your layout. Examples: header_banner, article_inline, sidebar_top. See Ad Placements for the full list of supported values.
​
limit
integer
default:"10"
The number of campaigns to return. Defaults to 10. Maximum value is 100. Use a higher limit to batch-fetch campaigns and reduce the number of API calls your integration makes.
​
location
string
The ISO 3166-1 alpha-2 country code representing the user’s geographic location. Examples: US, GB, FR. When provided, the API filters campaigns to those targeted at the specified country.
​
device
string
The device type of the current user. Accepted values: mobile, desktop, tablet. When provided, the API filters campaigns to those targeted at the specified device type.

​
Response

​
200 — Success

The response includes a status field, a data array of campaign objects, and a count of returned campaigns. 
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "Summer Sale Campaign",
      "description": "Limited time offer",
      "category": "retail",
      "destinationUrl": "https://example.com/summer",
      "status": "running",
      "createdAt": "2026-04-17T00:00:00Z"
    }
  ],
  "count": 1
}
​
status
string
Always "success" for a successful response.
​
count
integer
The number of campaign objects returned in the data array.
​
data
array
Array of campaign objects matching the requested placement and targeting parameters.

​
400 — Bad Request

Returned when a required parameter is missing or a parameter value is invalid. 
{
  "status": "error",
  "message": "placement parameter is required"
}

​
401 — Unauthorized

Returned when the Authorization header is missing or the API key is invalid. 
{
  "status": "error",
  "message": "unauthorized"
}