Introduction

This tutorial explains how to implement, via API, the guide introduced in A2 Getting Started: Basic Usage. In this guide, you will learn how to define ad placements and configure image banner advertisements.

An access token is required to follow the examples below. If you have not yet generated one, please refer to the following article: Getting api access token.

A budget is required to register an advertising campaign. Before proceeding, make sure to allocate a budget to the administrator account.

API: Update user budget
curl http://your_a2_service/api/user/budget \
  --request PATCH \
  --header 'Authorization: Bearer <token>' \  
  --header 'Content-Type: application/json' \
  --data '{
  "budget": 1000,
  "credit": 1000000,
  "id": "4f45b2ba-c3dd-4ad9-9e5a-669bf0b0c396"
}'

Create Placement

Add an placementwhere the ads will be served. In this example, we will create a placement with the following conditions:

ext.display.enabled=1: Allows campaign with display creatives to run on this placement.
display.{w, h}: Sets the placement size to 300 px (width) by 250 px (height).
ext.responsive=resize: Dynamically adjusts the size of the creative to fit the placement.
ext.approval_method=admin: Requires administrator approval before ads can be served on this placement.

API: Create a placement
curl --request POST \
  --url https://your_a2_service/api/placements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "campaign_permission": {"black": [], "white": []},
  "description": "This is a banner ad placement",
  "display": {
    "clktype": 1,
    "displayfmt": {
      "ext": {},
      "h": 250,
      "w": 300
    },
    "h": 250,
    "mime": [],
    "nativefmt": {
      "ext": {}
    },
    "w": 300
  },
  "ext": {
    "approval_method": "admin",
    "display": {
      "enabled": 1
    },
    "native": {
      "enabled": 0
    },
    "payout": "rates",
    "responsive": "resize",
    "target_ecpm": 0,
    "video": {
      "enabled": 0
    }
  },
  "is_active": false,
  "name": "My First Placement"
}'

Created Placement Response
{
  "created_at": "2025-04-15T06:35:47.151Z",
  "updated_at": "2025-04-15T06:35:47.151Z",
  "name": "…",
  "description": "…",
  "is_active": false,
  "campaign_permission": {
    "white": [],
    "black": []
  },
  "display": {
    "clktype": 1,
    "mime": [],
    "w": 300,
    "h": 250,
    "displayfmt": {
      "ext": {},
      "h": 250,
      "w": 300
    },
    "nativefmt": {
      "ext": {}
    }
  },
  "video": {
    "ptype": 1,
    "delay": 0,
    "skip": 0,
    "skipmin": 0,
    "skipafter": 0,
    "playmethod": [],
    "clktype": 1,
    "mime": [],
    "ctype": [
      2
    ],
    "w": 480,
    "h": 300,
    "mindur": 0,
    "maxdur": 0,
    "linear": 0
  },
  "ext": {
    "display": {
      "enabled": 1
    },
    "video": {
      "enabled": 0
    },
    "native": {
      "enabled": 0
    },
    "responsive": "resize",
    "payout": "rates",
    "approval_method": "admin",
    "target_ecpm": 0
  },
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "id": "4f45b2ba-c3dd-4ad9-9e5a-669bf0b0c396",
  "no": 1
}

Create Campaign

An advertising campaign is an advertising activity unit that enables you to run specific ads according to your goals and measure their performance.

We will create a campaign aimed at maximizing impressions (impression, maximize_volume) within a given budget over a specified period.

If campaign creation fails, please check the error message for more details.

API: Create a campaign
curl --request POST \
  --url https://your_a2_service/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "audience_segments": {"method": "auto", "segment_list": []},
  "budget": 1000000,
  "created_at": "2025-04-15 15:15:27.916514",
  "description": "This is a example campaign",
  "end_date": "2025-05-15 15:15:27.916516",
  "goal": "impression",
  "name": "Maximize Impression",
  "owner_id": "4f45b2ba-c3dd-4ad9-9e5a-669bf0b0c396",
  "start_date": "2025-04-15 15:15:27.916519",
  "status": "okay",
  "sub_goal": "maximize_volume",
  "updated_at": "2025-04-15 15:15:27.916520"
}'

