SmallForce CLI: Meta Ads commands
Manage Meta, Google, and TikTok Ads through organization-scoped SmallForce resources
This page covers 148 smallforce ads commands. It is generated from SmallForce CLI 0.1.17; run smallforce ads --help (or any command with --help) to see the same reference for the version you have installed. New to the CLI? Start with installation and authentication and JSON output.
Agent workflow:
Google Ads:
ads google --help
TikTok Ads:
ads tiktok --help
Meta Ads (existing top-level commands):
1. social profiles list
Reuse the profile that owns the Facebook or Instagram connection.
2. ads connections connect --profile <profileId> --via facebook
Share authUrl when returned; same-token connections may complete immediately.
3. ads connections list --json
Resolve the ads connection id and inspect its activation state.
4. ads connections activate <socialAccountId>
Activate the monthly advertising connection when required.
5. ads accounts sync <socialAccountId>
Import the Meta ad accounts visible to that connection.
6. ads accounts list --json
Use the returned local ad-account id as --account.
7. ads targeting search "<audience>" --account <adAccountId>
8. ads campaigns validate --input-file draft.json
9. ads campaigns create --input-file draft.json
To see what needs attention across Meta, Google, and TikTok (rejected ads,
delivery issues, payment problems, spend without results, capped budgets, lost
connections, failing syncs), run ads alerts list.
For asynchronous Meta Insights, use ads reports create, then ads reports wait
with the returned local report ID. Use ads reports get to page completed rows.
Meta campaigns are created paused. Run campaigns preflight before changing a
campaign to active. Complex mutation payloads accept --input '<json>',
--input-file <path>, or --input-file - for stdin.
Every leaf command supports --json. Use each leaf's --help for ID sources,
payload shapes, safety notes, and next commands. Google Ads and TikTok Ads live
under their explicit provider namespaces; existing top-level ads commands are
Meta Ads.
Common options
Most commands accept these options as well as their own. Every command also accepts -h, --help.
| Option | Description |
|---|---|
--api-key <key> | SmallForce API key, or set SMALLFORCE_API_KEY |
--backend-url <url> | SmallForce backend URL, or set SMALLFORCE_BACKEND_URL |
--json | Print stable machine-readable JSON |
--text | Print human-readable text |
--format <format> | Output format: text or json |
smallforce ads connections
Connect and activate Meta Ads credentials
smallforce ads connections connect
Create or reuse a Meta Ads connection
Usage: smallforce ads connections connect [options]
| Option | Description |
|---|---|
--profile <profileId> | Social profile id from social profiles list |
--via <platform> | Parent platform: facebook or instagram (default: “facebook”) |
--provider-account <actId> | Limit provider sync to one act_ |
--redirect-url <url> | Browser destination after authorization |
--login-mode <mode> | Meta authorization: classic or business |
--page-id <id> | Granted Meta Page ID for business login |
--force | Start a fresh authorization |
--headless | Request a headless provider authorization flow |
Also accepts the common options listed at the top of this page.
Examples:
$ smallforce ads connections connect --profile <profileId> --via facebook
$ smallforce ads connections connect --profile <profileId> --via instagram --provider-account act_123 --json
Meta uses the existing Facebook or Instagram token when possible. Share authUrl
if one is returned. The returned socialAccountId identifies the ads connection,
not an individual Meta ad account.
smallforce ads connections list
List Meta Ads connections and activation state
Usage: smallforce ads connections list [options]
| Option | Description |
|---|---|
--profile <profileId> | Filter by one social profile |
--include-deleted | Include disconnected connections |
Also accepts the common options listed at the top of this page.
Use the returned local connection ID with connections activate, accounts sync,
or connections disconnect.
Example:
$ smallforce ads connections list --json
smallforce ads connections activate
Activate billing for one Meta Ads connection
Usage: smallforce ads connections activate [options] <socialAccountId>
| Argument | Description |
|---|---|
socialAccountId | Local connection id |
Also accepts the common options listed at the top of this page.
The plan includes 5 connected accounts (social accounts and ad connections
together). Inside that allowance this charges nothing; beyond it, it charges the
monthly extra-account rate in SmallForce Credits. It is idempotent while the
current billing period is active.
Next:
ads accounts sync <socialAccountId>
smallforce ads connections disconnect
Disconnect one Meta Ads credential
Usage: smallforce ads connections disconnect [options] <socialAccountId>
| Argument | Description |
|---|---|
socialAccountId | Local connection id |
Also accepts the common options listed at the top of this page.
This disconnects the provider credential and marks its local connection
inactive. It is safe to repeat after a confirmed disconnect.
Example:
$ smallforce ads connections disconnect <socialAccountId>
smallforce ads accounts
Synchronize and inspect Meta Ads accounts
smallforce ads accounts list
List local Meta Ads account IDs
Usage: smallforce ads accounts list [options]
| Option | Description |
|---|---|
--connection <socialAccountId> | Filter by one Meta Ads connection |
Also accepts the common options listed at the top of this page.
Examples:
$ smallforce ads accounts list
$ smallforce ads accounts list --connection <socialAccountId> --json
Use each returned ID as --account in Meta Ads operation commands.
smallforce ads accounts sync
Synchronize provider accounts for one Meta Ads connection
Usage: smallforce ads accounts sync [options] <socialAccountId>
| Argument | Description |
|---|---|
socialAccountId | Local connection id |
Also accepts the common options listed at the top of this page.
Examples:
$ smallforce ads accounts sync <socialAccountId>
$ smallforce ads accounts sync <socialAccountId> --json
Next:
ads accounts list --connection <socialAccountId>
smallforce ads accounts create
Create a Meta ad account in your business portfolio
Usage: smallforce ads accounts create [options]
| Option | Description |
|---|---|
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Input: {"socialAccountId":"<local connection UUID>","businessId":"<Meta business ID>","name":"My business","currency":"USD","timezoneId":1,"idempotencyKey":"<UUID>"}
Use Meta numeric timezone IDs. Payment setup remains in Meta. Keep the same key when checking a previous attempt; do not repeat an uncertain creation with a new key.
smallforce ads accounts live
Get ad account live entities
Usage: smallforce ads accounts live [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.status (optional): string
Comma-separated Meta `effective_status` values to keep: ACTIVE, PAUSED, IN_PROCESS, WITH_ISSUES, DELETED, ARCHIVED, and CAMPAIGN_PAUSED (ad sets only; the campaigns level ignores it). Defaults to every status except DELETED and...
query.level (optional): "campaign" | "adSet"
Read only one level. Required with `after`. Both levels are read when omitted.
query.limit (optional): integer
Maximum rows per level in this response.
query.after (optional): string
Cursor from `paging.campaigns.after` or `paging.adSets.after` of a previous response.
Request skeleton:
{
"query": {
"status": "PAUSED"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts activity
Read the Meta ad-account activity log
Usage: smallforce ads accounts activity [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.since (optional): string(date)
Start of range (YYYY-MM-DD).
query.until (optional): string(date)
End of range (YYYY-MM-DD).
query.objectId (optional): local campaign, ad_set, or ad reference
Client-side filter to one object id (campaign, ad set / ad group or ad). Use a SmallForce-local campaign, ad_set, or ad reference; raw provider IDs are rejected.
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"since": "2026-08-01",
"until": "2026-08-01"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts studies
List Meta ad studies
Usage: smallforce ads accounts studies [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fields (optional): string
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"fields": "<fields>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts businesses
List Meta businesses visible to the connection
Usage: smallforce ads accounts businesses [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"limit": 25
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts labels
List Meta ad-account labels
Usage: smallforce ads accounts labels [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
Meta only. Rows per page.
query.after (optional): string
Meta only. Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"limit": 25
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts high-demand-periods
List high-demand periods for a campaign or ad set
Usage: smallforce ads accounts high-demand-periods [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local campaign or ad-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--target-kind <kind> | campaign or ad_set |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"limit": 25
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts create-high-demand-period
Create a Meta high-demand period
Usage: smallforce ads accounts create-high-demand-period [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local campaign or ad-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--target-kind <kind> | campaign or ad_set |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.budgetValue (required): number
With ABSOLUTE, a budget in the ad account's currency in WHOLE units (50 = $50.00). With MULTIPLIER, a factor of the existing budget (2 = double it) and NOT a currency amount.
body.budgetValueType (required): "ABSOLUTE" | "MULTIPLIER"
body.timeStart (required): integer
Unix seconds, on a 15-minute boundary (:00, :15, :30, :45).
body.timeEnd (required): integer
Unix seconds, on a 15-minute boundary and after timeStart.
body.recurrenceType (optional): "ONE_TIME" | "WEEKLY" | "MONTHLY"
body.currency (optional): string
Ad account currency, for the ABSOLUTE minor-unit conversion. Ignored for MULTIPLIER.
query: no client-supplied fields
Request skeleton:
{
"body": {
"budgetValue": 1,
"budgetValueType": "ABSOLUTE",
"timeStart": 1,
"timeEnd": 1
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts value-rule-sets
List Meta value rule sets
Usage: smallforce ads accounts value-rule-sets [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page. Meta does not document paging on this edge; `after` comes back null when it omits cursors.
Request skeleton:
{
"query": {
"limit": 25
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts create-value-rule-set
Create a Meta value rule set
Usage: smallforce ads accounts create-value-rule-set [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
body.rules (required): array<object{name, adjustSign, adjustValue, criteria}>
Evaluated in order; the first matching rule wins.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"rules": [
{
"name": "Example Meta Ads resource",
"adjustSign": "INCREASE",
"adjustValue": 1,
"criteria": [
{
"criteriaType": "AGE",
"operator": "CONTAINS",
"criteriaValues": [
"<criteriaValues>"
],
"criteriaValueTypes": [
"<criteriaValueTypes>"
]
}
]
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts get-value-rule-set
Read a Meta value rule set
Usage: smallforce ads accounts get-value-rule-set [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local value-rule-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts update-value-rule-set
Update a Meta value rule set
Usage: smallforce ads accounts update-value-rule-set [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local value-rule-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
Required: the update replaces the whole set.
body.rules (required): array<object{name, adjustSign, adjustValue, criteria}>
The COMPLETE rule list. Omitting a rule deletes it on Meta.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"rules": [
{
"name": "Example Meta Ads resource",
"adjustSign": "INCREASE",
"adjustValue": 1,
"criteria": [
{
"criteriaType": "AGE",
"operator": "CONTAINS",
"criteriaValues": [
"<criteriaValues>"
],
"criteriaValueTypes": [
"<criteriaValueTypes>"
]
}
]
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts delete-value-rule-set
Delete a Meta value rule set
Usage: smallforce ads accounts delete-value-rule-set [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local value-rule-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts finance
Read Meta ad-account finance details
Usage: smallforce ads accounts finance [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts update
Update Meta ad-account defaults
Usage: smallforce ads accounts update [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (optional): string
New ad account name.
body.spendCap (optional): value
Account spend cap in whole currency units; null removes it.
body.resetAmountSpent (optional): boolean
Restart the amount counted against the cap from zero. Cannot be combined with spendCap null.
body.defaultDsaBeneficiary (optional): string
Legal entity benefiting from ads on this ad account
body.defaultDsaPayor (optional): string
Legal entity paying for ads on this ad account. Defaults to defaultDsaBeneficiary when omitted. Requires defaultDsaBeneficiary.
body.trackingUrlTemplate (optional): string
body.finalUrlSuffix (optional): string
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts dsa-defaults
Read Meta DSA beneficiary and payor defaults
Usage: smallforce ads accounts dsa-defaults [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts dsa-recommendations
Read Meta DSA recommendations
Usage: smallforce ads accounts dsa-recommendations [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts custom-conversions
List Meta custom conversions
Usage: smallforce ads accounts custom-conversions [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts create-custom-conversion
Create a Meta custom conversion
Usage: smallforce ads accounts create-custom-conversion [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
Also the reuse key, together with pixelId.
body.pixelId (required): local tracking_tag reference
Meta pixel id (event_source_id). From GET /v1/accounts/{accountId}/tracking-tags. Use a SmallForce-local tracking_tag reference; raw provider IDs are rejected.
body.customEventType (required): string
Meta custom_event_type, e.g. LEAD, PURCHASE, OTHER.
body.rule (required): object
Meta conversion rule, forwarded verbatim.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"pixelId": {
"$smallforce": {
"id": "<local tracking_tag UUID>",
"kind": "tracking_tag"
}
},
"customEventType": "<customEventType>",
"rule": {}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads accounts health
Check whether the ad account can run ads now, with a fix link per problem
Usage: smallforce ads accounts health [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads campaigns
Create, review, inspect, and manage Meta Ads campaigns
smallforce ads campaigns list
List Meta Ads campaigns
Usage: smallforce ads campaigns list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--platform <platform> | facebook or instagram |
--status <status> | Campaign status filter |
--source <source> | all or zernio (default: “all”) |
--from <date> | Inclusive YYYY-MM-DD start date |
--to <date> | Inclusive YYYY-MM-DD end date |
--page <n> | Page number, starting at 1 |
--limit <n> | Campaigns per page, 1 to 100 |
Also accepts the common options listed at the top of this page.
Examples:
$ smallforce ads campaigns list --account <adAccountId>
$ smallforce ads campaigns list --account <adAccountId> --status active --from 2026-07-01 --to 2026-07-31 --json
smallforce ads campaigns tree
Read campaigns with nested ad sets and advertisements
Usage: smallforce ads campaigns tree [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--platform <platform> | facebook or instagram |
--status <status> | Campaign status filter |
--source <source> | all or zernio (default: “all”) |
--from <date> | Inclusive YYYY-MM-DD start date |
--to <date> | Inclusive YYYY-MM-DD end date |
--page <n> | Page number, starting at 1 |
--limit <n> | Campaigns per page, 1 to 100 |
--campaign <campaignId> | Limit to one local campaign id |
--include-daily | Include daily metric rows |
--daily-level <level> | campaign, adset, or ad |
--sort <sort> | newest, oldest, spend_desc, or spend_asc |
Also accepts the common options listed at the top of this page.
Examples:
$ smallforce ads campaigns tree --account <adAccountId> --campaign <campaignId> --json
$ smallforce ads campaigns tree --account <adAccountId> --include-daily --daily-level adset --from 2026-07-01 --to 2026-07-31 --json
smallforce ads campaigns analytics
Get summary, daily, and optional breakdown analytics
Usage: smallforce ads campaigns analytics [options] <campaignId>
| Argument | Description |
|---|---|
campaignId | Local campaign id from campaigns list |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--platform <platform> | facebook or instagram |
--from <date> | Inclusive YYYY-MM-DD start date |
--to <date> | Inclusive YYYY-MM-DD end date |
--breakdown <dimension> | age, gender, country, publisher_platform, device_platform, or region; repeatable (default: []) |
Also accepts the common options listed at the top of this page.
Examples:
$ smallforce ads campaigns analytics <campaignId> --account <adAccountId>
$ smallforce ads campaigns analytics <campaignId> --account <adAccountId> --breakdown age --breakdown gender --json
smallforce ads campaigns preflight
Check whether a paused Meta campaign is ready to activate
Usage: smallforce ads campaigns preflight [options] <campaignId>
| Argument | Description |
|---|---|
campaignId | Local campaign id from campaigns list |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--platform <platform> | facebook or instagram |
Also accepts the common options listed at the top of this page.
Run this before campaigns status <campaignId> active. Blocking issues prevent
activation; warnings are returned without blocking it.
Example:
$ smallforce ads campaigns preflight <campaignId> --account <adAccountId> --json
smallforce ads campaigns validate
Validate a complete Meta campaign draft without creating it
Usage: smallforce ads campaigns validate [options]
| Option | Description |
|---|---|
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Input is the same complete object used by campaigns create. Validation invokes
Meta's validate-only flow and does not create campaign objects. Predictable-
reach drafts are validated as part of quote and reserve instead.
Examples:
$ smallforce ads campaigns validate --input-file draft.json
$ cat draft.json | smallforce ads campaigns validate --input-file - --json
smallforce ads campaigns preview
Generate safe Meta placement previews for a campaign draft
Usage: smallforce ads campaigns preview [options]
| Option | Description |
|---|---|
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Input is the complete campaign draft plus previewFormats. Supported formats:
DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD,
INSTAGRAM_STORY, INSTAGRAM_REELS, FACEBOOK_STORY_MOBILE
Pre-create provider previews currently require an image asset.
Example:
$ smallforce ads campaigns preview --input-file preview-draft.json --json
smallforce ads campaigns create
Create a complete Meta campaign, ad set, and advertisement
Usage: smallforce ads campaigns create [options]
| Option | Description |
|---|---|
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Required top-level draft fields:
adAccountId, goal, idempotencyKey, mode, name, targeting
Rules:
mode must be "standalone".
assetId and creative are required except when goal is page_likes; Meta derives
the Page destination and LIKE_PAGE call to action for that goal.
Auction campaigns require budget; lifetime budget requires schedule.endDate.
targeting requires at least one geographic target.
The same idempotencyKey safely replays the same request; generate a new UUID
whenever the request changes.
Campaigns are created paused. Run campaigns preflight before activation.
Example:
$ smallforce ads campaigns create --input-file draft.json --json
smallforce ads campaigns update
Update Meta campaign name, CBO budget, bid strategy, or spend cap
Usage: smallforce ads campaigns update [options] <campaignId>
| Argument | Description |
|---|---|
campaignId | Local campaign id from campaigns list |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--platform <platform> | facebook or instagram |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Update JSON fields:
name, budget: { amount, type }, bidStrategy, spendCap
Set spendCap to null to remove it. Campaign budget updates only work for CBO;
use ads ad-sets update for ABO budgets.
Example:
$ smallforce ads campaigns update <campaignId> --account <adAccountId> --input '{"name":"Fall campaign","budget":{"amount":50,"type":"daily"}}'
smallforce ads campaigns status
Activate or pause one Meta campaign
Usage: smallforce ads campaigns status [options] <campaignId> <status>
| Argument | Description |
|---|---|
campaignId | Local campaign id from campaigns list |
status | active or paused |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--platform <platform> | facebook or instagram |
Also accepts the common options listed at the top of this page.
Activation automatically runs the same preflight checks as campaigns preflight
and is rejected when blocking issues remain. Pausing does not require preflight.
Examples:
$ smallforce ads campaigns status <campaignId> active --account <adAccountId>
$ smallforce ads campaigns status <campaignId> paused --account <adAccountId>
smallforce ads campaigns details
Get live campaign details
Usage: smallforce ads campaigns details [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local campaign id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fields (optional): string
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers.
Request skeleton:
{
"query": {
"fields": "<fields>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads campaigns create-empty
Create an empty Meta campaign
Usage: smallforce ads campaigns create-empty [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
body.goal (required): "engagement" | "traffic" | "awareness" | "video_views" | "lead_generation" | "lead_conversion" | "job_applicants" | "conversions" | "app_promotion" | "catalog_sales" | "page_likes" | "page_visits"
Mapped to the ODAX objective (same mapping as POST /v1/ads/create).
body.isSkadnetworkAttribution (optional): boolean
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....
body.promotedObject (optional): object
body.buyingType (optional): "AUCTION" | "RESERVED"
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. `RESERVED` (Reach & Frequency) is Meta-only and is rejected with a...
body.validateOnly (optional): boolean
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. `true` on any other platform returns 501...
body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
body.budgetAmount (optional): number
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.
body.budgetType (optional): "daily" | "lifetime"
body.status (optional): "ACTIVE" | "PAUSED"
body.startDate (optional): string(date-time)
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.
body.endDate (optional): string(date-time)
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`.
body.locationTargetingType (optional): object
Written on the new campaign.
body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
Campaign bid strategy. **Meta** stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request (400 without a campaign budget). A campaign carrying a strategy without its `bid_amount`...
body.bidAmount (optional): number
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.
body.roasAverageFloor (optional): number
Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"goal": "engagement"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads campaigns delete
Delete a Meta campaign
Usage: smallforce ads campaigns delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local campaign id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.platform (required): "facebook" | "instagram"
query: no client-supplied fields
Request skeleton:
{
"body": {
"platform": "facebook"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads campaigns bulk-status
Activate or pause several Meta campaigns
Usage: smallforce ads campaigns bulk-status [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--campaign <campaignId> | Local campaign id; repeat for multiple campaigns (default: []) |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.status (required): "active" | "paused"
query: no client-supplied fields
Request skeleton:
{
"body": {
"status": "active"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads campaigns duplicate
Duplicate a Meta campaign hierarchy
Usage: smallforce ads campaigns duplicate [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local campaign id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.platform (required): "facebook" | "instagram"
body.deepCopy (optional): boolean
Copy child ad sets + ads + creatives + targeting
body.statusOption (optional): "ACTIVE" | "PAUSED" | "INHERITED_FROM_SOURCE"
PAUSED = clone stays DRAFT, safe default. INHERITED_FROM_SOURCE = mirror each entity's source status per-entity. Duplicating an ACTIVE campaign this way starts a second front of spend.
body.startTime (optional): string(date-time)
Reschedule the copied hierarchy's start (ISO 8601). TikTok defaults to a start a few minutes after the copy. - Meta and TikTok: a value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad...
body.endTime (optional): string(date-time)
Reschedule the copied hierarchy's end, read like `startTime`; a date-only end runs to 23:59:59 local. Defaults to the source's end.
body.renameStrategy (optional): "DEEP_RENAME" | "ONLY_TOP_LEVEL_RENAME" | "NO_RENAME"
Meta's native `rename_strategy` values: - `DEEP_RENAME`: renames the copied campaign and every copied child (ad sets, ads) with `renamePrefix` / `renameSuffix`. - `ONLY_TOP_LEVEL_RENAME`: renames only the copied campaign; children keep...
body.renamePrefix (optional): string
Text prepended to each renamed object's name.
body.renameSuffix (optional): string
Text appended to each renamed object's name.
body.syncAfter (optional): boolean
Trigger ads discovery on the owning account after the copy succeeds
query: no client-supplied fields
Request skeleton:
{
"body": {
"platform": "facebook"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads campaigns timeline
Read the Meta Ads performance timeline
Usage: smallforce ads campaigns timeline [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fromDate (optional): string(date)
Inclusive start of metrics range (YYYY-MM-DD). Defaults to 90 days ago.
query.toDate (optional): string(date)
Inclusive end of metrics range (YYYY-MM-DD). Defaults to today. Max 730-day range.
query.platform (optional): "facebook" | "instagram"
Restrict to one platform.
query.compare (optional): "previous"
Set to `previous` to also return `previousRows` for the period of the same length that ends the day before `fromDate`, with that period as `previousRange`. Needs a `fromDate` (sent or defaulted); `toDate` alone answers 400.
Request skeleton:
{
"query": {
"fromDate": "2026-08-01"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads alerts
See what needs attention across Meta, Google, and TikTok ads
smallforce ads alerts list
List ads problems, most severe first: rejected ads, delivery issues, payment problems, spend without results, capped budgets, lost connections, failing syncs
Usage: smallforce ads alerts list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Only this ad account (local id from ads accounts list) |
Also accepts the common options listed at the top of this page.
Alerts come from synced ad data (the last 7 days of metrics), so this makes no
ad-platform call and is safe to run often. An alert id stays the same while the
problem lasts, so compare ids to tell new alerts from ones already reported.
A problem that is fixed disappears from the list.
Example:
$ smallforce ads alerts list --json
$ smallforce ads alerts list --account <adAccountId>
smallforce ads businesses
smallforce ads businesses list
List portfolios before creating your first Meta ad account
Usage: smallforce ads businesses list [options]
| Option | Description |
|---|---|
--connection <uuid> | Owned Meta Ads connection UUID |
Also accepts the common options listed at the top of this page.
smallforce ads ad-sets
Inspect, update, duplicate, and manage Meta Ads ad sets
smallforce ads ad-sets get
Get one ad set with live schedule and learning state
Usage: smallforce ads ad-sets get [options] <adSetId>
| Argument | Description |
|---|---|
adSetId | Local ad-set id from campaigns tree |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--campaign <campaignId> | Local campaign id from campaigns tree |
Also accepts the common options listed at the top of this page.
Example:
$ smallforce ads ad-sets get <adSetId> --campaign <campaignId> --account <adAccountId> --json
smallforce ads ad-sets update
Update a Meta ad set’s delivery, budget, bidding, or customer lifecycle
Usage: smallforce ads ad-sets update [options] <adSetId>
| Argument | Description |
|---|---|
adSetId | Local ad-set id from campaigns tree |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--campaign <campaignId> | Local campaign id from campaigns tree |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Update JSON fields:
name, status, budget, schedule, bidStrategy, bidAmount, roasAverageFloor,
dailyMinSpendTarget, lifetimeMinSpendTarget, customerLifecycle
Budget updates only work for ABO ad sets. Bid-cap and cost-cap strategies
require bidAmount; minimum-ROAS bidding requires roasAverageFloor.
Minimum spend targets reserve a share of a matching campaign budget.
customerLifecycle takes strategy (all_customers, new_customers, or
new_customers_excluding_engaged) and existingCustomerAudienceIds / engagedAudienceIds
as local references: {"$smallforce":{"kind":"audience","id":"<local UUID>"}}.
Example:
$ smallforce ads ad-sets update <adSetId> --campaign <campaignId> --account <adAccountId> --input '{"status":"paused","budget":{"amount":25,"type":"daily"}}'
smallforce ads ad-sets list
List Meta ad sets including empty sets
Usage: smallforce ads ad-sets list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.campaignId (optional): local campaign reference
Platform campaign ID. Use a SmallForce-local campaign reference; raw provider IDs are rejected.
query.adSetId (optional): local ad_set reference
Platform ad set ID. Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
query.platform (optional): "facebook" | "instagram"
query.status (optional): "active" | "paused" | "pending_review" | "rejected" | "completed" | "cancelled" | "error"
Filter by the ad set's stored `status`, the value each row returns. A live read does not change it. Rows whose `status` is null match no filter.
query.page (optional): integer
query.limit (optional): integer
Request skeleton:
{
"query": {
"campaignId": {
"$smallforce": {
"id": "<local campaign UUID>",
"kind": "campaign"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads ad-sets delete
Delete a Meta ad set and its ads
Usage: smallforce ads ad-sets delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local ad-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads ad-sets duplicate
Duplicate a Meta ad set
Usage: smallforce ads ad-sets duplicate [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local ad-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.platform (required): "facebook" | "instagram"
body.campaignId (optional): local campaign reference
Destination platform campaign id (defaults to the source's campaign). Use a SmallForce-local campaign reference; raw provider IDs are rejected.
body.deepCopy (optional): boolean
Copy child ads + creatives
body.statusOption (optional): "ACTIVE" | "PAUSED" | "INHERITED_FROM_SOURCE"
body.startTime (optional): string(date-time)
Reschedule the copy's start (ISO 8601). A value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone.
body.endTime (optional): string(date-time)
Reschedule the copy's end, read like `startTime`; a date-only end runs to 23:59:59 local.
body.renameStrategy (optional): "DEEP_RENAME" | "ONLY_TOP_LEVEL_RENAME" | "NO_RENAME"
Meta's native `rename_strategy` values: - `DEEP_RENAME`: renames the copied ad set and its copied ads with `renamePrefix` / `renameSuffix`. - `ONLY_TOP_LEVEL_RENAME`: renames only the copied ad set; its ads keep their source names. -...
body.renamePrefix (optional): string
Text prepended to each renamed object's name.
body.renameSuffix (optional): string
Text appended to each renamed object's name.
body.syncAfter (optional): boolean
query: no client-supplied fields
Request skeleton:
{
"body": {
"platform": "facebook"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads ad-sets status
Update a Meta ad-set status
Usage: smallforce ads ad-sets status [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local ad-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.status (required): "active" | "paused"
body.platform (required): "facebook" | "instagram"
query: no client-supplied fields
Request skeleton:
{
"body": {
"status": "active",
"platform": "facebook"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements
Inspect, update, duplicate, and manage Meta advertisements
smallforce ads advertisements update
Update an ad’s name, status, or image creative
Usage: smallforce ads advertisements update [options] <adId>
| Argument | Description |
|---|---|
adId | Local advertisement id from campaigns tree |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--campaign <campaignId> | Local campaign id |
--ad-set <adSetId> | Local ad-set id |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Update JSON fields:
name, status, creative
Replacement creative shape:
{"creative":{"assetId":"<uuid>","body":"...","callToAction":"LEARN_MORE","headline":"...","linkUrl":"https://..."}}
Post-launch creative replacement currently requires an image asset. Upload it
first with assets upload and pass the returned asset id.
Example:
$ smallforce ads advertisements update <adId> --campaign <campaignId> --ad-set <adSetId> --account <adAccountId> --input '{"status":"paused"}'
smallforce ads advertisements list
List individual Meta advertisements
Usage: smallforce ads advertisements list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
query.source (optional): "zernio" | "all"
all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.
query.status (optional): "active" | "paused" | "pending_review" | "rejected" | "completed" | "cancelled" | "error"
query.platform (optional): "facebook" | "instagram"
query.pageId (optional): local Facebook page or social account reference
Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's `creative.pageId`; ads with no page signal (rare IG-only... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
query.campaignId (optional): local campaign reference
Platform campaign ID (filter ads within a campaign). Use a SmallForce-local campaign reference; raw provider IDs are rejected.
query.adSetId (optional): local ad_set reference
Platform ad set ID (filter ads within an ad set, the /{adset_id}/ads read of an adset-centric dashboard). Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
query.platformAdId (optional): local ad reference
Meta ad ID. Returns the ad with this platform-side ad ID. Use a SmallForce-local ad reference; raw provider IDs are rejected.
query.effectiveObjectStoryId (optional): local social_post reference
Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). Use to map a Business-Manager-visible post back to the Zernio ad. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
query.effectiveInstagramMediaId (optional): local social_post reference
Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). Use to map a Business-Manager-visible IG post back to the Zernio ad. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
query.fromDate (optional): string(date)
Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
query.toDate (optional): string(date)
End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
Request skeleton:
{
"query": {
"limit": 50
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements duplicate
Duplicate a Meta advertisement
Usage: smallforce ads advertisements duplicate [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.adSetId (optional): local ad_set reference
Destination platform ad set id (defaults to the source's ad set). Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
body.statusOption (optional): "ACTIVE" | "PAUSED" | "INHERITED_FROM_SOURCE"
body.renameStrategy (optional): "DEEP_RENAME" | "ONLY_TOP_LEVEL_RENAME" | "NO_RENAME"
Meta's native `rename_strategy` values. An ad has no copied children, so `DEEP_RENAME` and `ONLY_TOP_LEVEL_RENAME` both rename the copy with `renamePrefix` / `renameSuffix`, and `NO_RENAME` keeps the source name. With no rename option...
body.renamePrefix (optional): string
Text prepended to the copy's name.
body.renameSuffix (optional): string
Text appended to the copy's name.
body.syncAfter (optional): boolean
body.reuseSourceCreative (optional): boolean
Point the copy at the source ad's creative object instead of copying it. The copy keeps the same Facebook post and Instagram media, their existing likes, comments and shares, and the full creative setup (text variations included). This...
query: no client-supplied fields
Request skeleton:
{
"body": {
"adSetId": {
"$smallforce": {
"id": "<local ad_set UUID>",
"kind": "ad_set"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements delete
Delete a Meta advertisement
Usage: smallforce ads advertisements delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements status
Update a Meta advertisement status
Usage: smallforce ads advertisements status [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.status (required): "active" | "paused"
query: no client-supplied fields
Request skeleton:
{
"body": {
"status": "active"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements boost-post
Boost a SmallForce social post with Meta Ads
Usage: smallforce ads advertisements boost-post [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local social-post id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--target-kind <kind> | social_post (default) or instagram_post from instagram-posts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.creativeFeatures (optional): object
body.name (required): string
body.campaignName (optional): string
Exact name for the campaign this boost provisions. Omitted keeps the default `<name> - Campaign`. Ignored on the Meta attach shape (`adSetId`), which creates no campaign.
body.adSetName (optional): string
Exact name for the ad-group level this boost provisions. Omitted keeps the default `<name> - Ad Group`. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group. Ignored on the...
body.goal (required): "engagement" | "traffic" | "awareness" | "video_views" | "lead_generation" | "conversions" | "app_promotion"
Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. X supports engagement, traffic, awareness, video_views, app_promotion. Reddit supports traffic, awareness, video_views, lead_generation and conversions.
body.adSetId (optional): local ad_set reference
Meta, or TikTok with `smartPlus: true`. Attach the boosted post to this existing ad set instead of creating a campaign. - Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400. - TikTok: the id is an... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
body.existingCampaignId (optional): local campaign reference
The campaign keeps its own status and objective (the objective must fit `goal`). Cannot be combined with adSetId or smartPlus. On Meta use POST /v1/ads/create with existingCampaignId. Use a SmallForce-local campaign reference; raw provider IDs are rejected.
body.identityId (optional): local TikTok identity reference
Must be authorized on the advertiser or the call fails naming the available ones. Use a SmallForce-local TikTok identity reference; raw provider IDs are rejected.
body.identityType (optional): "TT_USER" | "CUSTOMIZED_USER" | "BC_AUTH_TT"
Type of identityId; resolved from the advertiser's identity list when omitted.
body.budgetAmount (optional): number
Budget in whole currency units, the same flat field as POST /v1/ads/create. Required unless adSetId is set.
body.budgetType (optional): "daily" | "lifetime"
Goes together with budgetAmount. lifetime requires schedule.endDate.
body.lifetimeBudgetCap (optional): number
X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount. The line item gets both daily_budget_amount_local_micro and...
body.budget (optional): object{amount, type}
Alias of budgetAmount + budgetType, kept for existing callers
body.instagramAccountId (optional): local social_account reference
Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative. Use a SmallForce-local social_account reference; raw provider IDs are rejected.
body.destinationType (optional): "INSTAGRAM_PROFILE" | "WEBSITE" | "ON_AD" | "MESSENGER" | "WHATSAPP" | "INSTAGRAM_DIRECT"
Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal. A messaging callToAction selects its destination automatically; an...
body.whatsappPhoneNumber (optional): string
Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad.
body.currency (optional): string
ISO 4217 currency code matching the ad account's currency. Meta only. Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
body.startDate (optional): string(date-time)
Ad-set start time (ISO 8601, e.g. "2026-06-10T09:00:00Z"), mapped to the ad set's `start_time`. When omitted the ad starts delivering immediately. On Meta, TikTok, X, Pinterest and Reddit a value without an offset (`YYYY-MM-DD`,...
body.endDate (optional): string(date-time)
Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /v1/ads/create. Maps to the ad set's `end_time` (on X, the line item's `end_time`; X campaigns carry no flight dates). On Meta, TikTok, X, Pinterest and...
body.schedule (optional): object
Alias of the top-level `startDate` / `endDate`, kept for existing callers. Sending both forms with differing values is a 400.
body.targeting (optional): object
Same geo/demographic fields as the `TargetingSpec` used by /v1/ads/create. Geo keys (`regions`/`cities`/`zips`/`metros`) resolve via GET /v1/ads/targeting/search?dimension=geo. - Meta only: city radius and lat/lng `customLocations`....
body.locationTargetingType (optional): object
Written on the campaign the boost creates.
body.rawTargeting (optional): object
Meta only. A Meta-native targeting spec (e.g. `{ "geo_locations": { "cities": [{ "key": "...", "radius": 15, "distance_unit": "kilometer" }] } }`). Sent alone, it is forwarded unchanged. Use it for advanced fields the structured object...
body.bidStrategy (optional): object
Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. Meta bid strategy applied to the ad...
body.bidAmount (optional): number
Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. Bid cap in WHOLE currency units...
body.roasAverageFloor (optional): number
Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. Minimum ROAS as a decimal...
body.platformSpecificData (optional): object
Platform-specific options. The platform is derived from `accountId`; sending options for a different platform returns a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today. **Meta**:...
body.tracking (optional): object
Meta only, except `pixelId`, which also picks the Reddit pixel of the new ad group (`promotedObject.pixelId` wins when both are sent). Tracking specs (pixel, URL tags).
body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "FINANCIAL_PRODUCTS_SERVICES" | "ISSUES_ELECTIONS_POLITICS" | "ONLINE_GAMBLING_AND_GAMING">
Special ad category of the campaign the boost creates. Required for housing, employment, credit, or political ads. - Meta: every value. - TikTok: HOUSING, EMPLOYMENT and CREDIT, sent as the campaign's `special_industries` (TikTok...
body.specialAdCategoryCountry (optional): array<string>
Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).
body.regionalRegulatedCategories (optional): array<string>
Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
body.regionalRegulationIdentities (optional): object
Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on ad sets created through the API even...
body.linkUrl (optional): string(uri)
Website URL for non-messaging CTA buttons. Send it with `callToAction`. Omit for messaging boosts. **Meta**: adds a top-level `call_to_action` to the post-reference creative. This is what gives a `traffic` boost a clickable destination...
body.callToAction (optional): string
CTA button label. Non-messaging CTAs require `linkUrl`. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl. **Meta**: the CTA enum of POST /v1/ads/create plus `VIEW_INSTAGRAM_PROFILE`,...
body.sparkAuthCode (optional): string
Maps to `auth_code` on the creative entry of /v2/ad/create/. Without it, boosts are limited to videos owned by the same account running the ads (same-BC creators only).
body.smartPlus (optional): boolean
Run the Spark post in a Smart+ campaign instead of a regular one: goal `conversions` = Smart+ Web Conversions, `lead_generation` = Smart+ Lead Generation. Rejected with a 400 on other platforms. **Requires:** - `sparkAuthCode`: the...
body.sparkPosts (optional): array<object{platformPostId, sparkAuthCode}>
Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces `platformPostId` + `sparkAuthCode`.
body.promoCodes (optional): array<object{discountType, discountValue}>
Rejected with a 400 on other platforms and on Lead Generation campaigns.
body.promotedObject (optional): object
Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic. Required when `goal` is `conversions` (Meta also...
body.dsaBeneficiary (optional): string
Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
body.dsaPayor (optional): string
Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
body.leadGenFormId (optional): string
Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when `goal` is `lead_generation`; ignored for other goals. - Meta: the leadgen_forms ID (create one via POST /v1/ads/lead-forms). - LinkedIn: the adForm ID (create one...
body.status (optional): "ACTIVE" | "PAUSED"
Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default). PAUSED pauses only the top-most object this boost creates and switches everything below it on: - New campaign: held paused with its ad...
body.campaignStatus (optional): "ACTIVE" | "PAUSED"
Every platform, same semantics as POST /v1/ads/create. When omitted, it follows `status`. `ACTIVE` with `status: PAUSED` switches the campaign on and holds the new ad set paused (its ad on). Rejected with a 400 alongside `adSetId` or...
body.adSetStatus (optional): "ACTIVE" | "PAUSED"
Every platform, same semantics as POST /v1/ads/create. Sets the switch of the new ad set alone and overrides `status` for it. Omitted, it follows `status`. `status: PAUSED` then holds the top-most new object without a level status, only...
body.adStatus (optional): "ACTIVE" | "PAUSED"
Sets the switch of the new ad alone, also when attaching to an existing ad set with `adSetId` (Meta, TikTok Smart+), and overrides `status` for it. Same precedence as `adSetStatus`. A DRAFT creative is not submitted for review and...
body.budgetLevel (optional): "adset" | "campaign"
Meta only, same semantics as POST /v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId.
body.attributionSpec (optional): array<object{eventType, windowDays}>
Meta only. Ad-set attribution windows, same shape as POST /v1/ads/create. Applied on OUTCOME_SALES, OUTCOME_LEADS and OUTCOME_APP_PROMOTION campaigns (conversions, lead_conversion, lead_generation, app_promotion); other objectives keep...
body.bodies (optional): array<string>
Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media. Under a...
body.retryOnServerError (optional): boolean
Meta only (a 400 elsewhere). When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it...
body.rehostOnInstagramVideoRejection (optional): boolean
Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279). - First, Zernio copies the video into the ad account and retries on the original post. - Then it falls back to...
body.smartTargeting (optional): object
Available on Video views, Traffic, Lead generation, App install, Web conversion and Community interaction. Not available with smartPlus or when attaching to an existing ad set (adSetId). Only the flags you send are written. An unwritten...
body.optimizationGoal (optional): string
Ad-set optimization goal override. Meta, or TikTok with `goal: video_views`. **TikTok**: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400....
body.metaObjective (optional): "OUTCOME_ENGAGEMENT"
Meta only, with `goal: engagement` and without `adSetId` (400 otherwise). `OUTCOME_ENGAGEMENT` creates the campaign with objective `OUTCOME_ENGAGEMENT` and the ad set with `optimization_goal` `POST_ENGAGEMENT` (unless `optimizationGoal`...
body.validateOnly (optional): boolean
Meta only (facebook, instagram and Meta ads connections). Dry-runs the boost with Meta's execution_options validate_only: the campaign, ad set, creative (the post reference) and ad are checked as sent, everything PAUSED, and nothing is...
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"goal": "engagement"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements analytics
Read analytics for one Meta advertisement
Usage: smallforce ads advertisements analytics [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fromDate (optional): string(date)
Start of date range (YYYY-MM-DD). Defaults to 90 days ago.
query.toDate (optional): string(date)
End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
query.breakdowns (optional): string
Comma-separated breakdown dimensions. - **Meta**: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset. - **TikTok**: gender, age,...
Request skeleton:
{
"query": {
"fromDate": "2026-08-01"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements previews
Read placement previews for one Meta advertisement
Usage: smallforce ads advertisements previews [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.formats (optional): string
Comma-separated Meta ad_format values (max 10), one preview per format. Defaults to DESKTOP_FEED_STANDARD.
Request skeleton:
{
"query": {
"formats": "<formats>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements media
Read fresh signed media URLs for one Meta advertisement
Usage: smallforce ads advertisements media [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements tracking-tags
Read tracking parameters for a Meta advertisement
Usage: smallforce ads advertisements tracking-tags [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements update-tracking-tags
Update tracking parameters for a Meta advertisement
Usage: smallforce ads advertisements update-tracking-tags [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.urlTags (optional): array<object{key, value}>
Meta only. Click-URL params appended to a freshly-rebuilt creative. Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded.
body.creative (optional): object{headline, body, callToAction, linkUrl, imageUrl}
Meta only. OPTIONAL: omit to preserve the existing creative verbatim (default). Provide it only to rebuild the creative explicitly, or for creatives whose object_story_spec Meta strips.
body.trackingUrlTemplate (optional): string
Full tracking template (must contain {lpurl}).
body.finalUrlSuffix (optional): string
Parse-only key=value params.
body.dynamicValueParameters (optional): object
body.customValueParameters (optional): object
query: no client-supplied fields
Request skeleton:
{
"body": {
"urlTags": [
{
"key": "<key>",
"value": "<value>"
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements comments
Read comments attached to a Meta advertisement
Usage: smallforce ads advertisements comments [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.placement (optional): "facebook" | "instagram"
Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement.
query.limit (optional): integer
query.since (optional): string(date)
Defaults to 30 days before until. Maximum window is 30 days.
query.until (optional): string(date)
Defaults to today in UTC.
query.cursor (optional): string
Pagination cursor from a previous response.
Request skeleton:
{
"query": {
"placement": "facebook"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads advertisements performance
Rank the ad account’s ads by spend, impressions, clicks, results or ROAS
Usage: smallforce ads advertisements performance [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fromDate (required): string(date)
Inclusive start of the range (YYYY-MM-DD).
query.toDate (required): string(date)
Inclusive end of the range (YYYY-MM-DD). Max 730-day range.
query.platform (optional): "facebook" | "instagram"
Restrict to one platform.
query.sortBy (optional): "spend" | "impressions" | "clicks" | "conversions" | "roas"
Metric the ads are ranked by, highest first.
query.limit (optional): integer
How many ads to return.
Request skeleton:
{
"query": {
"fromDate": "2026-08-01",
"toDate": "2026-08-01"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads reports
Run and retrieve asynchronous Meta Insights reports
smallforce ads reports create
Submit an asynchronous Meta Insights report
Usage: smallforce ads reports create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Required JSON fields:
idempotencyKey
object: { "type": "account" }
or { "type": "campaign" | "ad_set" | "ad", "id": "<local UUID>" }
Optional report fields:
level, fields, breakdowns, actionBreakdowns, actionAttributionWindows,
actionReportTime, useUnifiedAttributionSetting, filtering, datePreset,
fromDate, toDate, timeIncrement
fields, breakdowns, and actionBreakdowns are arrays. datePreset is mutually
exclusive with fromDate/toDate. timeIncrement accepts 1-90, "monthly", or
"all_days". Meta validates field, breakdown, and filter combinations.
Examples:
$ smallforce ads reports create --account <adAccountId> --input-file report.json --json
$ smallforce ads reports create --account <adAccountId> --input '{"idempotencyKey":"<uuid>","object":{"type":"campaign","id":"<campaignId>"},"level":"ad","fields":["ad_id","ad_name","spend","actions"],"datePreset":"last_30d","timeIncrement":1}' --json
smallforce ads reports get
Poll or page one asynchronous Meta Insights report
Usage: smallforce ads reports get [options] <reportId>
| Argument | Description |
|---|---|
reportId | Local report id returned by reports create |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--cursor <cursor> | Opaque cursor from the previous JSON page |
--limit <n> | Rows per completed page, 1 to 500 |
Also accepts the common options listed at the top of this page.
While Meta is processing, this returns status and progress. Once succeeded,
--json includes raw report rows and nextCursor. The provider report handle is
never accepted by this command.
Example:
$ smallforce ads reports get <reportId> --account <adAccountId> --limit 500 --json
smallforce ads reports wait
Wait for an asynchronous Meta Insights report to finish
Usage: smallforce ads reports wait [options] <reportId>
| Argument | Description |
|---|---|
reportId | Local report id returned by reports create |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--cursor <cursor> | Opaque cursor from a completed report page |
--limit <n> | Rows per completed page, 1 to 500 |
--poll-interval <seconds> | Polling interval, 1 to 60 (default: “3”) |
--timeout <seconds> | Maximum wait, 1 to 3600 (default: “300”) |
Also accepts the common options listed at the top of this page.
This polls SmallForce using the local report id. A timeout does not cancel the
provider job; the JSON result sets waitTimedOut=true and can be resumed later.
Example:
$ smallforce ads reports wait <reportId> --account <adAccountId> --limit 500 --json
smallforce ads targeting
Search Meta targeting values and estimate audience reach
smallforce ads targeting search
Search valid Meta geographic, interest, behavior, or income targets
Usage: smallforce ads targeting search [options] <query>
| Argument | Description |
|---|---|
query | Audience or location search text |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--dimension <dimension> | geo, interest, behavior, income, language, workPosition, workEmployer, or workIndustry (default: “interest”) |
--geo-type <type> | country, country_group, region, city, zip, metro_area, place, or neighborhood |
--country <code> | Two-letter country code for geo searches |
--limit <n> | Results to return, 1 to 100 |
Also accepts the common options listed at the top of this page.
Use the returned IDs/keys when constructing targeting in a campaign draft.
--geo-type and --country are only valid with --dimension geo.
Examples:
$ smallforce ads targeting search "coffee" --account <adAccountId> --dimension interest --json
$ smallforce ads targeting search "Detroit" --account <adAccountId> --dimension geo --geo-type city --country US --json
smallforce ads targeting estimate
Estimate reach for a complete Meta targeting spec
Usage: smallforce ads targeting estimate [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--optimization-goal <goal> | Optional provider optimization goal |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
The input JSON is the targeting spec itself, not a wrapper. It may contain age,
gender, interests, behaviors, included/excluded locations, languages, or other
supported Meta targeting fields.
Examples:
$ smallforce ads targeting estimate --account <adAccountId> --input '{"countries":["US"],"ageMin":25,"ageMax":54}'
$ smallforce ads targeting estimate --account <adAccountId> --input-file targeting.json --json
smallforce ads targeting browse
Browse Meta’s detailed targeting categories without a keyword
Usage: smallforce ads targeting browse [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.type (optional): string
Only the nodes of this Meta type (e.g. interests, behaviors, life_events, income), plus the organizational nodes leading to them. A type that is not in the catalog returns 400.
query.parentNodeId (optional): string
Only the descendants (every depth) of this organizational node, e.g. `Demographics > Financial`. A nodeId that is not an organizational node of the catalog returns 400.
query.selectable (optional): boolean
`true` for selectable entities only, `false` for organizational nodes only.
Request skeleton:
{
"query": {
"type": "<type>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads predictable-reach
Quote, reserve, inspect, and release Meta Reach & Frequency delivery
smallforce ads predictable-reach quote
Create a Meta predictable-reach quote
Usage: smallforce ads predictable-reach quote [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Quote JSON fields:
idempotencyKey, startDate, endDate, targeting, and exactly one of
budgetAmount or reach
Optional fields:
frequencyCap, placements
Dates must be future ISO timestamps. A quote does not reserve inventory.
Example:
$ smallforce ads predictable-reach quote --account <adAccountId> --input-file quote.json --json
smallforce ads predictable-reach get
Read a predictable-reach quote or reservation
Usage: smallforce ads predictable-reach get [options] <predictionId>
| Argument | Description |
|---|---|
predictionId | Prediction id returned by quote |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
Also accepts the common options listed at the top of this page.
smallforce ads predictable-reach reserve
Reserve inventory for a predictable-reach quote
Usage: smallforce ads predictable-reach reserve [options] <predictionId>
| Argument | Description |
|---|---|
predictionId | Prediction id returned by quote |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
Also accepts the common options listed at the top of this page.
After reservation, create the campaign with buyingType "RESERVED" and the
returned rfPredictionId. Omit budget and schedule because the reservation owns
pricing and dates.
Example:
$ smallforce ads predictable-reach reserve <predictionId> --account <adAccountId> --json
smallforce ads predictable-reach release
Release a predictable-reach reservation
Usage: smallforce ads predictable-reach release [options] <predictionId>
| Argument | Description |
|---|---|
predictionId | Reserved prediction id |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
Also accepts the common options listed at the top of this page.
This releases reserved Meta inventory. Do not release a reservation that is
still intended for campaign launch.
Example:
$ smallforce ads predictable-reach release <predictionId> --account <adAccountId>
smallforce ads lead-forms
List, create, inspect, archive, test, and read Meta Instant Forms
smallforce ads lead-forms list
List Meta Instant Forms accessible to an ad account
Usage: smallforce ads lead-forms list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--cursor <cursor> | Opaque provider cursor from the previous page |
--limit <n> | Forms per page, 1 to 100 |
Also accepts the common options listed at the top of this page.
Example:
$ smallforce ads lead-forms list --account <adAccountId> --json
smallforce ads lead-forms get
Get one Meta Instant Form
Usage: smallforce ads lead-forms get [options] <formId>
| Argument | Description |
|---|---|
formId | Local form id from lead-forms list |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
Also accepts the common options listed at the top of this page.
smallforce ads lead-forms create
Create a Meta Instant Form
Usage: smallforce ads lead-forms create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Required JSON fields:
name, privacyPolicyUrl, questions
New Instant Form controls:
isPhoneSmsVerifyEnabled (optional boolean)
thankYouEnableMessenger (optional boolean)
This provider operation is not idempotent. Do not automatically retry a failed
request unless you have confirmed that Meta did not create the form.
Example:
$ smallforce ads lead-forms create --account <adAccountId> --input-file lead-form.json --json
smallforce ads lead-forms archive
Archive one Meta Instant Form
Usage: smallforce ads lead-forms archive [options] <formId>
| Argument | Description |
|---|---|
formId | Local form id from lead-forms list |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
Also accepts the common options listed at the top of this page.
This archives the provider form; it does not merely hide a local row.
Example:
$ smallforce ads lead-forms archive <formId> --account <adAccountId>
smallforce ads lead-forms test-lead
Create a Meta test lead for one Instant Form
Usage: smallforce ads lead-forms test-lead [options] <formId>
| Argument | Description |
|---|---|
formId | Local form id from lead-forms list |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Input shape:
{"fieldData":[{"name":"email","values":["test@example.com"]}]}
Example:
$ smallforce ads lead-forms test-lead <formId> --account <adAccountId> --input '{"fieldData":[{"name":"email","values":["test@example.com"]}]}' --json
smallforce ads lead-forms form-leads
List leads submitted to one Meta Instant Form
Usage: smallforce ads lead-forms form-leads [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local lead-form id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
query.cursor (optional): string
query.since (optional): integer
Unix seconds.
Request skeleton:
{
"query": {
"limit": 25
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads leads
Read captured Meta leads
smallforce ads leads list
List Meta leads for an advertising account
Usage: smallforce ads leads list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--form <formId> | Filter by one Meta lead-form id |
--since <iso> | Only leads created after this ISO timestamp |
--status <statuses> | Only leads in these statuses, comma-separated: new, contacted, unreachable, qualified, converted, disqualified |
--cursor <cursor> | Opaque provider cursor from the previous page |
--limit <n> | Leads per page, 1 to 100 |
Also accepts the common options listed at the top of this page.
Track a lead toward a sale with ads leads status (the lead id is "Lead id" here).
Examples:
$ smallforce ads leads list --account <adAccountId> --json
$ smallforce ads leads list --account <adAccountId> --status new,contacted
$ smallforce ads leads list --account <adAccountId> --form <formId> --since 2026-07-01T00:00:00Z --json
smallforce ads leads counts
Count stored Meta leads by status
Usage: smallforce ads leads counts [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.campaignId (optional): local campaign reference
The platform campaign id the leads came from. Use a SmallForce-local campaign reference; raw provider IDs are rejected.
Request skeleton:
{
"query": {
"campaignId": {
"$smallforce": {
"id": "<local campaign UUID>",
"kind": "campaign"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads leads status
Set a Meta lead’s status, and optionally its value, to track it to a sale
Usage: smallforce ads leads status [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.status (required): "new" | "contacted" | "unreachable" | "qualified" | "converted" | "disqualified"
body.value (optional): number
Deal value; requires currency.
body.currency (optional): string
ISO 4217 code.
query: no client-supplied fields
path:
path.id (required): string
Zernio lead id, or the Meta leadgenId (then accountId is required).
Request skeleton:
{
"body": {
"status": "new"
},
"path": {
"id": "<lead id from ads leads list>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads account-users
Manage Meta ad-account access
smallforce ads account-users assign
Assign ad account user
Usage: smallforce ads account-users assign [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local meta-business-user id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.tasks (required): array<"MANAGE" | "ADVERTISE" | "ANALYZE" | "DRAFT">
query: no client-supplied fields
Request skeleton:
{
"body": {
"tasks": [
"MANAGE"
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads account-users list
List ad account users
Usage: smallforce ads account-users list [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local meta-business id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads account-users remove
Remove ad account user
Usage: smallforce ads account-users remove [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local meta-business-user id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads page-users
Manage Facebook Page access
smallforce ads page-users assign
Assign page user
Usage: smallforce ads page-users assign [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local facebook-page id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.businessId (required): local Meta business reference
Business portfolio the user belongs to. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.
body.userId (required): local meta_business_user reference
Business-scoped user id from GET /v1/ads/businesses/users. Use a SmallForce-local meta_business_user reference; raw provider IDs are rejected.
body.tasks (required): array<"MANAGE" | "CREATE_CONTENT" | "MODERATE" | "MESSAGING" | "ADVERTISE" | "ANALYZE">
query: no client-supplied fields
Request skeleton:
{
"body": {
"businessId": {
"$smallforce": {
"id": "<local meta_business UUID>",
"kind": "meta_business"
}
},
"userId": {
"$smallforce": {
"id": "<local meta_business_user UUID>",
"kind": "meta_business_user"
}
},
"tasks": [
"MANAGE"
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads page-users list
List page users
Usage: smallforce ads page-users list [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local facebook-page id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.businessId (required): local Meta business reference
Business portfolio whose people to list. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.
Request skeleton:
{
"query": {
"businessId": {
"$smallforce": {
"id": "<local meta_business UUID>",
"kind": "meta_business"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads page-users remove
Remove page user
Usage: smallforce ads page-users remove [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local facebook-page id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.userId (required): local meta_business_user reference
Business-scoped user id. Use a SmallForce-local meta_business_user reference; raw provider IDs are rejected.
Request skeleton:
{
"query": {
"userId": {
"$smallforce": {
"id": "<local meta_business_user UUID>",
"kind": "meta_business_user"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads videos
Manage Meta Ads videos
smallforce ads videos status
Get ad video status
Usage: smallforce ads videos status [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local video id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads business-users
Discover Meta business users and system users
smallforce ads business-users list
List meta business users
Usage: smallforce ads business-users list [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local meta-business id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads instagram-posts
Manage Meta Ads instagram-posts
smallforce ads instagram-posts list
List Instagram posts to boost
Usage: smallforce ads instagram-posts list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.igUserId (optional): local Instagram identity reference
Instagram identity to list. Must be one this connection can reach, otherwise the request is rejected with a 400. Use a SmallForce-local Instagram identity reference; raw provider IDs are rejected.
query.limit (optional): integer
Number of posts to return per page.
query.after (optional): string
Opaque Meta cursor from a previous response's paging.after.
Request skeleton:
{
"query": {
"igUserId": {
"$smallforce": {
"id": "<local instagram_identity UUID>",
"kind": "instagram_identity"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads test-leads
Manage Meta Ads test-leads
smallforce ads test-leads delete
Delete a test lead
Usage: smallforce ads test-leads delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local lead-form id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalogs
Manage Meta Ads catalogs
smallforce ads catalogs create
Create a Meta product catalog
Usage: smallforce ads catalogs create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.businessId (optional): local Meta business reference
Business portfolio that owns the catalog. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.
body.name (required): string
body.vertical (optional): "commerce" | "adoptable_pets" | "apps_and_software" | "articles_and_publications" | "destinations" | "flights" | "generic" | "home_listings" | "hotels" | "local_service_businesses" | "media_titles" | "offer_items" | ...
Meta catalog vertical. Use services for a professional services catalog (for example one linked to WhatsApp). local_service_business is a deprecated alias of local_service_businesses. The product endpoints under...
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalogs get
Get a product catalog
Usage: smallforce ads catalogs get [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalogs delete
Delete a product catalog
Usage: smallforce ads catalogs delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-products
Manage Meta Ads catalog-products
smallforce ads catalog-products list
List a catalog’s products
Usage: smallforce ads catalog-products list [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.limit (optional): integer
query.after (optional): string
Cursor from the previous page's `nextCursor`
query.retailerId (optional): string
Only the product with this retailer id (your SKU)
Request skeleton:
{
"query": {
"limit": 25
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-products create
Add a product to a catalog
Usage: smallforce ads catalog-products create [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.product (required): object{retailerId, name, url, imageUrl, price, currency}
query: no client-supplied fields
Request skeleton:
{
"body": {
"product": {
"retailerId": "<retailerId>",
"name": "Example Meta Ads resource",
"url": "https://example.com/offer",
"imageUrl": {
"$smallforceAsset": "<SmallForce asset UUID>"
},
"price": 1,
"currency": "USD"
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-products batch
Create, update or delete products in bulk
Usage: smallforce ads catalog-products batch [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.requests (required): array<object{method, product}>
query: no client-supplied fields
Request skeleton:
{
"body": {
"requests": [
{
"method": "CREATE",
"product": {
"retailerId": "<retailerId>"
}
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-products get
Get a product
Usage: smallforce ads catalog-products get [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-product id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-products update
Update a product
Usage: smallforce ads catalog-products update [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-product id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.product (required): object
query: no client-supplied fields
Request skeleton:
{
"body": {
"product": {
"retailerId": "<retailerId>"
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-products delete
Delete a product
Usage: smallforce ads catalog-products delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-product id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-batches
Manage Meta Ads catalog-batches
smallforce ads catalog-batches get
Get a bulk request’s status
Usage: smallforce ads catalog-batches get [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-batch id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-feeds
Manage Meta Ads catalog-feeds
smallforce ads catalog-feeds list
List a catalog’s product feeds
Usage: smallforce ads catalog-feeds list [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-feeds create
Create a product feed
Usage: smallforce ads catalog-feeds create [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
body.schedule (optional): object{interval, url}
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-uploads
Manage Meta Ads catalog-uploads
smallforce ads catalog-uploads list
List a feed’s uploads
Usage: smallforce ads catalog-uploads list [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-feed id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-uploads create
Fetch a feed file now
Usage: smallforce ads catalog-uploads create [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-feed id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.url (required): string(uri)
query: no client-supplied fields
Request skeleton:
{
"body": {
"url": "https://example.com/offer"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-sets
Manage Meta Ads catalog-sets
smallforce ads catalog-sets create
Create a product set
Usage: smallforce ads catalog-sets create [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
body.filter (required): object
Meta product set filter
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"filter": {}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-sets update
Update a product set
Usage: smallforce ads catalog-sets update [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-product-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (optional): string
body.filter (optional): object
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads catalog-sets delete
Delete a product set
Usage: smallforce ads catalog-sets delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog-product-set id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--idempotency-key <key> | Idempotency key forwarded for provider mutations |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads identities
Manage Meta Ads identities
smallforce ads identities list
List Instagram ad identities
Usage: smallforce ads identities list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads applications
Manage Meta Ads applications
smallforce ads applications list
List advertisable apps
Usage: smallforce ads applications list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads applications ios-limits
Get iOS 14 campaign limits
Usage: smallforce ads applications ios-limits [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.applicationId (required): local application reference
Meta application ID from advertisable-applications. Use a SmallForce-local application reference; raw provider IDs are rejected.
Request skeleton:
{
"query": {
"applicationId": {
"$smallforce": {
"id": "<local application UUID>",
"kind": "application"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads partnerships
Manage Meta Ads partnerships
smallforce ads partnerships content
List partnership ad content
Usage: smallforce ads partnerships content [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.creatorUsername (optional): string
Creator username. Required unless postUrl is supplied.
query.postUrl (optional): string(uri)
Instagram post permalink. Required unless creatorUsername is supplied.
query.onlyAllowlisted (optional): boolean
Return only creators with account-level permission.
Request skeleton:
{
"query": {
"creatorUsername": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads partnerships permissions
List partnership permissions
Usage: smallforce ads partnerships permissions [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.creatorUsername (optional): string
Filter by creator username.
Request skeleton:
{
"query": {
"creatorUsername": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads partnerships set-permission
Set partnership permission
Usage: smallforce ads partnerships set-permission [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.creatorUsername (required): string
body.revoke (optional): boolean
query: no client-supplied fields
Request skeleton:
{
"body": {
"creatorUsername": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads insights
Run synchronous Meta advertising insights queries
smallforce ads insights query
Run a synchronous Meta Insights query
Usage: smallforce ads insights query [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local ad-account, campaign, ad-set, or advertisement id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--target-kind <kind> | ad_account, campaign, ad_set, or ad |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.reportType (optional): "BASIC" | "AUDIENCE"
query.dataLevel (optional): "AUCTION_ADVERTISER" | "AUCTION_CAMPAIGN" | "AUCTION_ADGROUP" | "AUCTION_AD"
query.dimensions (optional): string
query.metrics (optional): string
query.page (optional): integer
query.pageSize (optional): integer
query.level (optional): "ad" | "adset" | "campaign" | "account"
Row granularity
query.fields (optional): string
Comma-separated Graph insights fields (e.g. spend,impressions,frequency,website_purchase_roas). Omitted = Meta's default set.
query.breakdowns (optional): string
Meta only: comma-separated Graph breakdowns (e.g. age,gender or publisher_platform).
query.actionBreakdowns (optional): string
Comma-separated Graph action breakdowns; segments the actions[] arrays in each row. Pass `none` to clear Meta's default action_type breakdown, required to combine some non-action breakdowns such as instagram_ads_follow_type (otherwise...
query.actionAttributionWindows (optional): string
Comma-separated Meta attribution windows. Action values are returned keyed per window.
query.actionReportTime (optional): string
When actions are counted: impression, conversion or mixed.
query.useUnifiedAttributionSetting (optional): boolean
Use the ad sets' own attribution settings for action counting.
query.filtering (optional): string
JSON array of filter objects: [{"field", "operator", "value"}]. Applied server-side by Meta or TikTok (TikTok fields e.g. campaign_ids, adgroup_ids, ad_ids).
query.datePreset (optional): string
Meta date_preset (e.g. last_7d, last_30d, this_month). Mutually exclusive with fromDate/toDate.
query.fromDate (optional): string(date)
Start of range (YYYY-MM-DD); requires toDate.
query.toDate (optional): string(date)
End of range (YYYY-MM-DD); requires fromDate.
query.timeIncrement (optional): string
Days per row (1-90), monthly, or all_days.
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"reportType": "BASIC"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives
Manage reusable Meta creatives, images, videos, and catalogs
smallforce ads creatives list
List reusable Meta ad creatives
Usage: smallforce ads creatives list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fields (optional): string
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"fields": "<fields>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives create
Create a reusable Meta ad creative
Usage: smallforce ads creatives create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.headline (required): string
body.body (required): string
Primary text
body.description (optional): string
Link description below the headline; omitted = Meta scrapes the destination's OG description.
body.callToAction (optional): string
CTA type (same whitelist as POST /v1/ads/create).
body.linkUrl (required): string(uri)
body.imageUrl (optional): SmallForce asset reference
Publicly reachable image; uploaded to the account's library server-side.
body.imageHash (optional): local image reference
Existing library image hash (POST /v1/ads/images or GET /v1/ads/images). Use a SmallForce-local image reference; raw provider IDs are rejected.
body.carouselCards (optional): array<object{imageUrl, linkUrl}>
body.instagramAccountId (optional): local social_account reference
Meta only. The Instagram account the creative runs as, mapped to `instagram_user_id`: an id from `GET /v1/ads/instagram-accounts`, including a Page-backed one. - Given, it is never swapped. One the ad account cannot use returns 400... Use a SmallForce-local social_account reference; raw provider IDs are rejected.
body.optimizeCardOrder (optional): boolean
Only with `carouselCards` (a 400 without them). Sets `link_data.multi_share_optimized`: - `false`: keeps the cards in the order given. Meta then takes at most 5 cards, so `false` with more than 5 cards is a 400. - `true`: lets Meta...
body.urlTags (optional): string
Appended to every outbound URL (e.g. utm_source=fb).
body.creativeFeatures (optional): object
Meta only. Applied to each new creative, including standalone and attach shapes. With creatives[], these are defaults; an item replaces the whole feature map, including an empty map. auto_promotion_tag is an Advantage+ enhancement, not...
body.multiAdvertiser (optional): "OPT_IN" | "OPT_OUT"
Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta...
body.aiDisclosure (optional): "OPT_IN" | "OPT_OUT"
Meta only. Meta's "Ad includes media created or edited with AI" disclosure (the Ads Manager checkbox), stored on the creative as `generative_asset_spec.transparency_metadata.self_disclosure`. - OPT_IN: checks it. - OPT_OUT: explicitly...
query: no client-supplied fields
Request skeleton:
{
"body": {
"headline": "A useful offer",
"body": "Learn more about this offer.",
"linkUrl": "https://example.com/offer"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives get
Read a reusable Meta ad creative
Usage: smallforce ads creatives get [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local creative id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fields (optional): string
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
query.thumbnailWidth (optional): integer
Width in pixels of the `thumbnail_url` rendering, forwarded to Meta as `thumbnail_width`. Without it Meta returns a 64x64 thumbnail.
query.thumbnailHeight (optional): integer
Height in pixels of the `thumbnail_url` rendering, forwarded to Meta as `thumbnail_height`. Without it Meta returns a 64x64 thumbnail.
Request skeleton:
{
"query": {
"fields": "<fields>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives update
Update a reusable Meta ad creative
Usage: smallforce ads creatives update [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local creative id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives delete
Delete a reusable Meta ad creative
Usage: smallforce ads creatives delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local creative id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives upload-image
Upload a SmallForce image asset to Meta Ads
Usage: smallforce ads creatives upload-image [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--asset <assetId> | SmallForce image asset id |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; supply the SmallForce asset with --asset.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives list-images
List Meta ad-account images
Usage: smallforce ads creatives list-images [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fields (optional): string
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"fields": "<fields>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives upload-video
Upload a SmallForce video asset to Meta Ads
Usage: smallforce ads creatives upload-video [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--asset <assetId> | SmallForce video asset id |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (optional): string
Optional video name shown in the Ads Manager media library. Takes precedence over filename.
body.async (optional): boolean
true: answer 202 once Meta accepts the upload instead of waiting for processing. Poll GET /v1/ads/videos/{videoId} or subscribe to ad.video.processed.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives list-videos
List Meta ad-account videos
Usage: smallforce ads creatives list-videos [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.fields (optional): string
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
query.limit (optional): integer
Rows per page
query.after (optional): string
Cursor from paging.after of the previous page.
Request skeleton:
{
"query": {
"fields": "<fields>"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives delete-video
Delete a Meta ad-account video
Usage: smallforce ads creatives delete-video [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local video id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives catalogs
List Meta commerce catalogs
Usage: smallforce ads creatives catalogs [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.businessId (optional): local Meta business reference
Meta business portfolio ID to list. When it is omitted and the Meta login can see several portfolios, the 400 carries `details.businesses` (id + name) so a client can offer the choice. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.
Request skeleton:
{
"query": {
"businessId": {
"$smallforce": {
"id": "<local meta_business UUID>",
"kind": "meta_business"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads creatives product-sets
List product sets in a Meta catalog
Usage: smallforce ads creatives product-sets [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local catalog id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags
Manage Meta pixels, datasets, sharing, and statistics
smallforce ads tracking-tags list
List Meta pixels and datasets
Usage: smallforce ads tracking-tags list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags create
Create a Meta pixel
Usage: smallforce ads tracking-tags create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
body.defaultEventType (optional): "order_created" | "lead_created" | "items_added" | "contents_viewed" | "checkout_started" | "registration_completed" | "subscription_created" | "trial_started" | "appointment_scheduled" | "page_viewed" | "app_installed" | "app_opened"
OpenAI Ads only (ignored by Meta). When set, also provisions a standard conversion event setting wired to the new pixel, so `goal: conversions` ad creates on `POST /v1/ads/create` have an event to reference immediately.
body.automaticMatchingFields (optional): array<"em" | "ph" | "fn" | "ln" | "ge" | "db" | "ct" | "st" | "zp" | "country" | "external_id">
Customer data the new tag matches automatically (automatic enhanced match): `em` email, `ph` phone, `fn`/`ln` name, `ge` gender, `db` date of birth, `ct`/`st`/`zp`/`country` location, `external_id`.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags get
Read a Meta pixel
Usage: smallforce ads tracking-tags get [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local tracking-tag id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags update
Update a Meta pixel
Usage: smallforce ads tracking-tags update [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local tracking-tag id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (optional): string
body.enableAutomaticMatching (optional): boolean
Meta Advanced Matching toggle (`enable_automatic_matching`).
body.automaticMatchingFields (optional): array<"em" | "ph" | "fn" | "ln" | "ge" | "db" | "ct" | "st" | "zp" | "country" | "external_id">
Which user fields Advanced Matching may collect. Meta's terse codes: em=email, ph=phone, fn=first name, ln=last name, ge=gender, db=date of birth, ct=city, st=state, zp=zip.
body.firstPartyCookieStatus (optional): "empty" | "first_party_cookie_disabled" | "first_party_cookie_enabled"
body.dataUseSetting (optional): "advertising_and_analytics" | "analytics_only" | "empty"
body.enableFirstPartyCookies (optional): boolean
Platform-neutral alternative to `firstPartyCookieStatus`.
body.autoTagging (optional): boolean
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags shared-accounts
List ad accounts sharing a Meta pixel
Usage: smallforce ads tracking-tags shared-accounts [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local tracking-tag id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags share
Share a Meta pixel with another local ad account
Usage: smallforce ads tracking-tags share [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local tracking-tag id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.adAccountId (required): local ad_account reference
Ad account to share with. Use a SmallForce-local ad_account reference; raw provider IDs are rejected.
query: no client-supplied fields
Request skeleton:
{
"body": {
"adAccountId": {
"$smallforce": {
"id": "<local ad_account UUID>",
"kind": "ad_account"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags unshare
Remove a Meta pixel from another local ad account
Usage: smallforce ads tracking-tags unshare [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local tracking-tag id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.adAccountId (optional): local ad_account reference
Ad account to unshare May also be sent in the JSON body. Use a SmallForce-local ad_account reference; raw provider IDs are rejected.
Request skeleton:
{
"query": {
"adAccountId": {
"$smallforce": {
"id": "<local ad_account UUID>",
"kind": "ad_account"
}
}
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads tracking-tags stats
Read Meta pixel event statistics
Usage: smallforce ads tracking-tags stats [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local tracking-tag id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.aggregation (optional): "event" | "host" | "url" | "url_by_rule" | "pixel_fire" | "device_type" | "device_os" | "browser_type" | "had_pii" | "custom_data_field" | "match_keys" | "event_source" | ...
Meta only (400 on other platforms): aggregation dimension. Defaults to `event`.
query.startTime (optional): integer
Unix seconds lower bound.
query.endTime (optional): integer
Unix seconds upper bound.
Request skeleton:
{
"query": {
"aggregation": "event"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences
Manage Meta custom audiences
smallforce ads audiences list
List Meta custom audiences
Usage: smallforce ads audiences list [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
query.platform (optional): "facebook" | "instagram"
query.type (optional): "customer_list" | "meta_engagement" | "website" | "lookalike" | "saved_targeting"
Filter to one audience type. `saved_targeting` returns stored TargetingSpec audiences and needs no adAccountId; the other types keep only the platform audiences of that type (an empty list when the platform has none). Meta ENGAGEMENT...
Request skeleton:
{
"query": {
"platform": "facebook"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences create
Create a Meta custom audience
Usage: smallforce ads audiences create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (required): string
body.description (optional): string
body.type (required): "customer_list" | "meta_engagement" | "website" | "lookalike" | "saved_targeting"
body.pixelId (optional): local tracking_tag reference
website: the Meta pixel, TikTok pixel, Pinterest tag or Reddit pixel id. Use a SmallForce-local tracking_tag reference; raw provider IDs are rejected.
body.retentionDays (optional): integer
Required for website (Meta max 180, TikTok 7/14/30/60/90/180, Reddit max 90, Pinterest and Google max 540), meta_engagement (max 365) and tiktok_engagement (7/14/30/60/90/180; organic and live video and most business-account events only...
body.engagementSource (optional): "page" | "instagram" | "video"
Required for meta_engagement audiences (Meta only): what people engaged with. `page` = a Facebook Page, `instagram` = an IG professional account, `video` = a video.
body.sourceId (optional): local social_account or video reference
Required for meta_engagement: the Page / IG account / video id. Use a SmallForce-local social_account or video reference; raw provider IDs are rejected.
body.event (optional): string
The event to match. Its meaning depends on the type: - meta_engagement: the engagement event. Defaults per source (page → page_engaged, instagram → ig_business_profile_all, video → video_watched). An unknown value is a 400 that lists...
body.sourceAudienceId (optional): local audience reference
Required for lookalike audiences. Use a SmallForce-local audience reference; raw provider IDs are rejected.
body.country (optional): string
2-letter code, required for lookalike audiences
body.ratio (optional): number
lookalike on Meta (0.01-0.20) and Pinterest (0.01-0.10, whole percents).
body.size (optional): "narrow" | "balanced" | "broad"
Rejected on Meta and Pinterest.
body.source (optional): "ads" | "organic_video" | "live_video" | "business_account"
body.campaignIds (optional): local campaign reference[]
Use a SmallForce-local campaign reference; raw provider IDs are rejected.
body.adIds (optional): local ad reference[]
Use a SmallForce-local ad reference; raw provider IDs are rejected.
body.urlContains (optional): string
website on Meta, TikTok and Google. Narrows the audience from all visitors to visitors of URLs containing this substring. Ignored when `rule` is supplied.
body.rule (optional): object
Meta only (a 400 elsewhere). Optional raw Meta rule, replacing the one we build. Omit it for all visitors of `pixelId`, or use `urlContains` for the common page-match case. **For `website`** this is Meta's Flexible Audience Rule and is...
body.customerFileSource (optional): string
Data source declaration for GDPR compliance (customer_list only)
body.spec (conditional): object
The targeting spec to store.
query: no client-supplied fields
Body variants:
- UploadedOrDerivedAudience (required: name, type): customer_list, website, lookalike or engagement audience (uploaded or derived from a source).
- SavedTargetingAudience (required: type, name, spec): A reusable, stored TargetingSpec. No member upload step, no adAccountId, the spec is the audience. Reference it later via `savedTargetingId` on POST /v1/ads/create.
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"type": "customer_list"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences get
Read a Meta custom audience
Usage: smallforce ads audiences get [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local audience id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences update
Update a Meta custom audience
Usage: smallforce ads audiences update [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local audience id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.name (optional): string
body.description (optional): string
body.spec (optional): object
Full replacement for the stored targeting spec.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences delete
Delete a Meta custom audience
Usage: smallforce ads audiences delete [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local audience id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences add-users
Add hashed customer records to a Meta custom audience
Usage: smallforce ads audiences add-users [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local audience id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.users (required): array<object>
query: no client-supplied fields
Request skeleton:
{
"body": {
"users": [
{
"email": "<email>"
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads audiences remove-users
Remove hashed customer records from a Meta custom audience
Usage: smallforce ads audiences remove-users [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local audience id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.users (required): array<object>
query: no client-supplied fields
Request skeleton:
{
"body": {
"users": [
{
"email": "<email>"
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads conversions
Inspect conversion quality and send Meta conversion events
smallforce ads conversions quality
Read Meta conversion match quality
Usage: smallforce ads conversions quality [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local conversion-destination id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads conversions send
Send conversion events to Meta
Usage: smallforce ads conversions send [options] <targetId>
| Argument | Description |
|---|---|
targetId | SmallForce-local conversion-destination id; raw Meta ids are rejected |
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.events (required): array<object{eventName, eventTime, eventId, user}>
body.testCode (optional): string
Test event code. Send it at the request root, never inside an event. A root-level `test_event_code` (Meta's own name) is accepted as an alias and must be a non-empty string; sending both with different values is a 400. - Meta: sent as...
body.consent (optional): object
Batch-level user consent. Required by Google for EEA/UK events under the Feb 2026 restrictions. - **Meta:** any DENIED flag enables Limited Data Use on every event in the batch (data_processing_options ["LDU"] with geolocation, country...
query: no client-supplied fields
Request skeleton:
{
"body": {
"events": [
{
"eventName": "Purchase",
"eventTime": 1788134400,
"eventId": "evt-001",
"user": {
"email": "<email>"
}
}
]
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads conversions destinations
List Meta conversion destinations
Usage: smallforce ads conversions destinations [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields
No provider JSON is required; omit --input and --input-file.
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads messaging
Create Meta messaging, call, and WhatsApp advertisements
smallforce ads messaging create
Create a Meta messaging advertisement
Usage: smallforce ads messaging create [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.retryOnServerError (optional): boolean
When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`. `false`...
body.creativeFeatures (optional): object
Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.
body.tracking (optional): object
body.name (required): string
Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
body.campaignName (optional): string
Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
body.adSetName (optional): string
Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
body.platformPostId (optional): local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference
Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. - Facebook IDs become object_story_id. - Instagram IDs become... Use a SmallForce-local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference; raw provider IDs are rejected.
body.existingPostId (optional): local social_post reference
Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
body.objectStoryId (optional): local social_post reference
Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
body.pageId (optional): local Facebook page or social account reference
Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
body.whatsappPhoneNumber (optional): string
WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. - Sent to the creative CTA and, when creating a new ad set, its promoted_object. - Meta can accept the number yet...
body.headline (optional): string
Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.
body.body (optional): string
Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
body.description (optional): string
Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. Meta shows it mainly on Facebook Feed placements,...
body.imageUrl (optional): SmallForce asset reference
Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.
body.video (optional): object
Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
body.welcomeMessage (optional): object{text}
Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
body.carouselCards (optional): array<object{imageUrl}>
Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. - Meta may reorder cards for performance, since `multi_share_optimized`...
body.optimizeCardOrder (optional): boolean
Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. - `false`: keeps the cards in the order given. Meta then takes at most 5...
body.creatives (optional): array<object>
Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId...
body.adSetId (optional): local ad_set reference
Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. The ad set then owns budget, targeting and... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
body.existingCampaignId (optional): local campaign reference
Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. - The campaign's objective... Use a SmallForce-local campaign reference; raw provider IDs are rejected.
body.budgetLevel (optional): "adset" | "campaign"
Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not...
body.budgetAmount (optional): number
Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.
body.budgetType (optional): "daily" | "lifetime"
Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.
body.currency (optional): string
ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
body.startDate (optional): string
When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used as is; one without an offset (`2027-01-15T10:00:00`) is read in the ad account's timezone, and a...
body.endDate (optional): string
ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.
body.countries (optional): array<string>
ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
body.cities (optional): array<object{key}>
City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km /...
body.regions (optional): array<object{key}>
Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
body.zips (optional): array<object{key}>
ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
body.metros (optional): array<object{key}>
DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
body.countryGroups (optional): array<"africa" | "asia" | "europe" | "north_america" | "south_america" | "oceania" | "central_america" | "caribbean" | "eea" | "euro_area" | "nafta" | "mercosur" | ...>
Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`....
body.customLocations (optional): array<object{latitude, longitude, radius, distanceUnit}>
Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
body.ageMin (optional): integer
body.ageMax (optional): integer
body.interests (optional): array<object{id}>
body.audienceId (optional): local audience reference
Custom audience ID to target. Use a SmallForce-local audience reference; raw provider IDs are rejected.
body.placements (optional): object
Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,...
body.gender (optional): "all" | "male" | "female"
Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.
body.languages (optional): array<string>
Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"). Meta numeric locale ids (e.g. "24" for English UK) are also...
body.places (optional): array<object{key}>
Meta place keys (from GET /v1/ads/targeting/search).
body.neighborhoods (optional): array<object{key}>
Meta neighborhood keys (from GET /v1/ads/targeting/search).
body.excludedLocations (optional): object
Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
body.behaviors (optional): array<object{id}>
Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across).
body.workPositions (optional): array<object{id}>
body.workEmployers (optional): array<object{id}>
body.workIndustries (optional): array<object{id}>
body.incomeTier (optional): "top_5" | "top_10" | "top_10_25" | "top_25_50"
Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
body.userOs (optional): array<string>
Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"].
body.userDevice (optional): array<string>
Meta `user_device`.
body.audienceInclude (optional): array<string>
Custom or lookalike audience ids to include.
body.audienceExclude (optional): array<string>
Custom or lookalike audience ids to exclude.
body.savedTargetingId (optional): string
ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields.
body.targeting (optional): object
Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.
body.rawTargeting (optional): object
Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one...
body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
Meta special ad categories on the new campaign.
body.specialAdCategoryCountry (optional): array<string>
Countries the special ad category applies to. Requires specialAdCategories.
body.advantageAudience (optional): 0 | 1
Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
body.objective (optional): "OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"
Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
body.status (optional): "ACTIVE" | "PAUSED"
Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.
body.campaignStatus (optional): "ACTIVE" | "PAUSED"
Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`. - `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). - `ACTIVE` with `status:...
body.adSetStatus (optional): "ACTIVE" | "PAUSED"
Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED`...
body.adStatus (optional): "ACTIVE" | "PAUSED"
Ad-level status, same semantics as `POST /v1/ads/create`. Sets the new ads' switch and overrides `status` for them, also with `adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all PAUSED to create every object paused.
body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`....
body.bidAmount (optional): number
Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.
body.roasAverageFloor (optional): number
Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.
body.dsaBeneficiary (optional): string
Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
body.dsaPayor (optional): string
Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
body.regionalRegulatedCategories (optional): array<string>
Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
body.regionalRegulationIdentities (optional): object
Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on API-created ad sets even when a default...
body.destination (optional): "whatsapp" | "messenger" | "instagram_direct"
Where the conversation opens when the ad is tapped. Set this OR `destinations`, not both.
body.destinations (optional): array<"whatsapp" | "messenger" | "instagram_direct">
Two or three messaging apps on ONE ad set, like Ads Manager's "all messaging apps". Set this OR `destination`, not both. The ad set gets Meta's combined destination_type (e.g. MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP) and the...
body.placementAssets (optional): object{rules}
A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (`adSetId`). Replaces top-level `imageUrl` / `video` (sending...
body.validateOnly (optional): boolean
Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with `adSetId`). Nothing is uploaded, created or stored; media is checked by URL. -...
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads messaging call
Create a Meta call advertisement
Usage: smallforce ads messaging call [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.retryOnServerError (optional): boolean
When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`. `false`...
body.creativeFeatures (optional): object
Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.
body.tracking (optional): object
body.name (required): string
Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
body.campaignName (optional): string
Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
body.adSetName (optional): string
Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
body.platformPostId (optional): local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference
Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. - Facebook IDs become object_story_id. - Instagram IDs become... Use a SmallForce-local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference; raw provider IDs are rejected.
body.existingPostId (optional): local social_post reference
Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
body.objectStoryId (optional): local social_post reference
Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
body.pageId (optional): local Facebook page or social account reference
Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
body.whatsappPhoneNumber (optional): string
WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. - Sent to the creative CTA and, when creating a new ad set, its promoted_object. - Meta can accept the number yet...
body.headline (optional): string
Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.
body.body (optional): string
Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
body.description (optional): string
Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. Meta shows it mainly on Facebook Feed placements,...
body.imageUrl (optional): SmallForce asset reference
Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.
body.video (optional): object
Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
body.welcomeMessage (optional): object{text}
Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
body.carouselCards (optional): array<object{imageUrl}>
Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. - Meta may reorder cards for performance, since `multi_share_optimized`...
body.optimizeCardOrder (optional): boolean
Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. - `false`: keeps the cards in the order given. Meta then takes at most 5...
body.creatives (optional): array<object>
Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId...
body.adSetId (optional): local ad_set reference
Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. The ad set then owns budget, targeting and... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
body.existingCampaignId (optional): local campaign reference
Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. - The campaign's objective... Use a SmallForce-local campaign reference; raw provider IDs are rejected.
body.budgetLevel (optional): "adset" | "campaign"
Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not...
body.budgetAmount (optional): number
Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.
body.budgetType (optional): "daily" | "lifetime"
Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.
body.currency (optional): string
ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
body.startDate (optional): string
When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used as is; one without an offset (`2027-01-15T10:00:00`) is read in the ad account's timezone, and a...
body.endDate (optional): string
ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.
body.countries (optional): array<string>
ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
body.cities (optional): array<object{key}>
City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km /...
body.regions (optional): array<object{key}>
Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
body.zips (optional): array<object{key}>
ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
body.metros (optional): array<object{key}>
DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
body.countryGroups (optional): array<"africa" | "asia" | "europe" | "north_america" | "south_america" | "oceania" | "central_america" | "caribbean" | "eea" | "euro_area" | "nafta" | "mercosur" | ...>
Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`....
body.customLocations (optional): array<object{latitude, longitude, radius, distanceUnit}>
Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
body.ageMin (optional): integer
body.ageMax (optional): integer
body.interests (optional): array<object{id}>
body.audienceId (optional): local audience reference
Custom audience ID to target. Use a SmallForce-local audience reference; raw provider IDs are rejected.
body.placements (optional): object
Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,...
body.gender (optional): "all" | "male" | "female"
Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.
body.languages (optional): array<string>
Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"). Meta numeric locale ids (e.g. "24" for English UK) are also...
body.places (optional): array<object{key}>
Meta place keys (from GET /v1/ads/targeting/search).
body.neighborhoods (optional): array<object{key}>
Meta neighborhood keys (from GET /v1/ads/targeting/search).
body.excludedLocations (optional): object
Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
body.behaviors (optional): array<object{id}>
Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across).
body.workPositions (optional): array<object{id}>
body.workEmployers (optional): array<object{id}>
body.workIndustries (optional): array<object{id}>
body.incomeTier (optional): "top_5" | "top_10" | "top_10_25" | "top_25_50"
Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
body.userOs (optional): array<string>
Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"].
body.userDevice (optional): array<string>
Meta `user_device`.
body.audienceInclude (optional): array<string>
Custom or lookalike audience ids to include.
body.audienceExclude (optional): array<string>
Custom or lookalike audience ids to exclude.
body.savedTargetingId (optional): string
ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields.
body.targeting (optional): object
Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.
body.rawTargeting (optional): object
Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one...
body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
Meta special ad categories on the new campaign.
body.specialAdCategoryCountry (optional): array<string>
Countries the special ad category applies to. Requires specialAdCategories.
body.advantageAudience (optional): 0 | 1
Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
body.objective (optional): "OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"
Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
body.status (optional): "ACTIVE" | "PAUSED"
Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.
body.campaignStatus (optional): "ACTIVE" | "PAUSED"
Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`. - `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). - `ACTIVE` with `status:...
body.adSetStatus (optional): "ACTIVE" | "PAUSED"
Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED`...
body.adStatus (optional): "ACTIVE" | "PAUSED"
Ad-level status, same semantics as `POST /v1/ads/create`. Sets the new ads' switch and overrides `status` for them, also with `adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all PAUSED to create every object paused.
body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`....
body.bidAmount (optional): number
Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.
body.roasAverageFloor (optional): number
Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.
body.dsaBeneficiary (optional): string
Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
body.dsaPayor (optional): string
Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
body.regionalRegulatedCategories (optional): array<string>
Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
body.regionalRegulationIdentities (optional): object
Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on API-created ad sets even when a default...
body.phoneNumber (required): string
E.164 number the CALL_NOW CTA dials (e.g. +34600111222).
body.linkUrl (required): string(uri)
Website shown as the creative's link. Required: Meta rejects tel: as link_data.link; the phone number rides only the CTA.
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource",
"phoneNumber": "<phoneNumber>",
"linkUrl": "https://example.com/offer"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads messaging whatsapp
Create a click-to-WhatsApp advertisement
Usage: smallforce ads messaging whatsapp [options]
| Option | Description |
|---|---|
--account <adAccountId> | Local id from ads accounts list |
--input <json> | Inline JSON request object |
--input-file <path> | JSON request file; use - to read from stdin |
Also accepts the common options listed at the top of this page.
Provider parameters (--input or --input-file):
body:
body.retryOnServerError (optional): boolean
When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`. `false`...
body.creativeFeatures (optional): object
Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.
body.tracking (optional): object
body.name (required): string
Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
body.campaignName (optional): string
Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
body.adSetName (optional): string
Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
body.platformPostId (optional): local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference
Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. - Facebook IDs become object_story_id. - Instagram IDs become... Use a SmallForce-local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference; raw provider IDs are rejected.
body.existingPostId (optional): local social_post reference
Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
body.objectStoryId (optional): local social_post reference
Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
body.pageId (optional): local Facebook page or social account reference
Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
body.whatsappPhoneNumber (optional): string
WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. - Sent to the creative CTA and, when creating a new ad set, its promoted_object. - Meta can accept the number yet...
body.headline (optional): string
Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.
body.body (optional): string
Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
body.description (optional): string
Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. Meta shows it mainly on Facebook Feed placements,...
body.imageUrl (optional): SmallForce asset reference
Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.
body.video (optional): object
Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
body.welcomeMessage (optional): object{text}
Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
body.carouselCards (optional): array<object{imageUrl}>
Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. - Meta may reorder cards for performance, since `multi_share_optimized`...
body.optimizeCardOrder (optional): boolean
Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. - `false`: keeps the cards in the order given. Meta then takes at most 5...
body.creatives (optional): array<object>
Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId...
body.adSetId (optional): local ad_set reference
Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. The ad set then owns budget, targeting and... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
body.existingCampaignId (optional): local campaign reference
Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. - The campaign's objective... Use a SmallForce-local campaign reference; raw provider IDs are rejected.
body.budgetLevel (optional): "adset" | "campaign"
Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not...
body.budgetAmount (optional): number
Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.
body.budgetType (optional): "daily" | "lifetime"
Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.
body.currency (optional): string
ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
body.startDate (optional): string
When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used as is; one without an offset (`2027-01-15T10:00:00`) is read in the ad account's timezone, and a...
body.endDate (optional): string
ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.
body.countries (optional): array<string>
ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
body.cities (optional): array<object{key}>
City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km /...
body.regions (optional): array<object{key}>
Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
body.zips (optional): array<object{key}>
ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
body.metros (optional): array<object{key}>
DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
body.countryGroups (optional): array<"africa" | "asia" | "europe" | "north_america" | "south_america" | "oceania" | "central_america" | "caribbean" | "eea" | "euro_area" | "nafta" | "mercosur" | ...>
Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`....
body.customLocations (optional): array<object{latitude, longitude, radius, distanceUnit}>
Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
body.ageMin (optional): integer
body.ageMax (optional): integer
body.interests (optional): array<object{id}>
body.audienceId (optional): local audience reference
Custom audience ID to target. Use a SmallForce-local audience reference; raw provider IDs are rejected.
body.placements (optional): object
Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,...
body.gender (optional): "all" | "male" | "female"
Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.
body.languages (optional): array<string>
Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"). Meta numeric locale ids (e.g. "24" for English UK) are also...
body.places (optional): array<object{key}>
Meta place keys (from GET /v1/ads/targeting/search).
body.neighborhoods (optional): array<object{key}>
Meta neighborhood keys (from GET /v1/ads/targeting/search).
body.excludedLocations (optional): object
Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
body.behaviors (optional): array<object{id}>
Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across).
body.workPositions (optional): array<object{id}>
body.workEmployers (optional): array<object{id}>
body.workIndustries (optional): array<object{id}>
body.incomeTier (optional): "top_5" | "top_10" | "top_10_25" | "top_25_50"
Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
body.userOs (optional): array<string>
Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"].
body.userDevice (optional): array<string>
Meta `user_device`.
body.audienceInclude (optional): array<string>
Custom or lookalike audience ids to include.
body.audienceExclude (optional): array<string>
Custom or lookalike audience ids to exclude.
body.savedTargetingId (optional): string
ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields.
body.targeting (optional): object
Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.
body.rawTargeting (optional): object
Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one...
body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
Meta special ad categories on the new campaign.
body.specialAdCategoryCountry (optional): array<string>
Countries the special ad category applies to. Requires specialAdCategories.
body.advantageAudience (optional): 0 | 1
Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
body.objective (optional): "OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"
Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
body.status (optional): "ACTIVE" | "PAUSED"
Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.
body.campaignStatus (optional): "ACTIVE" | "PAUSED"
Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`. - `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). - `ACTIVE` with `status:...
body.adSetStatus (optional): "ACTIVE" | "PAUSED"
Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED`...
body.adStatus (optional): "ACTIVE" | "PAUSED"
Ad-level status, same semantics as `POST /v1/ads/create`. Sets the new ads' switch and overrides `status` for them, also with `adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all PAUSED to create every object paused.
body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`....
body.bidAmount (optional): number
Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.
body.roasAverageFloor (optional): number
Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.
body.dsaBeneficiary (optional): string
Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
body.dsaPayor (optional): string
Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
body.regionalRegulatedCategories (optional): array<string>
Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
body.regionalRegulationIdentities (optional): object
Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on API-created ad sets even when a default...
query: no client-supplied fields
Request skeleton:
{
"body": {
"name": "Example Meta Ads resource"
}
}
Local relationship syntax:
{"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
{"$smallforceAsset":"<SmallForce asset UUID>"}
SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.
smallforce ads google
Manage Google Ads through SmallForce-local, organization-scoped IDs
Full reference: Google Ads commands.
smallforce ads tiktok
Manage TikTok Ads through SmallForce-local, organization-scoped IDs
Full reference: TikTok Ads commands.