Skip to content

AdsApi.md

Latest commit

 

History

History
811 lines (577 loc) · 24.9 KB

AdsApi.md

File metadata and controls

811 lines (577 loc) · 24.9 KB

Zernio::AdsApi

All URIs are relative to https://zernio.com/api

Method HTTP request Description
boost_post POST /v1/ads/boost Boost post as ad
create_standalone_ad POST /v1/ads/create Create standalone ad
delete_ad DELETE /v1/ads/{adId} Cancel an ad
get_ad GET /v1/ads/{adId} Get ad details
get_ad_analytics GET /v1/ads/{adId}/analytics Get ad analytics
list_ad_accounts GET /v1/ads/accounts List ad accounts
list_ads GET /v1/ads List ads
list_conversion_destinations GET /v1/accounts/{accountId}/conversion-destinations List destinations for the Conversions API
search_ad_interests GET /v1/ads/interests Search targeting interests
send_conversions POST /v1/ads/conversions Send conversion events to an ad platform
update_ad PUT /v1/ads/{adId} Update ad

boost_post

boost_post(boost_post_request)

Boost post as ad

Creates a paid ad campaign from an existing published post. Creates the full platform campaign hierarchy (campaign, ad set, ad).

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
boost_post_request = Zernio::BoostPostRequest.new({account_id: 'account_id_example', ad_account_id: 'ad_account_id_example', name: 'name_example', goal: 'engagement', budget: Zernio::BoostPostRequestBudget.new({amount: 3.56, type: 'daily'})}) # BoostPostRequest | 

begin
  # Boost post as ad
  result = api_instance.boost_post(boost_post_request)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->boost_post: #{e}"
end

Using the boost_post_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> boost_post_with_http_info(boost_post_request)

begin
  # Boost post as ad
  data, status_code, headers = api_instance.boost_post_with_http_info(boost_post_request)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <UpdateAd200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->boost_post_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
boost_post_request BoostPostRequest

Return type

UpdateAd200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

create_standalone_ad

create_standalone_ad(create_standalone_ad_request)

Create standalone ad

Creates a paid ad with custom creative. The request body supports three mutually-exclusive shapes: 1. Legacy single-creative (all platforms). Top-level headline + body + imageUrl + linkUrl + callToAction create 1 campaign + 1 ad set + 1 ad. 2. Multi-creative (Meta only — use creatives[] array). Creates 1 campaign + 1 ad set + N ads sharing the same budget / targeting / schedule. This is the standard performance-marketing creative-testing flow — Meta's delivery algorithm A/B tests the creatives inside a single ad set so budget isn't fragmented across N parallel campaigns. 3. Attach to existing ad set (Meta only — pass adSetId + a single creative). Adds one new ad to an existing ad set without creating a new campaign. Budget, targeting, goal are inherited from the ad set on Meta. creatives[] and adSetId are mutually exclusive; specifying both returns 400.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
create_standalone_ad_request = Zernio::CreateStandaloneAdRequest.new({account_id: 'account_id_example', ad_account_id: 'ad_account_id_example', name: 'name_example'}) # CreateStandaloneAdRequest | 

begin
  # Create standalone ad
  result = api_instance.create_standalone_ad(create_standalone_ad_request)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->create_standalone_ad: #{e}"
end

Using the create_standalone_ad_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> create_standalone_ad_with_http_info(create_standalone_ad_request)

begin
  # Create standalone ad
  data, status_code, headers = api_instance.create_standalone_ad_with_http_info(create_standalone_ad_request)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <CreateStandaloneAd201Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->create_standalone_ad_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
create_standalone_ad_request CreateStandaloneAdRequest

Return type

CreateStandaloneAd201Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

delete_ad

delete_ad(ad_id)

Cancel an ad

Cancels the ad on the platform and marks it as cancelled in the database. The ad is preserved for history.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
ad_id = 'ad_id_example' # String | 

begin
  # Cancel an ad
  result = api_instance.delete_ad(ad_id)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->delete_ad: #{e}"
end

Using the delete_ad_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> delete_ad_with_http_info(ad_id)

begin
  # Cancel an ad
  data, status_code, headers = api_instance.delete_ad_with_http_info(ad_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <DeleteAccountGroup200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->delete_ad_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
ad_id String

Return type

DeleteAccountGroup200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

get_ad

get_ad(ad_id)

Get ad details

Returns an ad with its creative, targeting, status, and performance metrics.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
ad_id = 'ad_id_example' # String | 

begin
  # Get ad details
  result = api_instance.get_ad(ad_id)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->get_ad: #{e}"
end

Using the get_ad_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> get_ad_with_http_info(ad_id)

begin
  # Get ad details
  data, status_code, headers = api_instance.get_ad_with_http_info(ad_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <GetAd200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->get_ad_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
ad_id String

Return type

GetAd200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

get_ad_analytics

get_ad_analytics(ad_id, opts)

Get ad analytics

Returns detailed performance analytics for an ad. Includes summary metrics, a daily timeline over the requested date range, and optional demographic breakdowns (Meta and TikTok only). If no date range is provided, defaults to the last 90 days. Date range is capped at 90 days max.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
ad_id = 'ad_id_example' # String | 
opts = {
  from_date: Date.parse('2013-10-20'), # Date | Start of date range (YYYY-MM-DD). Defaults to 90 days ago.
  to_date: Date.parse('2013-10-20'), # Date | End of date range (YYYY-MM-DD). Defaults to today. Max 90-day range.
  breakdowns: 'breakdowns_example' # String | Comma-separated breakdown dimensions. Meta: age, gender, country, publisher_platform, device_platform, region. TikTok: gender, age, country_code, platform, ac, language.
}

begin
  # Get ad analytics
  result = api_instance.get_ad_analytics(ad_id, opts)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->get_ad_analytics: #{e}"
end

Using the get_ad_analytics_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> get_ad_analytics_with_http_info(ad_id, opts)

begin
  # Get ad analytics
  data, status_code, headers = api_instance.get_ad_analytics_with_http_info(ad_id, opts)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <GetAdAnalytics200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->get_ad_analytics_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
ad_id String
from_date Date Start of date range (YYYY-MM-DD). Defaults to 90 days ago. [optional]
to_date Date End of date range (YYYY-MM-DD). Defaults to today. Max 90-day range. [optional]
breakdowns String Comma-separated breakdown dimensions. Meta: age, gender, country, publisher_platform, device_platform, region. TikTok: gender, age, country_code, platform, ac, language. [optional]

Return type

GetAdAnalytics200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

list_ad_accounts

list_ad_accounts(account_id)

List ad accounts

Returns the platform ad accounts available for the given social account (e.g. Meta ad accounts, TikTok advertiser IDs, Google Ads customer IDs).

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
account_id = 'account_id_example' # String | Social account ID

begin
  # List ad accounts
  result = api_instance.list_ad_accounts(account_id)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->list_ad_accounts: #{e}"
end

Using the list_ad_accounts_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> list_ad_accounts_with_http_info(account_id)

begin
  # List ad accounts
  data, status_code, headers = api_instance.list_ad_accounts_with_http_info(account_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ListAdAccounts200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->list_ad_accounts_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
account_id String Social account ID

Return type

ListAdAccounts200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

list_ads

list_ads(opts)

List ads

Returns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers. If no date range is provided, defaults to the last 90 days. Date range is capped at 90 days max.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
opts = {
  page: 56, # Integer | Page number (1-based)
  limit: 56, # Integer | 
  source: 'zernio', # String | all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.
  status: Zernio::AdStatus::ACTIVE, # AdStatus | 
  platform: 'facebook', # String | 
  account_id: 'account_id_example', # String | Social account ID
  ad_account_id: 'ad_account_id_example', # String | Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.
  profile_id: 'profile_id_example', # String | Profile ID
  campaign_id: 'campaign_id_example', # String | Platform campaign ID (filter ads within a campaign)
  from_date: Date.parse('2013-10-20'), # Date | Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
  to_date: Date.parse('2013-10-20') # Date | End of metrics date range (YYYY-MM-DD). Defaults to today. Max 90-day range.
}

begin
  # List ads
  result = api_instance.list_ads(opts)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->list_ads: #{e}"
end

Using the list_ads_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> list_ads_with_http_info(opts)

begin
  # List ads
  data, status_code, headers = api_instance.list_ads_with_http_info(opts)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ListAds200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->list_ads_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
page Integer Page number (1-based) [optional][default to 1]
limit Integer [optional][default to 50]
source String all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only. [optional][default to 'all']
status AdStatus [optional]
platform String [optional]
account_id String Social account ID [optional]
ad_account_id String Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree. [optional]
profile_id String Profile ID [optional]
campaign_id String Platform campaign ID (filter ads within a campaign) [optional]
from_date Date Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago. [optional]
to_date Date End of metrics date range (YYYY-MM-DD). Defaults to today. Max 90-day range. [optional]

Return type

ListAds200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

list_conversion_destinations

list_conversion_destinations(account_id)

List destinations for the Conversions API

Returns the list of pixels (Meta) or conversion actions (Google) accessible to the connected ads account. Use the returned id as destinationId when posting to POST /v1/ads/conversions. For Google, each destination's type reflects the conversion action's category (PURCHASE, LEAD, SIGN_UP, etc.) — the event type is locked to the destination. For Meta, type is absent: pixels accept any event name per request.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
account_id = 'account_id_example' # String | SocialAccount ID (metaads or googleads).

begin
  # List destinations for the Conversions API
  result = api_instance.list_conversion_destinations(account_id)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->list_conversion_destinations: #{e}"
end

Using the list_conversion_destinations_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> list_conversion_destinations_with_http_info(account_id)

begin
  # List destinations for the Conversions API
  data, status_code, headers = api_instance.list_conversion_destinations_with_http_info(account_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ListConversionDestinations200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->list_conversion_destinations_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
account_id String SocialAccount ID (metaads or googleads).

Return type

ListConversionDestinations200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

search_ad_interests

search_ad_interests(q, account_id)

Search targeting interests

Search for interest-based targeting options available on the platform.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
q = 'q_example' # String | Search query
account_id = 'account_id_example' # String | Social account ID

begin
  # Search targeting interests
  result = api_instance.search_ad_interests(q, account_id)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->search_ad_interests: #{e}"
end

Using the search_ad_interests_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> search_ad_interests_with_http_info(q, account_id)

begin
  # Search targeting interests
  data, status_code, headers = api_instance.search_ad_interests_with_http_info(q, account_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <SearchAdInterests200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->search_ad_interests_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
q String Search query
account_id String Social account ID

Return type

SearchAdInterests200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

send_conversions

send_conversions(send_conversions_request)

Send conversion events to an ad platform

Relay one or more conversion events to the target ad platform's native Conversions API. Supported platforms: Meta (metaads) via Graph API, Google Ads (googleads) via Data Manager API ingestEvents. Platform is inferred from the provided accountId. destinationId semantics differ per platform: - Meta: pixel (dataset) ID, e.g. "123456789012345" - Google: conversion action resource name, e.g. "customers/1234567890/conversionActions/987654321" Callers can list valid destinations via GET /v1/accounts/{accountId}/conversion-destinations. All PII (email, phone, names, external IDs) is hashed with SHA-256 server-side per each platform's normalization spec (including Google's Gmail-specific dot/plus-suffix stripping). Send plaintext. Requires the Ads add-on. Batching: Meta caps at 1000 events per request and rejects the entire batch if any event is malformed. Google caps at 2000. Both are handled automatically by chunking. Dedup: pass a stable eventId on every event. Meta uses it to dedupe against pixel events; Google maps it to transactionId.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
send_conversions_request = Zernio::SendConversionsRequest.new({account_id: 'account_id_example', destination_id: 'destination_id_example', events: [Zernio::ConversionEvent.new({event_name: 'Purchase', event_time: 1744732800, event_id: 'order_abc_123', user: Zernio::ConversionEventUser.new})]}) # SendConversionsRequest | 

begin
  # Send conversion events to an ad platform
  result = api_instance.send_conversions(send_conversions_request)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->send_conversions: #{e}"
end

Using the send_conversions_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> send_conversions_with_http_info(send_conversions_request)

begin
  # Send conversion events to an ad platform
  data, status_code, headers = api_instance.send_conversions_with_http_info(send_conversions_request)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <SendConversions200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->send_conversions_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
send_conversions_request SendConversionsRequest

Return type

SendConversions200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

update_ad

update_ad(ad_id, update_ad_request)

Update ad

Update one or more fields on an ad. Status changes and budget updates are propagated to the platform. Targeting updates are Meta-only.

Examples

require 'time'
require 'zernio-sdk'
# setup authorization
Zernio.configure do |config|
  # Configure Bearer authorization (JWT): bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = Zernio::AdsApi.new
ad_id = 'ad_id_example' # String | 
update_ad_request = Zernio::UpdateAdRequest.new # UpdateAdRequest | 

begin
  # Update ad
  result = api_instance.update_ad(ad_id, update_ad_request)
  p result
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->update_ad: #{e}"
end

Using the update_ad_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> update_ad_with_http_info(ad_id, update_ad_request)

begin
  # Update ad
  data, status_code, headers = api_instance.update_ad_with_http_info(ad_id, update_ad_request)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <UpdateAd200Response>
rescue Zernio::ApiError => e
  puts "Error when calling AdsApi->update_ad_with_http_info: #{e}"
end

Parameters

Name Type Description Notes
ad_id String
update_ad_request UpdateAdRequest

Return type

UpdateAd200Response

Authorization

bearerAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json