GET /api/v1/campaigns/fetch — Retrieve Ad Campaigns

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

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.

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.

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.

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
}

string

Always "success" for a successful response.

integer

The number of campaign objects returned in the data array.

array

Array of campaign objects matching the requested placement and targeting parameters.

Show Campaign object fields

integer

Unique identifier for the campaign. Use this value when calling the impression and click tracking endpoints.

string

The display title of the campaign.

string

A short description of the campaign’s offer or message.

string

The content category the campaign belongs to (e.g., retail, technology, health).

string

The URL users should be directed to when they interact with the campaign.

string

The current status of the campaign. A value of "running" means the campaign is active and eligible for display.

string

ISO 8601 timestamp indicating when the campaign was created.

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"
}

​Endpoint

​Request example

​Query parameters

​Response

​200 — Success

​400 — Bad Request

​401 — Unauthorized

Endpoint

Request example

Query parameters

Response

200 — Success

400 — Bad Request

401 — Unauthorized