Created Campaign Response
{
  "audience_segments": {
    "method": "auto",
    "segment_list": []
  },
  "bid_strategy": "highest_volume",
  "budget": 1000000,
  "created_at": "2025-04-15 15:15:27.916514",
  "daily_budget": 0,
  "description": "campaign description",
  "end_date": "2025-05-15 15:15:27.916516",
  "goal": "impression",
  "id": "ab9dc64a-d4a9-40c6-816f-61d49c4cb68e",
  "max_bid": 0,
  "min_daily_imp": 1000,
  "name": "test campaign",
  "no": 12,
  "owner_id": "0741e2d5-6aed-4994-8498-493c6a84bb66",
  "start_date": "2025-04-15 15:15:27.916519",
  "status": "okay",
  "sub_goal": "maximize_volume",
  "target_cpa": 0,
  "target_cpm": 0,
  "target_volume": 0,
  "updated_at": "2025-04-15 15:15:27.916520"
}

Create Creative

We will register the advertising creative that will be shown on the placement when the campaign is served. Campaign creatives can include images, videos, or native ads, among others.

Note: The types of creatives allowed may differ depending on the placement.

API: Create a creative
curl --request POST \
  --url https://your_a2_service/api/creatives \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "test creative",
  "type": "banner",
  "staatus": "active",
  "width": 300,
  "height": 100,
  "banner": {
    "img": "https://example.com/creative.png"
  },
  "cid": "ab9dc64a-d4a9-40c6-816f-61d49c4cb68e",
  "owner_id": "4f45b2ba-c3dd-4ad9-9e5a-669bf0b0c396"
}'

Request Publish

Once the campaign and creatives are registered, you can request ad serving on the placement where you wish to run the campaign. At least one creative must be active and must match the format of the targeted placement.

Create a new allocation to submit the publishing request.

API: Create an allocation
curl --request POST \
  --url https://your_a2_service/api/allocations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tagid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "cid": "ab9dc64a-d4a9-40c6-816f-61d49c4cb68e",
  "owner_id": "4f45b2ba-c3dd-4ad9-9e5a-669bf0b0c396"
}'

Approval and Rejection of Publishing Requests

The requested placement for ad serving requires approval. The creative or links used in the campaign may not comply with the placement’s settings or internal operating guidelines. If, based on the review, the campaign is approved or rejected, you can update its status using the Campaign Information Update API. You can also communicate the reason for rejection by setting last_comment field.

Status Code

code	description
pending	Initial state
requested	publish requested
published	published
rejected	Rejected
canceled	canceled
finished	finished

API: Update an allocation
curl --request PATCH \
  --url https://your_a2_service/api/allocations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tagid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "published",
  "cid": "ab9dc64a-d4a9-40c6-816f-61d49c4cb68e",
  "owner_id": "4f45b2ba-c3dd-4ad9-9e5a-669bf0b0c396"
}'

Campaign Launch and Performance Measurement

Once your campaign is approved, the ad will start showing immediately. Campaign metrics are collected and managed for each ad served. This data can help to be more effective campaign strategy.

Performance Analysis

You can assess a campaign’s performance using APIs that provide data for any desired time interval, such as daily or hourly.

API: Get a campaign hourly metric
curl --request POST \
  --url https://your_a2_service/metric/campaigns_hourly \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "campaign_id": "ab9dc64a-d4a9-40c6-816f-61d49c4cb68e",
  "tagid": "123e4567-e89b-12d3-a456-426614174000",
  "from_datetime": "2025-04-14 16:47:03.773",
  "to_datetime": "2025-04-15 16:47:03.773"
}'

Tutorial

General

A2 OnPrem

Publishing an Ad Campaign via API

Introduction

Create Placement

Create Campaign

Create Creative

Request Publish

Approval and Rejection of Publishing Requests

Status Code

Campaign Launch and Performance Measurement

Performance Analysis

Tutorial

General

A2 OnPrem

​Introduction

​Create Placement

​Create Campaign

​Create Creative

​Request Publish

​Approval and Rejection of Publishing Requests

​Status Code

​Campaign Launch and Performance Measurement

​Performance Analysis

Introduction

Create Placement

Create Campaign

Create Creative

Request Publish

Approval and Rejection of Publishing Requests

Status Code

Campaign Launch and Performance Measurement

Performance Analysis