A Comprehensive Guide

API Documentation for كوانتم Banner and Popup Ads

Introduction

The Quantum API provides a comprehensive suite of tools to manage and operate ad campaigns, including banners and popup ads. These APIs allow you to:

Create, manage, and delete banner and popup ad campaigns.
Generate detailed reports, including impressions, clicks, and conversions.
Implement advanced targeting using demographic and geographic filters.
Retrieve available ad inventory and place bids for ad slots.

Note: The APIs for banners and popup ads are identical to those for other ad types. However, the responsibility for displaying the ads as banners or popups lies with the partner’s implementation.

This documentation is structured to ensure a seamless integration experience for developers.

Base URL

All API requests should be directed to the following base URL:

				
					https://api.engine.quantums.com.sa/

Authentication

Quantum API requires an API key for authentication. Include the key in the headers of each request:

				
					Authorization: Bearer YOUR_API_KEY

Contact support to obtain your API key.

Campaign Management APIs

List Campaigns

Endpoint: GET /campaigns

Description: Retrieve a paginated list of banner or popup ad campaigns.

Parameters:

Parameter	Type	Location	Required	Description
skip	integer	query	Yes	Number of records to skip.
take	integer	query	Yes	Number of records to retrieve.

Response:

200 OK: Returns an array of campaigns with their metadata.

Example Request:

				
					curl -X GET "https://api.engine.quantums.com.sa/campaigns?skip=0&take=10" \
-H "Authorization: Bearer YOUR_API_KEY"

Expected Response:

				
					[
  {
    "id": "92de7c0d-ecba-4f27-b014-a997a2110291",
    "name": "Holiday Banner Campaign",
    "dailyBudget": 2000,
    "totalBudget": 30000,
    "impressionBid": 15,
    "status": "Active"
  }
]

Create Campaign

Endpoint: POST /campaigns
Description: Create a new banner or popup ad campaign with specified parameters.
Request Body (JSON):

				
					{
  "name": "Campaign Name",
  "dailyBudget": 1500,
  "totalBudget": 15000,
  "impressionBid": 10,
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z",
  "notificationUri": "https://example.com/notify",
  "tags": [["gender:male", "region:ksa"]],
  "description": "Banner campaign targeting male users in KSA",
  "imageUri": "https://example.com/banner.jpg"
}

Field	Type	Required	Description
name	string	Yes	The name of the campaign.
dailyBudget	number	Yes	The daily budget allocated for the campaign.
totalBudget	number	Yes	The total budget for the campaign.
impressionBid	number	Yes	The cost-per-impression bid amount.
startAt	string	Yes	The start date and time of the campaign (ISO 8601).
endAt	string	Yes	The end date and time of the campaign (ISO 8601).
notificationUri	string	Yes	URI for receiving campaign notifications.
tags	array	No	Tags for campaign targeting criteria.
description	string	No	Description of the campaign.
imageUri	string	Yes	URI for the image ad.

Response:

200 OK: Returns details of the newly created campaign, including its unique identifier.

Example Request:

				
					curl -X POST "http://localhost:5068/campaigns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Holiday Banner Campaign",
  "dailyBudget": 2000,
  "totalBudget": 30000,
  "impressionBid": 15,
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z",
  "tags": [["region:ksa", "age:25-34"]],
  "description": "Holiday ads targeting young adults in KSA",
  "imageUri": "https://example.com/banner-holiday.jpg"
}'

Expected Response:

				
					{
  "id": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "name": "Holiday Banner Campaign",
  "dailyBudget": 2000,
  "totalBudget": 30000,
  "impressionBid": 15,
  "status": "Active",
  "tags": [["region:ksa", "age:25-34"]],
  "description": "Holiday ads targeting young adults in KSA",
  "imageUri": "https://example.com/banner-holiday.jpg",
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z"
}

Generate Campaign Reports

Endpoint: POST /reports
Description: Generate a detailed report for a campaign, providing metrics such as impressions, clicks, and conversions.
Request Body (JSON):

				
					{
  "from": "2024-12-01T00:00:00Z",
  "to": "2024-12-15T23:59:59Z",
  "campaignId": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "groupBy": "geo"
}

Field	Type	Required	Description
from	string	Yes	The start date and time for the report (ISO 8601).
to	string	Yes	The end date and time for the report (ISO 8601).
campaignId	UUID	Yes	Unique identifier of the campaign.
groupBy	string	No	The tag used for grouping results.

Response:

200 OK: Returns a JSON report grouped by specified criteria, such as region.

Example Request:

				
					curl -X POST "https://api.engine.quantums.com.sa/reports" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "from": "2024-12-01T00:00:00Z",
  "to": "2024-12-15T23:59:59Z",
  "campaignId": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "groupBy": "geo"
}'

Expected Response:

				
					{
  "reportBuckets": [
    {
      "from": "2024-12-01T00:00:00Z",
      "to": "2024-12-02T00:00:00Z",
      "dataPoints": {
        "geo:ksa": {
          "impressionsCount": 500,
          "clicks": 50,
          "addToCart": 10
        }
      }
    }
  ],
  "totalDataPoint": {
    "impressionsCount": 500,
    "clicks": 50,
    "addToCart": 10
  }
}

Schemas

Campaign Response

Field	Type	Description
id	UUID	Unique identifier for the campaign.
name	string	Name of the campaign.
dailyBudget	number	Daily budget allocated to the campaign.
totalBudget	number	Total budget allocated to the campaign.
impressionBid	number	Cost-per-impression bid.
status	string	Status of the campaign (e.g., Active, Paused).
tags	array	Targeting criteria tags.

Report Response

Field	Type	Description
reportBuckets	array	Array of data buckets grouped by criteria.
totalDataPoint	object	Summary of total metrics across all buckets.