Create a standalone campaign
curl --request POST \
--url https://api.aisa.one/apis/v1/ads/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"adAccountId": "act_757082720485182",
"goal": "app_promotion",
"name": "iOS app campaign"
}
'import requests
url = "https://api.aisa.one/apis/v1/ads/campaigns"
payload = {
"adAccountId": "act_757082720485182",
"goal": "app_promotion",
"name": "iOS app campaign"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
adAccountId: 'act_757082720485182',
goal: 'app_promotion',
name: 'iOS app campaign'
})
};
fetch('https://api.aisa.one/apis/v1/ads/campaigns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/campaigns",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'adAccountId' => 'act_757082720485182',
'goal' => 'app_promotion',
'name' => 'iOS app campaign'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.aisa.one/apis/v1/ads/campaigns"
payload := strings.NewReader("{\n \"adAccountId\": \"act_757082720485182\",\n \"goal\": \"app_promotion\",\n \"name\": \"iOS app campaign\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/ads/campaigns")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"adAccountId\": \"act_757082720485182\",\n \"goal\": \"app_promotion\",\n \"name\": \"iOS app campaign\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/campaigns")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"adAccountId\": \"act_757082720485182\",\n \"goal\": \"app_promotion\",\n \"name\": \"iOS app campaign\"\n}"
response = http.request(request)
puts response.read_body{
"adAccountId": "<string>",
"campaignId": "",
"objective": "<string>",
"status": "VALIDATED",
"validateOnly": true
}{
"adAccountId": "<string>",
"campaignId": "<string>",
"objective": "<string>",
"status": "ACTIVE"
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}AIsa Ads
Create a standalone campaign
Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Creates a campaign on the ad platform; with a budget and an active status it starts spending. validateOnly=true checks the request without acting and needs no confirmation. Creates an empty campaign, paused, so you can add ad sets and ads to it afterwards. Creates a campaign WITHOUT its first ad set / ad, on the platform of the given `connectionId`. Ad sets join it later via `existingCampaignId` on the create endpoints. Created `PAUSED` (TikTok `DISABLE`) unless `status: ACTIVE` where the platform supports it.
<!-- aisa-pricing:start -->
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.
<!-- aisa-pricing:end -->
POST
https://api.aisa.one
/
apis
/
v1
/
ads
/
campaigns
Create a standalone campaign
curl --request POST \
--url https://api.aisa.one/apis/v1/ads/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"adAccountId": "act_757082720485182",
"goal": "app_promotion",
"name": "iOS app campaign"
}
'import requests
url = "https://api.aisa.one/apis/v1/ads/campaigns"
payload = {
"adAccountId": "act_757082720485182",
"goal": "app_promotion",
"name": "iOS app campaign"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
adAccountId: 'act_757082720485182',
goal: 'app_promotion',
name: 'iOS app campaign'
})
};
fetch('https://api.aisa.one/apis/v1/ads/campaigns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/campaigns",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'adAccountId' => 'act_757082720485182',
'goal' => 'app_promotion',
'name' => 'iOS app campaign'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.aisa.one/apis/v1/ads/campaigns"
payload := strings.NewReader("{\n \"adAccountId\": \"act_757082720485182\",\n \"goal\": \"app_promotion\",\n \"name\": \"iOS app campaign\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/ads/campaigns")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"adAccountId\": \"act_757082720485182\",\n \"goal\": \"app_promotion\",\n \"name\": \"iOS app campaign\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/campaigns")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"adAccountId\": \"act_757082720485182\",\n \"goal\": \"app_promotion\",\n \"name\": \"iOS app campaign\"\n}"
response = http.request(request)
puts response.read_body{
"adAccountId": "<string>",
"campaignId": "",
"objective": "<string>",
"status": "VALIDATED",
"validateOnly": true
}{
"adAccountId": "<string>",
"campaignId": "<string>",
"objective": "<string>",
"status": "ACTIVE"
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}Request contract
- Method and path: POST /apis/v1/ads/campaigns
- Availability: enabled
- Request URL template:
https://api.aisa.one/apis/v1/ads/campaigns - connectionId: query; required
- X-Aisa-Confirm: header; optional
- Idempotency-Key: header; optional
- Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09
{
"operationId": "post_aisa_ads_apis_v1_ads_campaigns",
"method": "POST",
"path": "/apis/v1/ads/campaigns",
"servers": [
{
"url": "https://api.aisa.one"
}
],
"parameters": [
{
"description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
"in": "query",
"name": "connectionId",
"required": true,
"schema": {
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
}
},
{
"description": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.",
"in": "header",
"name": "X-Aisa-Confirm",
"required": false,
"schema": {
"enum": [
"spend"
],
"type": "string"
}
},
{
"description": "Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"maxLength": 191,
"minLength": 1,
"type": "string"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"adAccountId": "act_757082720485182",
"buyingType": "AUCTION",
"connectionId": "adc_7f3k2m9q",
"goal": "app_promotion",
"isSkadnetworkAttribution": true,
"name": "iOS app campaign",
"promotedObject": {
"applicationId": "123456789",
"objectStoreUrl": "https://apps.apple.com/us/app/id123456789"
},
"status": "PAUSED",
"validateOnly": true
},
"schema": {
"additionalProperties": true,
"properties": {
"adAccountId": {
"description": "Platform ad account id (Meta act_, Google customer id, LinkedIn account id, ...).",
"type": "string"
},
"bidAmount": {
"description": "Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. Meta: validated here but NOT stored, since the campaign object only has bid_strategy.",
"type": "number"
},
"bidStrategy": {
"description": "Campaign bid strategy. Meta stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request (400 without a campaign budget).",
"enum": [
"LOWEST_COST_WITHOUT_CAP",
"LOWEST_COST_WITH_BID_CAP",
"COST_CAP",
"LOWEST_COST_WITH_MIN_ROAS"
],
"type": "string"
},
"budgetAmount": {
"description": "Campaign-level (CBO) budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Requires budgetType.",
"type": "number"
},
"budgetType": {
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"buyingType": {
"description": "Every platform buys at auction by default, so this only needs sending on Meta, and only to choose RESERVED. `AUCTION` is accepted on every platform and changes nothing.",
"enum": [
"AUCTION",
"RESERVED"
],
"type": "string"
},
"connectionId": {
"description": "The ads connection (adc_...), when not sent as the connectionId query parameter.",
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
},
"endDate": {
"description": "Reddit only (400 elsewhere). Campaign end (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (400 otherwise), and is required for `budgetType: lifetime`.",
"format": "date-time",
"type": "string"
},
"goal": {
"description": "Mapped to the ODAX objective (same mapping as POST /apis/v1/ads/create).",
"enum": [
"engagement",
"traffic",
"awareness",
"video_views",
"lead_generation",
"lead_conversion",
"job_applicants",
"conversions",
"app_promotion",
"catalog_sales",
"page_likes",
"page_visits"
],
"type": "string"
},
"isSkadnetworkAttribution": {
"description": "Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true.",
"type": "boolean"
},
"locationTargetingType": {
"description": "Google only (400 elsewhere). Written on the new campaign.",
"enum": [
"presence",
"presence_or_interest"
],
"type": "string"
},
"manualCpc": {
"additionalProperties": false,
"description": "Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field.",
"properties": {
"maxCpc": {
"description": "Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid.",
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"maxCpc"
],
"type": "object"
},
"name": {
"maxLength": 255,
"type": "string"
},
"networkSettings": {
"additionalProperties": false,
"description": "Google Search campaigns only. Which networks the campaign serves on besides Google Search.",
"properties": {
"displayNetwork": {
"description": "campaign.network_settings.target_content_network (Search with Display expansion)",
"type": "boolean"
},
"searchPartners": {
"description": "campaign.network_settings.target_search_network",
"type": "boolean"
}
},
"type": "object"
},
"portfolioBidStrategyId": {
"description": "Google only. Attach an existing portfolio bid strategy (numeric id from GET /apis/v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy.",
"pattern": "^\\d+$",
"type": "string"
},
"promotedObject": {
"additionalProperties": false,
"description": "What the ad optimises against. Behaviour depends on the platform. Platforms other than Meta, TikTok, OpenAI and Reddit ignore `promotedObject` entirely. Meta: forwarded to the ad set's `promoted_object` (snake-cased).",
"properties": {
"applicationId": {
"description": "App ID. Required for `goal: app_promotion`.",
"type": "string"
},
"customConversionId": {
"description": "Custom Conversion ID, when optimising against one instead of a standard event. Accepted alone by this API, without `pixelId` or `customEventType`.",
"type": "string"
},
"customEventStr": {
"description": "Meta only. Pixel custom-event name to optimise against (Meta's `custom_event_str`), exactly as it appears in Events Manager and your CAPI payloads (case-sensitive, not uppercased).",
"type": "string"
},
"customEventType": {
"description": "The event the campaign/ad group optimises against. Meta: a standard event like `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`, `ADD_TO_CART`. Uppercased internally, so any case works. Required for `goal: conversions`.",
"type": "string"
},
"objectStoreUrl": {
"description": "App Store / Play Store listing URL. Required for `goal: app_promotion`.",
"format": "uri",
"type": "string"
},
"offlineConversionDataSetId": {
"description": "Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id).",
"type": "string"
},
"pageId": {
"description": "Facebook Page ID. Used by `goal: lead_generation`. Auto-filled from the connected Page when omitted.",
"type": "string"
},
"pixelId": {
"description": "Pixel ID. Meta: Facebook Pixel ID, required for `goal: conversions`.",
"type": "string"
},
"productCatalogId": {
"description": "Optional catalog ID. A catalog ID cannot replace productSetId.",
"type": "string"
},
"productSetId": {
"description": "Meta product SET ID, for example from GET /apis/v1/ads/catalogs/{catalogId}/product-sets. Creating catalog ads needs only ads_management on the Meta login, not catalog_management. Where it goes.",
"type": "string"
},
"whatsappPhoneNumber": {
"description": "Meta only. WhatsApp number on messaging-destination ad sets.",
"type": "string"
}
},
"type": "object"
},
"roasAverageFloor": {
"description": "Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS.",
"type": "number"
},
"specialAdCategories": {
"items": {
"enum": [
"HOUSING",
"EMPLOYMENT",
"CREDIT",
"ISSUES_ELECTIONS_POLITICS",
"FINANCIAL_PRODUCTS_SERVICES",
"ONLINE_GAMBLING_AND_GAMING"
],
"type": "string"
},
"type": "array"
},
"startDate": {
"description": "Reddit only (400 elsewhere). Campaign start (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (`budgetAmount` + `budgetType`, 400 otherwise). Defaults to now.",
"format": "date-time",
"type": "string"
},
"status": {
"default": "PAUSED",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"targetImpressionShare": {
"additionalProperties": false,
"description": "Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc).",
"properties": {
"location": {
"enum": [
"ANYWHERE_ON_PAGE",
"TOP_OF_PAGE",
"ABSOLUTE_TOP_OF_PAGE"
],
"type": "string"
},
"maxCpc": {
"description": "Max CPC bid limit, in the account's currency units. Google requires it.",
"exclusiveMinimum": 0,
"type": "number"
},
"percent": {
"description": "Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000).",
"exclusiveMinimum": 0,
"maximum": 100,
"type": "number"
}
},
"required": [
"location",
"maxCpc",
"percent"
],
"type": "object"
},
"validateOnly": {
"description": "Meta and ChatGPT (OpenAI). Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED.",
"type": "boolean"
}
},
"required": [
"adAccountId",
"goal",
"name"
],
"type": "object"
}
}
},
"required": true
},
"x-aisa-status": "enabled",
"x-aisa-pricing": {
"description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
"kind": "no_customer_charge"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"scheme": "bearer",
"type": "http"
}
}
}
}
Cost and request rules
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.
Available options:
spend Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.
Required string length:
1 - 191Query Parameters
The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.
Pattern:
^adc_[0-9A-Za-z]+$Body
application/json
Platform ad account id (Meta act_, Google customer id, LinkedIn account id, ...).
Mapped to the ODAX objective (same mapping as POST /apis/v1/ads/create).
Available options:
engagement, traffic, awareness, video_views, lead_generation, lead_conversion, job_applicants, conversions, app_promotion, catalog_sales, page_likes, page_visits Maximum string length:
255Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. Meta: validated here but NOT stored, since the campaign object only has bid_strategy.
Campaign bid strategy. Meta stores bid_strategy alongside the budget, so this REQUIRES budgetAmount + budgetType on the same request (400 without a campaign budget).
Available options:
LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS Campaign-level (CBO) budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Requires budgetType.
Available options:
daily, lifetime Every platform buys at auction by default, so this only needs sending on Meta, and only to choose RESERVED. AUCTION is accepted on every platform and changes nothing.
Available options:
AUCTION, RESERVED The ads connection (adc_...), when not sent as the connectionId query parameter.
Pattern:
^adc_[0-9A-Za-z]+$Reddit only (400 elsewhere). Campaign end (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (400 otherwise), and is required for budgetType: lifetime.
Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true.
Google only (400 elsewhere). Written on the new campaign.
Available options:
presence, presence_or_interest Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field.
Show child attributes
Show child attributes
Google Search campaigns only. Which networks the campaign serves on besides Google Search.
Show child attributes
Show child attributes
Google only. Attach an existing portfolio bid strategy (numeric id from GET /apis/v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy.
Pattern:
^\d+$What the ad optimises against. Behaviour depends on the platform. Platforms other than Meta, TikTok, OpenAI and Reddit ignore promotedObject entirely. Meta: forwarded to the ad set's promoted_object (snake-cased).
Show child attributes
Show child attributes
Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS.
Available options:
HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCTS_SERVICES, ONLINE_GAMBLING_AND_GAMING Reddit only (400 elsewhere). Campaign start (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (budgetAmount + budgetType, 400 otherwise). Defaults to now.
Available options:
ACTIVE, PAUSED Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc).
Show child attributes
Show child attributes
Meta and ChatGPT (OpenAI). Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED.