A Comprehensive Guide

API Documentation for Quantum Audio Ads

Introduction

The Quantum API provides a comprehensive suite of tools to manage and operate audio ad campaigns effectively. These APIs allow you to:

Create, manage, and delete audio 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.

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 audio Campaigns

Endpoint: GET/campaigns
Description: Retrieve a paginated list of audio 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 Audio Campaign",
    "dailyBudget": 2000,
    "totalBudget": 30000,
    "impressionBid": 15,
    "status": "Active"
  }
]

Create Campaign

Endpoint: POST /campaigns

Description: Create a new audio 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": "Audio campaign targeting male users in KSA",
  "audioUri": "https://example.com/audio.mp3"
}

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.
audioUri	string	Yes	URI for the audio ad content.

Response:

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

Example Request:

				
					curl -X POST "https://api.engine.quantums.com.sa/campaigns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Holiday Audio 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",
  "audioUri": "https://example.com/audio-holiday.mp3"
}'

Expected Response:

				
					{
  "id": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "name": "Holiday Audio Campaign",
  "dailyBudget": 2000,
  "totalBudget": 30000,
  "impressionBid": 15,
  "status": "Active",
  "tags": [["region:ksa", "age:25-34"]],
  "description": "Holiday ads targeting young adults in KSA",
  "audioUri": "https://example.com/audio-holiday.mp3",
  "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.