late-sdk 0.0.1379 → 0.0.1380

data/docs/ConnectApi.md

@@ -421,7 +421,7 @@ end
 
 Connect ads for a platform
 
-Starts connecting a platform's ads account, giving you a dedicated ads connection to manage campaigns without touching posting accounts.  Creates a dedicated ads SocialAccount for the specified platform.  **Meta business login (opt-in).** Set `loginMode=business` for `facebook` or `instagram` to use Facebook Login for Business and a Business Integration System User token. No posting account is created or required. This mode always returns an authUrl; it returns 503 when the server has no META_ADS_CONFIG_ID. Complete the dialog in a browser. The callback creates or reconnects only the metaads account, preserving its ID and history. Non-empty successful subscription results replace subscribedAdAccountIds to remove stale grants; an empty result leaves routing unchanged. A reconnect is accepted when the new grant shares at least one ad account with the existing connection (its scopedAdAccountIds plus the previous grant, or the ad accounts its old token can read when neither is stored), so re-running the dialog can add, drop or swap ad accounts. A grant with zero overlap is refused before changing the account and redirects with `error=invalid_field_value` and `error_reason=reconnect_mismatch` (disconnect and connect again to switch); when the previous ad accounts cannot be read at all, it redirects with `error=reconnect_required`. On an accepted reconnect the scope is rebuilt from the new grant: `adAccountIds` passed on the re-auth become the scope; otherwise a stored scope keeps its ad accounts that are still granted plus any granted for the first time, and an unscoped connection follows the new grant.  Pass `pageId` to select a granted Page for creatives and lead forms. API integrations otherwise reuse the previous Page or sole granted Page. Multiple Pages without a selection return 400 with available Page IDs for API integrations; restart with pageId. Dashboard session logins use the sole current grant automatically or open the existing Facebook Page picker for several grants, including reconnects. Selection completes the Meta Ads connection. Success redirects with connected=metaads, profileId and accountId. Every failure after Meta's dialog redirects to redirect_url (or the dashboard) with `error`, `platform=metaads`, `error_message`, `request_id` and `stage`, plus `is_user_fixable` and `error_reason` when known. `error` is the API error code: `invalid_field_value` with `error_reason` `no_pages_granted` (no Page ticked), `page_not_granted` (pageId not in the grant), `ad_accounts_not_granted` or `reconnect_mismatch` (the grant shares no ad account with the existing connection); `reconnect_required`, `ads_addon_required`, `payment_required` and the profile gates of GET /v1/connect/{platform}; `invalid_state` with `error_reason=state_expired` after the 30-minute window; `connection_failed` when Meta refuses the code (e.g. a replayed callback). A denial in the dialog is `meta_ads_authorization_denied` with the `platform_error*` params. Only a state that cannot be decrypted at all still answers 400 JSON, since it names no redirect_url. Business login reports metadata.tokenType=system-user in GET /v1/accounts. An absent Meta expires_in leaves tokenExpiresAt absent; no personal-token re-exchange occurs. Subsequent classic requests can change the ad-account scope using the business token; force=true (or disconnecting the business connection first) switches the profile to the standard Facebook login; the ads account is then held by the user token.  **Same-token platforms (facebook, instagram, linkedin, pinterest).** The ads SocialAccount (metaads, linkedinads, pinterestads) reuses the OAuth token of the parent posting account, but only when an active parent exists and, for facebook and instagram, its stored token carries ads_management and ads_read (linkedin and pinterest need no extra scope). In that case no extra OAuth happens and the response is alreadyConnected: true.  When no such parent exists, or the scopes are missing, the endpoint returns an authUrl and a full OAuth round trip is required. When a parent exists but carries no token usable for ad accounts, the call fails with 400 RECONNECT_REQUIRED. Independently of the branch, the call can return 403 ADS_ADDON_REQUIRED without the ads add-on and 402 PAYMENT_REQUIRED when the billing gate is closed.  Meta Ads prerequisite: connecting Meta Ads (via facebook or instagram) requires a Facebook Page. Not because the ad account is read through a Page, but because both parent posting accounts are: the facebook flow only offers Pages you manage, and the instagram flow with loginMethod=facebook_login only offers Instagram accounts linked to one of those Pages. Without a Page there is no parent account to inherit a token from. A user who manages no Facebook Page cannot complete this connection, and the facebook flow ends with error=no_facebook_pages.  **Separate-token platforms (tiktok, twitter).** Starts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (tiktokads, xads) with its own token. If the ads account already exists, returns alreadyConnected: true.   - tiktok: accountId is OPTIONAL. With accountId, the new tiktokads account links to that posting account (parentAccountId set), so Spark Ads + standalone ads using the posting TT_USER identity become available. Without accountId, ads-only mode kicks in: the new tiktokads account has parentAccountId=null and standalone ads use a synthetic CUSTOMIZED_USER (\"Brand Identity\"); Spark Ads are unavailable because TikTok requires a posting account for them. The Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).   - twitter (X Ads): accountId is REQUIRED. There's no ads-only mode, because tweets need to be authored by a real X user.  **Standalone platforms (googleads).** Starts the Google Ads OAuth flow and creates a standalone ads SocialAccount (googleads) with no parent. If the account already exists and has at least one discovered Google Ads customer account, returns alreadyConnected: true. When the existing connection has zero customer accounts (metadata.googleAdsCustomerIds is empty) or is flagged needsReconnection, it returns an authUrl instead; completing it reconnects the same account (same accountId) and re-runs ad account discovery. Discovery includes the client accounts under every manager (MCC) the Google user can reach, and includes Google Ads test accounts, which Google always reports with status CLOSED. When discovery finds no usable customer account, the callback saves nothing and redirects with `error=google_ads_no_ad_accounts`, `platform=googleads` and an `error_message` naming each customer the Google user can reach and why it was left out (for example CUSTOMER_NOT_ENABLED). Sign in with a Google user that has access to the ad account or to its manager account. When the user unticks the Google Ads permission on Google's consent screen, the callback saves nothing and redirects with `error=missing_google_permissions`, `platform=googleads`, `is_user_fixable=true` and `missing_scopes`. An existing connection whose token lacks that permission is flagged needsReconnection, and the health endpoints report \"Google Ads permission not granted\"; this endpoint then returns an authUrl for it.  Ads accounts appear as regular SocialAccount documents with ads platform values (e.g., metaads, tiktokads) in GET /v1/accounts. 
+Starts connecting a platform's ads account, giving you a dedicated ads connection to manage campaigns without touching posting accounts.  Creates a dedicated ads SocialAccount for the specified platform.  **Meta business login (opt-in).** Set `loginMode=business` for `facebook` or `instagram` to use Facebook Login for Business and a Business Integration System User token. No posting account is created or required. This mode always returns an authUrl; it returns 503 when the server has no META_ADS_CONFIG_ID. Complete the dialog in a browser. The callback creates or reconnects only the metaads account, preserving its ID and history. Non-empty successful subscription results replace subscribedAdAccountIds to remove stale grants; an empty result leaves routing unchanged. A reconnect is accepted when the new grant shares at least one ad account with the existing connection (its scopedAdAccountIds plus the previous grant, or the ad accounts its old token can read when neither is stored), so re-running the dialog can add, drop or swap ad accounts. A grant with zero overlap is refused before changing the account and redirects with `error=invalid_field_value` and `error_reason=reconnect_mismatch` (disconnect and connect again to switch); when the previous ad accounts cannot be read at all, it redirects with `error=reconnect_required`. On an accepted reconnect the scope is rebuilt from the new grant: `adAccountIds` passed on the re-auth become the scope; otherwise a stored scope keeps its ad accounts that are still granted plus any granted for the first time, and an unscoped connection follows the new grant.  Pass `pageId` to select a granted Page for creatives and lead forms. API integrations otherwise reuse the previous Page or sole granted Page. Multiple Pages without a selection return 400 with available Page IDs for API integrations; restart with pageId. Dashboard session logins use the sole current grant automatically or open the existing Facebook Page picker for several grants, including reconnects. Selection completes the Meta Ads connection. Success redirects with connected=metaads, profileId and accountId. Every failure after Meta's dialog redirects to redirect_url (or the dashboard) with `error`, `platform=metaads`, `error_message`, `request_id` and `stage`, plus `is_user_fixable` and `error_reason` when known. `error` is the API error code: `invalid_field_value` with `error_reason` `no_pages_granted` (no Page ticked), `page_not_granted` (pageId not in the grant), `ad_accounts_not_granted` or `reconnect_mismatch` (the grant shares no ad account with the existing connection); `reconnect_required`, `ads_addon_required`, `payment_required` and the profile gates of GET /v1/connect/{platform}; `invalid_state` with `error_reason=state_expired` after the 30-minute window; `connection_failed` when Meta refuses the code (e.g. a replayed callback). A denial in the dialog is `meta_ads_authorization_denied` with the `platform_error*` params. Only a state that cannot be decrypted at all still answers 400 JSON, since it names no redirect_url. Business login reports metadata.tokenType=system-user in GET /v1/accounts. An absent Meta expires_in leaves tokenExpiresAt absent; no personal-token re-exchange occurs. Subsequent classic requests can change the ad-account scope using the business token; force=true (or disconnecting the business connection first) switches the profile to the standard Facebook login; the ads account is then held by the user token.  **Same-token platforms (facebook, instagram, linkedin, pinterest).** The ads SocialAccount (metaads, linkedinads, pinterestads) reuses the OAuth token of the parent posting account, but only when an active parent exists and, for facebook and instagram, its stored token carries ads_management and ads_read (linkedin and pinterest need no extra scope). In that case no extra OAuth happens and the response is alreadyConnected: true.  When no such parent exists, or the scopes are missing, the endpoint returns an authUrl and a full OAuth round trip is required. When a parent exists but carries no token usable for ad accounts, the call fails with 400 RECONNECT_REQUIRED. Independently of the branch, the call can return 403 ADS_ADDON_REQUIRED without the ads add-on and 402 PAYMENT_REQUIRED when the billing gate is closed.  Meta Ads prerequisite: connecting Meta Ads (via facebook or instagram) requires a Facebook Page. Not because the ad account is read through a Page, but because both parent posting accounts are: the facebook flow only offers Pages you manage, and the instagram flow with loginMethod=facebook_login only offers Instagram accounts linked to one of those Pages. Without a Page there is no parent account to inherit a token from. A user who manages no Facebook Page cannot complete this connection, and the facebook flow ends with error=no_facebook_pages.  **Separate-token platforms (tiktok, twitter).** Starts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (tiktokads, xads) with its own token. If the ads account already exists, returns alreadyConnected: true.   - tiktok: accountId is OPTIONAL. With accountId, the new tiktokads account links to that posting account (parentAccountId set), so Spark Ads + standalone ads using the posting TT_USER identity become available. Without accountId, ads-only mode kicks in: the new tiktokads account has parentAccountId=null and standalone ads use a synthetic CUSTOMIZED_USER (\"Brand Identity\"); Spark Ads are unavailable because TikTok requires a posting account for them. The Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).   - twitter (X Ads): accountId is REQUIRED. There's no ads-only mode, because tweets need to be authored by a real X user.  **Standalone platforms (googleads).** Starts the Google Ads OAuth flow and creates a standalone ads SocialAccount (googleads) with no parent. If the account already exists and has at least one discovered Google Ads customer account, returns alreadyConnected: true. When the existing connection has zero customer accounts (metadata.googleAdsCustomerIds is empty) or is flagged needsReconnection, it returns an authUrl instead; completing it reconnects the same account (same accountId) and re-runs ad account discovery. Discovery includes the client accounts under every manager (MCC) the Google user can reach, and includes Google Ads test accounts, which Google always reports with status CLOSED. When discovery finds no usable customer account, the callback saves nothing and redirects with `error=google_ads_no_ad_accounts`, `platform=googleads` and an `error_message` naming each customer the Google user can reach and why it was left out (for example CUSTOMER_NOT_ENABLED). Sign in with a Google user that has access to the ad account or to its manager account. When the user unticks the Google Ads permission on Google's consent screen, the callback saves nothing and redirects with `error=missing_google_permissions`, `platform=googleads`, `is_user_fixable=true` and `missing_scopes`. An existing connection whose token lacks that permission is flagged needsReconnection, and the health endpoints report \"Google Ads permission not granted\"; this endpoint then returns an authUrl for it.  **Standalone platforms (redditads).** Starts the Reddit Ads OAuth flow (Reddit permissions `adsread`, `adsedit` and `adsconversions`) and creates a standalone ads SocialAccount (redditads) with no parent, separate from any organic `reddit` posting account. It is reached only as `redditads` in the path. If an active Reddit Ads connection already exists on the profile, is not flagged needsReconnection and holds every one of those permissions, returns alreadyConnected: true. Otherwise it returns an authUrl; completing it reconnects the same account (same accountId). A connection authorized without `adsconversions` keeps managing ads, but the health endpoints list an issue asking to reconnect Reddit Ads and allow every permission, the Conversions API answers 403 `reconnect_required`, and this endpoint returns an authUrl for it. Discovery lists every Reddit ad account the Reddit user can reach. When the user unticks `adsread` or `adsedit` on Reddit's consent screen the callback saves nothing and redirects with `error=reddit_ads_scope_not_granted`; when the user reaches no Reddit ad account it redirects with `error=reddit_ads_no_ad_accounts` (both with `platform=redditads`). Without `redirect_url` the browser lands on the Zernio dashboard's ad account picker for the new connection.  Ads accounts appear as regular SocialAccount documents with ads platform values (e.g., metaads, tiktokads) in GET /v1/accounts. 
 
 ### Examples
 
@@ -441,11 +441,11 @@ opts = {
   login_mode: 'classic', # String | Meta ads authorization mode. Business login is opt-in for Facebook and Instagram; classic preserves the posting-account flow.
   permission_level: 'full', # String | Business login only. Ad-account permission the connection's system user will hold. `full` asks the owner for Full control (MANAGE; required to create pixels and other account-level assets through Zernio). `advertise` asks for Manage campaigns (ADVERTISE), enough for campaigns, ad sets, creatives, ads, media and reporting, for owners who will not grant billing-level control to an integration. Either way Meta only lets a business admin complete the grant. 503 if the advertise configuration is not set up.
   page_id: '811889972008357', # String | Business login only. Facebook Page ID to select from the token grants for ad creatives and lead forms.
-  account_id: 'account_id_example', # String | Existing SocialAccount ID. Required for `twitter` (X Ads). Optional for `tiktok`: omit to enter ads-only mode (no TikTok posting account linked; ad creation uses a Brand Identity instead of a TT_USER). For same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`) it picks which posting account the ads connection uses when the profile holds several of that platform; with one it can be omitted, and an id that names no active account of the platform on the profile is ignored, except with `force=true` when it names the posting account the profile's ads connection hangs off: that account is no longer connected, so the call returns 409 `reconnect_required` instead of reconnecting another account. Reconnect it via GET /v1/connect/{platform} first. Ignored for standalone platforms (`googleads`). 
-  redirect_url: 'redirect_url_example', # String | Custom URL the browser is sent to once the OAuth flow finishes. Honored on every ads platform, including the separate-token (`tiktok`, `twitter`) and standalone (`googleads`) flows. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. On success `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`) append `connected`, `profileId`, `accountId`, `username` and, on API-key calls, `connect_token`. On failure the same error contract applies as on GET /v1/connect/{platform}: `error` and `platform` are always appended, other params are optional, and the value list there is not exhaustive. On the tiktok, twitter and googleads flows `platform` carries the ads platform id (`tiktokads`, `xads`, `googleads`), not the value used in the request path. When omitted, the browser lands on the Zernio dashboard. 
+  account_id: 'account_id_example', # String | Existing SocialAccount ID. Required for `twitter` (X Ads). Optional for `tiktok`: omit to enter ads-only mode (no TikTok posting account linked; ad creation uses a Brand Identity instead of a TT_USER). For same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`) it picks which posting account the ads connection uses when the profile holds several of that platform; with one it can be omitted, and an id that names no active account of the platform on the profile is ignored, except with `force=true` when it names the posting account the profile's ads connection hangs off: that account is no longer connected, so the call returns 409 `reconnect_required` instead of reconnecting another account. Reconnect it via GET /v1/connect/{platform} first. Ignored for standalone platforms (`googleads`, `redditads`). 
+  redirect_url: 'redirect_url_example', # String | Custom URL the browser is sent to once the OAuth flow finishes. Honored on every ads platform, including the separate-token (`tiktok`, `twitter`) and standalone (`googleads`, `redditads`) flows. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. On success `tiktok` lands on the URL unchanged; `twitter`, `googleads` and `redditads` append `connected` (the ads platform id: `xads`, `googleads` or `redditads`), `profileId`, `accountId` (the ads connection) and `username`; and the same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`) append `connected`, `profileId`, `accountId`, `username` and, on API-key calls, `connect_token`. On failure the same error contract applies as on GET /v1/connect/{platform}: `error` and `platform` are always appended, other params are optional, and the value list there is not exhaustive. On the tiktok, twitter, googleads and redditads flows `platform` carries the ads platform id (`tiktokads`, `xads`, `googleads`, `redditads`), not the value used in the request path. When omitted, the browser lands on the Zernio dashboard. 
   headless: true, # Boolean | Enable headless mode (same-token platforms only)
   force: true, # Boolean | Force a fresh OAuth even when an account already exists. Normally the endpoint returns `alreadyConnected: true` whenever a connected account is found, keying off its active state rather than token liveness. Set `force=true` to bypass that and always receivean `authUrl`. Completing the returned OAuth refreshes the stored token on the existing posting and ads accounts in place. An `alreadyConnected` response re-runs ad discovery and webhook subscriptions in the background at most once every 15 minutes per ads account (always when the call changes the ad-account scope), so it is not a sync trigger. To check the connection's health, read GET /v1/ads/accounts?accountId=<ads account ID>. 
-  ad_account_id: 'act_1330190928038136', # String | Scope ad sync to a single platform ad account. Without this param, sync covers every ad account the connected token can see. Business-login reconnects preserve the existing scope; supplied IDs are checked against the new grant. To change that scope after migration, call this endpoint with the IDs and omit loginMode. Supported on `facebook`/`instagram` (Meta, `act_<digits>`), `linkedin` (bare numeric sponsored-account id), `googleads` (bare customer id digits) and `twitter` (X Ads, base36 account id). `tiktok` scopes advertisers at OAuth and `pinterest` has no ads discovery, so both ignore it. Meta ids are additionally validated against the connected token: an id the token cannot see returns 400 `invalid_field_value`, and an id it can see but that Meta marks unusable for ads (disabled, closed, under risk review, settlement pending) returns 400 `ad_account_unusable` with `details.accountStatus` (Meta's `account_status`) and, when Meta gives one, `details.disableReason`. Unsettled and in-grace accounts are accepted, matching the `selectable` flag of `GET /v1/ads/accounts`. Setting a scope also removes already synced ads, campaigns, ad sets and keywords from de-scoped ad accounts. On Meta the scope also decides which ad accounts Zernio subscribes to ad-account webhooks: only the scoped ones, instead of every ad account the login can reach. The scope is kept when this call returns an `authUrl`, so the Meta Ads account created after OAuth is scoped (and only its scoped ad accounts synced and subscribed) from the start. On `googleads` the scope is kept through OAuth when `redirect_url` is set, so the Google Ads connection created after OAuth syncs only its scoped customers from the first sync. For multiple accounts use `adAccountIds` instead. 
+  ad_account_id: 'act_1330190928038136', # String | Scope ad sync to a single platform ad account. Without this param, sync covers every ad account the connected token can see. Business-login reconnects preserve the existing scope; supplied IDs are checked against the new grant. To change that scope after migration, call this endpoint with the IDs and omit loginMode. Supported on `facebook`/`instagram` (Meta, `act_<digits>`), `linkedin` (bare numeric sponsored-account id), `googleads` (bare customer id digits), `redditads` (Reddit ad account id, `a2_<id>` or `t2_<id>`) and `twitter` (X Ads, base36 account id). `tiktok` scopes advertisers at OAuth and `pinterest` has no ads discovery, so both ignore it. Meta ids are additionally validated against the connected token: an id the token cannot see returns 400 `invalid_field_value`, and an id it can see but that Meta marks unusable for ads (disabled, closed, under risk review, settlement pending) returns 400 `ad_account_unusable` with `details.accountStatus` (Meta's `account_status`) and, when Meta gives one, `details.disableReason`. Unsettled and in-grace accounts are accepted, matching the `selectable` flag of `GET /v1/ads/accounts`. Setting a scope also removes already synced ads, campaigns, ad sets and keywords from de-scoped ad accounts. On Meta the scope also decides which ad accounts Zernio subscribes to ad-account webhooks: only the scoped ones, instead of every ad account the login can reach. The scope is kept when this call returns an `authUrl`, so the Meta Ads account created after OAuth is scoped (and only its scoped ad accounts synced and subscribed) from the start. On `googleads` and `redditads` the scope is kept through OAuth when `redirect_url` is set, so the connection created after OAuth syncs only its scoped ad accounts from the first sync. For multiple accounts use `adAccountIds` instead. 
   ad_account_ids: ['inner_example'] # Array<String> | Scope ad sync to multiple platform ad accounts (same platform support and id shapes as `adAccountId`). Repeat the param (`?adAccountIds=act_1&adAccountIds=act_2`) or comma-separate (`?adAccountIds=act_1,act_2`). Persisted server-side; latest call wins, and de-scoped ad accounts have their synced ads, campaigns, ad sets and keywords removed. On Meta only the scoped ad accounts get webhook subscriptions, including when the call starts a fresh OAuth. Omitting both `adAccountId` and `adAccountIds` keeps any previously persisted scope unchanged (no scope means every reachable ad account). 
 }
 
@@ -485,11 +485,11 @@ end
 | **login_mode** | **String** | Meta ads authorization mode. Business login is opt-in for Facebook and Instagram; classic preserves the posting-account flow. | [optional][default to &#39;classic&#39;] |
 | **permission_level** | **String** | Business login only. Ad-account permission the connection&#39;s system user will hold. &#x60;full&#x60; asks the owner for Full control (MANAGE; required to create pixels and other account-level assets through Zernio). &#x60;advertise&#x60; asks for Manage campaigns (ADVERTISE), enough for campaigns, ad sets, creatives, ads, media and reporting, for owners who will not grant billing-level control to an integration. Either way Meta only lets a business admin complete the grant. 503 if the advertise configuration is not set up. | [optional][default to &#39;full&#39;] |
 | **page_id** | **String** | Business login only. Facebook Page ID to select from the token grants for ad creatives and lead forms. | [optional] |
-| **account_id** | **String** | Existing SocialAccount ID. Required for &#x60;twitter&#x60; (X Ads). Optional for &#x60;tiktok&#x60;: omit to enter ads-only mode (no TikTok posting account linked; ad creation uses a Brand Identity instead of a TT_USER). For same-token platforms (&#x60;facebook&#x60;, &#x60;instagram&#x60;, &#x60;linkedin&#x60;, &#x60;pinterest&#x60;) it picks which posting account the ads connection uses when the profile holds several of that platform; with one it can be omitted, and an id that names no active account of the platform on the profile is ignored, except with &#x60;force&#x3D;true&#x60; when it names the posting account the profile&#39;s ads connection hangs off: that account is no longer connected, so the call returns 409 &#x60;reconnect_required&#x60; instead of reconnecting another account. Reconnect it via GET /v1/connect/{platform} first. Ignored for standalone platforms (&#x60;googleads&#x60;).  | [optional] |
-| **redirect_url** | **String** | Custom URL the browser is sent to once the OAuth flow finishes. Honored on every ads platform, including the separate-token (&#x60;tiktok&#x60;, &#x60;twitter&#x60;) and standalone (&#x60;googleads&#x60;) flows. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. On success &#x60;tiktok&#x60;, &#x60;twitter&#x60; and &#x60;googleads&#x60; land on the URL unchanged, while the same-token platforms (&#x60;facebook&#x60;, &#x60;instagram&#x60;, &#x60;linkedin&#x60;, &#x60;pinterest&#x60;) append &#x60;connected&#x60;, &#x60;profileId&#x60;, &#x60;accountId&#x60;, &#x60;username&#x60; and, on API-key calls, &#x60;connect_token&#x60;. On failure the same error contract applies as on GET /v1/connect/{platform}: &#x60;error&#x60; and &#x60;platform&#x60; are always appended, other params are optional, and the value list there is not exhaustive. On the tiktok, twitter and googleads flows &#x60;platform&#x60; carries the ads platform id (&#x60;tiktokads&#x60;, &#x60;xads&#x60;, &#x60;googleads&#x60;), not the value used in the request path. When omitted, the browser lands on the Zernio dashboard.  | [optional] |
+| **account_id** | **String** | Existing SocialAccount ID. Required for &#x60;twitter&#x60; (X Ads). Optional for &#x60;tiktok&#x60;: omit to enter ads-only mode (no TikTok posting account linked; ad creation uses a Brand Identity instead of a TT_USER). For same-token platforms (&#x60;facebook&#x60;, &#x60;instagram&#x60;, &#x60;linkedin&#x60;, &#x60;pinterest&#x60;) it picks which posting account the ads connection uses when the profile holds several of that platform; with one it can be omitted, and an id that names no active account of the platform on the profile is ignored, except with &#x60;force&#x3D;true&#x60; when it names the posting account the profile&#39;s ads connection hangs off: that account is no longer connected, so the call returns 409 &#x60;reconnect_required&#x60; instead of reconnecting another account. Reconnect it via GET /v1/connect/{platform} first. Ignored for standalone platforms (&#x60;googleads&#x60;, &#x60;redditads&#x60;).  | [optional] |
+| **redirect_url** | **String** | Custom URL the browser is sent to once the OAuth flow finishes. Honored on every ads platform, including the separate-token (&#x60;tiktok&#x60;, &#x60;twitter&#x60;) and standalone (&#x60;googleads&#x60;, &#x60;redditads&#x60;) flows. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. On success &#x60;tiktok&#x60; lands on the URL unchanged; &#x60;twitter&#x60;, &#x60;googleads&#x60; and &#x60;redditads&#x60; append &#x60;connected&#x60; (the ads platform id: &#x60;xads&#x60;, &#x60;googleads&#x60; or &#x60;redditads&#x60;), &#x60;profileId&#x60;, &#x60;accountId&#x60; (the ads connection) and &#x60;username&#x60;; and the same-token platforms (&#x60;facebook&#x60;, &#x60;instagram&#x60;, &#x60;linkedin&#x60;, &#x60;pinterest&#x60;) append &#x60;connected&#x60;, &#x60;profileId&#x60;, &#x60;accountId&#x60;, &#x60;username&#x60; and, on API-key calls, &#x60;connect_token&#x60;. On failure the same error contract applies as on GET /v1/connect/{platform}: &#x60;error&#x60; and &#x60;platform&#x60; are always appended, other params are optional, and the value list there is not exhaustive. On the tiktok, twitter, googleads and redditads flows &#x60;platform&#x60; carries the ads platform id (&#x60;tiktokads&#x60;, &#x60;xads&#x60;, &#x60;googleads&#x60;, &#x60;redditads&#x60;), not the value used in the request path. When omitted, the browser lands on the Zernio dashboard.  | [optional] |
 | **headless** | **Boolean** | Enable headless mode (same-token platforms only) | [optional][default to false] |
 | **force** | **Boolean** | Force a fresh OAuth even when an account already exists. Normally the endpoint returns &#x60;alreadyConnected: true&#x60; whenever a connected account is found, keying off its active state rather than token liveness. Set &#x60;force&#x3D;true&#x60; to bypass that and always receivean &#x60;authUrl&#x60;. Completing the returned OAuth refreshes the stored token on the existing posting and ads accounts in place. An &#x60;alreadyConnected&#x60; response re-runs ad discovery and webhook subscriptions in the background at most once every 15 minutes per ads account (always when the call changes the ad-account scope), so it is not a sync trigger. To check the connection&#39;s health, read GET /v1/ads/accounts?accountId&#x3D;&lt;ads account ID&gt;.  | [optional][default to false] |
-| **ad_account_id** | **String** | Scope ad sync to a single platform ad account. Without this param, sync covers every ad account the connected token can see. Business-login reconnects preserve the existing scope; supplied IDs are checked against the new grant. To change that scope after migration, call this endpoint with the IDs and omit loginMode. Supported on &#x60;facebook&#x60;/&#x60;instagram&#x60; (Meta, &#x60;act_&lt;digits&gt;&#x60;), &#x60;linkedin&#x60; (bare numeric sponsored-account id), &#x60;googleads&#x60; (bare customer id digits) and &#x60;twitter&#x60; (X Ads, base36 account id). &#x60;tiktok&#x60; scopes advertisers at OAuth and &#x60;pinterest&#x60; has no ads discovery, so both ignore it. Meta ids are additionally validated against the connected token: an id the token cannot see returns 400 &#x60;invalid_field_value&#x60;, and an id it can see but that Meta marks unusable for ads (disabled, closed, under risk review, settlement pending) returns 400 &#x60;ad_account_unusable&#x60; with &#x60;details.accountStatus&#x60; (Meta&#39;s &#x60;account_status&#x60;) and, when Meta gives one, &#x60;details.disableReason&#x60;. Unsettled and in-grace accounts are accepted, matching the &#x60;selectable&#x60; flag of &#x60;GET /v1/ads/accounts&#x60;. Setting a scope also removes already synced ads, campaigns, ad sets and keywords from de-scoped ad accounts. On Meta the scope also decides which ad accounts Zernio subscribes to ad-account webhooks: only the scoped ones, instead of every ad account the login can reach. The scope is kept when this call returns an &#x60;authUrl&#x60;, so the Meta Ads account created after OAuth is scoped (and only its scoped ad accounts synced and subscribed) from the start. On &#x60;googleads&#x60; the scope is kept through OAuth when &#x60;redirect_url&#x60; is set, so the Google Ads connection created after OAuth syncs only its scoped customers from the first sync. For multiple accounts use &#x60;adAccountIds&#x60; instead.  | [optional] |
+| **ad_account_id** | **String** | Scope ad sync to a single platform ad account. Without this param, sync covers every ad account the connected token can see. Business-login reconnects preserve the existing scope; supplied IDs are checked against the new grant. To change that scope after migration, call this endpoint with the IDs and omit loginMode. Supported on &#x60;facebook&#x60;/&#x60;instagram&#x60; (Meta, &#x60;act_&lt;digits&gt;&#x60;), &#x60;linkedin&#x60; (bare numeric sponsored-account id), &#x60;googleads&#x60; (bare customer id digits), &#x60;redditads&#x60; (Reddit ad account id, &#x60;a2_&lt;id&gt;&#x60; or &#x60;t2_&lt;id&gt;&#x60;) and &#x60;twitter&#x60; (X Ads, base36 account id). &#x60;tiktok&#x60; scopes advertisers at OAuth and &#x60;pinterest&#x60; has no ads discovery, so both ignore it. Meta ids are additionally validated against the connected token: an id the token cannot see returns 400 &#x60;invalid_field_value&#x60;, and an id it can see but that Meta marks unusable for ads (disabled, closed, under risk review, settlement pending) returns 400 &#x60;ad_account_unusable&#x60; with &#x60;details.accountStatus&#x60; (Meta&#39;s &#x60;account_status&#x60;) and, when Meta gives one, &#x60;details.disableReason&#x60;. Unsettled and in-grace accounts are accepted, matching the &#x60;selectable&#x60; flag of &#x60;GET /v1/ads/accounts&#x60;. Setting a scope also removes already synced ads, campaigns, ad sets and keywords from de-scoped ad accounts. On Meta the scope also decides which ad accounts Zernio subscribes to ad-account webhooks: only the scoped ones, instead of every ad account the login can reach. The scope is kept when this call returns an &#x60;authUrl&#x60;, so the Meta Ads account created after OAuth is scoped (and only its scoped ad accounts synced and subscribed) from the start. On &#x60;googleads&#x60; and &#x60;redditads&#x60; the scope is kept through OAuth when &#x60;redirect_url&#x60; is set, so the connection created after OAuth syncs only its scoped ad accounts from the first sync. For multiple accounts use &#x60;adAccountIds&#x60; instead.  | [optional] |
 | **ad_account_ids** | [**Array&lt;String&gt;**](String.md) | Scope ad sync to multiple platform ad accounts (same platform support and id shapes as &#x60;adAccountId&#x60;). Repeat the param (&#x60;?adAccountIds&#x3D;act_1&amp;adAccountIds&#x3D;act_2&#x60;) or comma-separate (&#x60;?adAccountIds&#x3D;act_1,act_2&#x60;). Persisted server-side; latest call wins, and de-scoped ad accounts have their synced ads, campaigns, ad sets and keywords removed. On Meta only the scoped ad accounts get webhook subscriptions, including when the call starts a fresh OAuth. Omitting both &#x60;adAccountId&#x60; and &#x60;adAccountIds&#x60; keeps any previously persisted scope unchanged (no scope means every reachable ad account).  | [optional] |
 
 ### Return type
@@ -1303,7 +1303,7 @@ opts = {
   expected_platform_user_id: 'expected_platform_user_id_example', # String | Only connect if the login lands on this platform account; any other account ends the flow with `error=account_mismatch` (a 409 `account_mismatch` on POST /v1/connect/instagram/select-account) and nothing is written. Compared with every id the platform reports for the authorized account: the `platformUserId` of a Zernio account on this platform, or on Instagram either the app-scoped id or the professional account id (`metadata.instagramScopedId`, the `17841...` id that Facebook Login accounts hold as platformUserId). TikTok open_ids are app-scoped, so an id from your own TikTok app never matches; use expectedUsername there. Honoured by the OAuth callback (every platform that connects without a selection step, Instagram Login included) and by the Instagram selection step; on the other selection endpoints you choose the destination yourself. In headless mode the marker travels in the redirect_url we hand you, so pass that URL back unchanged. On X it counts toward the OAuth state limit described under redirect_url.
   expected_username: 'expected_username_example', # String | Only connect if the authorized account's handle is this one (case-insensitive, a leading @ is ignored); otherwise the flow ends with `error=account_mismatch`, `error_message` naming the handle that was authorized, and nothing is written. Same coverage and transport as expectedPlatformUserId; when both are sent both must match. Use this on a first connection, where you hold the handle the user typed but no Zernio id yet.
   force_reauth: true, # Boolean | Instagram Login only (the default loginMethod); ignored elsewhere. Makes Instagram show its login page and ask for the credentials of the account to connect even when another Instagram account is logged in on the device or in the app, and hides the Facebook login option on that page. Use it when the person connecting manages several Instagram accounts on one phone: Instagram otherwise logs in, and converts to a professional account, whichever account is active, before any consent screen. Pair it with expectedUsername to also refuse a wrong account at the end.
-  redirect_url: 'redirect_url_example', # String | Your custom redirect URL after connection completes. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. X (twitter) caps the OAuth `state` at 500 characters and the redirect is carried inside it, so the URL-encoded `redirect_url` must be at most 258 characters for API callers (310 for dashboard sessions; in headless mode the appended `headless=true` counts toward it); a longer one is rejected with 400 INVALID_REDIRECT_URL. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.  On failure, the browser is sent to the same redirect_url with `error` and `platform` appended. `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason`, `dashboard_url`, `missing_scopes`, `error_reason` and the `platform_error*` params are conditional and must be treated as optional. Your own query params are kept on every redirect, but ours overwrite a param of yours with the same name. On an error redirect the internal `headless`, `adsConnect`, `adsScope`, `reconnectAccountId`, `expectedPlatformUserId` and `expectedUsername` markers we add during the flow are removed.  Correlation (every redirect from an OAuth callback, success and failure, and the `redirect_url` returned by the selection endpoints such as POST /v1/connect/facebook/select-page):   - `request_id`: the id we log that request under. Quote it when reporting a problem.   - `stage`: where the flow ended. `authorize` = the platform's consent dialog returned an     error or denial instead of a code. `callback` = we processed the returned code (success,     a selection step, or a failure). `select_page` = the destination-selection endpoint     (page, account, organization, board, location, profile or phone number) completed it.  `oauth_denied` carries `error_message` and, when the platform sent them, its own values as `platform_error` (e.g. `access_denied`), `platform_error_reason` (e.g. `user_denied`) and `platform_error_description` (truncated to 500 characters). `is_user_fixable=true` is set when the platform reported that the user cancelled or declined.  `no_facebook_pages` comes with `is_user_fixable=true`, an `error_message` telling the user to click \"Edit previous settings\" in Meta's dialog and tick the Page (or create one), and, when Meta's token debug answered, `error_reason`:   - `pages_permission_declined`: the user declined the pages_show_list permission.   - `no_pages_granted`: the permission was granted with no Page ticked. Meta reports a user who     manages no Page the same way, so this covers both.   - `granted_pages_not_listed`: Pages were ticked but Meta listed none the user can manage, and a     direct read of each ticked Page returned no access token.  Headless Facebook success (`step=select_page`): `userProfile` is JSON that was percent-encoded once before being set as a query param, so it is encoded twice on the wire. After your framework decodes the query string once, run one more decodeURIComponent (or equivalent) and then JSON.parse it. `tempToken` and `connect_token` are plain values.  `code_already_redeemed` means the same authorization code arrived more than once and an earlier request already processed it (the code is never sent to the platform twice). It is not a failure: check GET /v1/accounts or wait for the `account.connected` webhook.  `missing_google_permissions` (YouTube, Google Business and Google Ads) means the user unchecked one or more permissions on Google's consent screen. It always comes with `is_user_fixable=true`. When Google reported the granted scopes, `missing_scopes` is also present: a comma-separated list of the requested Google scopes that were not granted. Ask the user to connect again and keep every permission checked.  `no_youtube_channel` means Google authorized the account but it has no YouTube channel we can connect. It always comes with `is_user_fixable=true` and an `error_message`. The usual causes: the user picked their personal Google identity instead of the Brand Account in Google's account chooser, they only have YouTube Studio access (not Brand Account owner or manager), or the account has no channel yet.  This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized value as a generic failure rather than matching it exhaustively. Existing values are not renamed or removed without notice.  OAuth and callback:   oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,   internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,   missing_google_permissions, missing_tiktok_permissions, platform_requires_destination,   reconnect_account_mismatch, account_mismatch, instagram_login_method_mismatch, invalid_request,   code_already_redeemed  Access and limits:   profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,   profile_limit_exceeded, payment_required  Destination selection:   no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,   google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,   no_youtube_channel, discord_no_guild, slack_no_team  WhatsApp:   whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,   whatsapp_number_pinned_to_profile, whatsapp_coexistence_not_registered, connection_cancelled  Google Ads (platform=googleads):   google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,   google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error  TikTok Ads (platform=tiktokads):   tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,   tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,   tiktok_ads_callback_error  X Ads (platform=xads):   x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,   x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error  Shopify (platform=shopify):   shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,   shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error  1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`, with the provider's own values in the `platform_error*` params described above. The dedicated ads flows below are different: they use their own denial slugs and `google_ads_auth_failed` and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.  2. On the tiktok and twitter ads flows `platform` carries the ads platform id (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify flows report `googleads` and `shopify`.  3. `missing_tiktok_permissions` means the TikTok authorization left out a permission the already-connected account needs, so nothing was changed and it keeps working as before. It is user-fixable: connect again and accept every permission on TikTok's screen.  4. `instagram_login_method_mismatch` means an Instagram Login authorization landed on a profile whose Instagram account is connected through Facebook Login, so nothing was changed and it keeps working as before. To refresh it, connect again with `loginMethod=facebook_login`. To move it to Instagram Login, disconnect it first. 
+  redirect_url: 'redirect_url_example', # String | Your custom redirect URL after connection completes. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. X (twitter) caps the OAuth `state` at 500 characters and the redirect is carried inside it, so the URL-encoded `redirect_url` must be at most 258 characters for API callers (310 for dashboard sessions; in headless mode the appended `headless=true` counts toward it); a longer one is rejected with 400 INVALID_REDIRECT_URL. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.  On failure, the browser is sent to the same redirect_url with `error` and `platform` appended. `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason`, `dashboard_url`, `missing_scopes`, `error_reason` and the `platform_error*` params are conditional and must be treated as optional. Your own query params are kept on every redirect, but ours overwrite a param of yours with the same name. On an error redirect the internal `headless`, `adsConnect`, `adsScope`, `reconnectAccountId`, `expectedPlatformUserId` and `expectedUsername` markers we add during the flow are removed.  Correlation (every redirect from an OAuth callback, success and failure, and the `redirect_url` returned by the selection endpoints such as POST /v1/connect/facebook/select-page):   - `request_id`: the id we log that request under. Quote it when reporting a problem.   - `stage`: where the flow ended. `authorize` = the platform's consent dialog returned an     error or denial instead of a code. `callback` = we processed the returned code (success,     a selection step, or a failure). `select_page` = the destination-selection endpoint     (page, account, organization, board, location, profile or phone number) completed it.  `oauth_denied` carries `error_message` and, when the platform sent them, its own values as `platform_error` (e.g. `access_denied`), `platform_error_reason` (e.g. `user_denied`) and `platform_error_description` (truncated to 500 characters). `is_user_fixable=true` is set when the platform reported that the user cancelled or declined.  `no_facebook_pages` comes with `is_user_fixable=true`, an `error_message` telling the user to click \"Edit previous settings\" in Meta's dialog and tick the Page (or create one), and, when Meta's token debug answered, `error_reason`:   - `pages_permission_declined`: the user declined the pages_show_list permission.   - `no_pages_granted`: the permission was granted with no Page ticked. Meta reports a user who     manages no Page the same way, so this covers both.   - `granted_pages_not_listed`: Pages were ticked but Meta listed none the user can manage, and a     direct read of each ticked Page returned no access token.  Headless Facebook success (`step=select_page`): `userProfile` is JSON that was percent-encoded once before being set as a query param, so it is encoded twice on the wire. After your framework decodes the query string once, run one more decodeURIComponent (or equivalent) and then JSON.parse it. `tempToken` and `connect_token` are plain values.  `code_already_redeemed` means the same authorization code arrived more than once and an earlier request already processed it (the code is never sent to the platform twice). It is not a failure: check GET /v1/accounts or wait for the `account.connected` webhook.  `missing_google_permissions` (YouTube, Google Business and Google Ads) means the user unchecked one or more permissions on Google's consent screen. It always comes with `is_user_fixable=true`. When Google reported the granted scopes, `missing_scopes` is also present: a comma-separated list of the requested Google scopes that were not granted. Ask the user to connect again and keep every permission checked.  `no_youtube_channel` means Google authorized the account but it has no YouTube channel we can connect. It always comes with `is_user_fixable=true` and an `error_message`. The usual causes: the user picked their personal Google identity instead of the Brand Account in Google's account chooser, they only have YouTube Studio access (not Brand Account owner or manager), or the account has no channel yet.  This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized value as a generic failure rather than matching it exhaustively. Existing values are not renamed or removed without notice.  OAuth and callback:   oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,   internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,   missing_google_permissions, missing_tiktok_permissions, platform_requires_destination,   reconnect_account_mismatch, account_mismatch, instagram_login_method_mismatch, invalid_request,   code_already_redeemed  Access and limits:   profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,   profile_limit_exceeded, payment_required  Destination selection:   no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,   google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,   no_youtube_channel, discord_no_guild, slack_no_team  WhatsApp:   whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,   whatsapp_number_pinned_to_profile, whatsapp_coexistence_not_registered, connection_cancelled  Google Ads (platform=googleads):   google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,   google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error  TikTok Ads (platform=tiktokads):   tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,   tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,   tiktok_ads_callback_error  X Ads (platform=xads):   x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,   x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error  Reddit Ads (platform=redditads):   reddit_ads_auth_failed, reddit_ads_invalid_state, reddit_ads_access_denied,   reddit_ads_scope_not_granted, reddit_ads_no_ad_accounts, reddit_ads_callback_error  Shopify (platform=shopify):   shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,   shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error  1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`, with the provider's own values in the `platform_error*` params described above. The dedicated ads flows below are different: they use their own denial slugs and `google_ads_auth_failed` and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.  2. On the tiktok and twitter ads flows `platform` carries the ads platform id (`tiktokads`, `xads`), not the value used in the request path. The googleads, redditads and shopify flows report `googleads`, `redditads` and `shopify`.  3. `missing_tiktok_permissions` means the TikTok authorization left out a permission the already-connected account needs, so nothing was changed and it keeps working as before. It is user-fixable: connect again and accept every permission on TikTok's screen.  4. `instagram_login_method_mismatch` means an Instagram Login authorization landed on a profile whose Instagram account is connected through Facebook Login, so nothing was changed and it keeps working as before. To refresh it, connect again with `loginMethod=facebook_login`. To move it to Instagram Login, disconnect it first. 
   scopes: 'posting,analytics', # String | Comma-separated permission areas to request instead of the platform's full permission set. Values: `posting`, `analytics`, `comments`, `messaging`, `ads`. Omit it (the default, and what the dashboard does) to request everything the platform supports.  When present, the consent dialog asks only for the platform scopes behind those areas plus the scopes every connection needs (identity, token refresh, and listing the pages, organizations or channels the user picks from). Scopes the user was never asked for are absent from the account's `permissions`, and the health endpoints report them as not granted, so a `posting`-only account cannot read analytics or the inbox until it is connected again with more areas. First comments need `comments`: a `posting`-only account publishes the post and skips the first comment. Scopes the platform lists under none of the areas (X likes, bookmarks and follows, Pinterest ads-only extras) are requested only when the parameter is omitted.  Supported on facebook, instagram (both login methods), linkedin, twitter, tiktok, youtube, threads, reddit, pinterest, googlebusiness and slack (via `GET /v1/connect/slack`). Rejected with 400 `INVALID_FIELD_VALUE` (`param: scopes`) on bluesky, telegram, discord, snapchat and whatsapp, whose dialog cannot be reduced, and for an empty list or an unknown area.  What each area asks for, per platform (Google scopes shortened to their last path segment):  | Platform | `posting` | `analytics` | `comments` | `messaging` | `ads` | Always requested | |---|---|---|---|---|---|---| | facebook | `pages_manage_posts` | `read_insights`, `pages_read_user_content` | `pages_manage_engagement`, `pages_read_user_content` | (in the always-requested set) | `ads_management`, `ads_read`, `leads_retrieval`, `pages_manage_ads`, `instagram_basic`, `business_management` | `pages_show_list`, `pages_read_engagement`, `pages_manage_metadata`, `pages_messaging` | | instagram (Instagram Login) | `instagram_business_content_publish` | `instagram_business_manage_insights` | `instagram_business_manage_comments` | `instagram_business_manage_messages` | none | `instagram_business_basic` | | instagram (`loginMethod=facebook_login`) | `instagram_content_publish` | `instagram_manage_insights` | `instagram_manage_comments` | `instagram_manage_messages` | `ads_management`, `ads_read`, `leads_retrieval`, `pages_manage_ads` | `instagram_basic`, `pages_show_list`, `pages_read_engagement`, `business_management`, `pages_messaging`, `pages_manage_metadata` | | linkedin | `w_member_social`, `w_organization_social`, `r_organization_social`, `r_organization_followers` | `r_member_postAnalytics`, `r_member_profileAnalytics`, `rw_organization_admin`, `r_organization_social`, `r_organization_followers` | `w_member_social`, `w_member_social_feed`, `w_organization_social`, `w_organization_social_feed`, `r_organization_social`, `r_organization_social_feed` | none | `r_ads`, `rw_ads`, `r_ads_reporting`, `r_marketing_leadgen_automation`, `rw_conversions` | `openid`, `profile`, `email`, `r_basicprofile`, `rw_organization_admin` | | twitter | `tweet.write`, `media.write` | (in the always-requested set) | `tweet.write`, `like.write`, `tweet.moderate.write` | `dm.read`, `dm.write`, `media.write` | none | `tweet.read`, `users.read`, `offline.access` | | tiktok | `video.publish` | `user.info.stats`, `user.insights`, `video.list`, `video.insights` | `comment.list`, `comment.list.manage`, `video.list` | `message.list.read`, `message.list.send`, `message.list.manage` | none | `user.info.basic`, `user.info.username`, `user.info.profile`, `user.account.type`, `video.publish`, `video.upload`, `video.list` | | youtube | `youtube.upload` | `yt-analytics.readonly` | `youtube.force-ssl` | none | none | `youtube` | | threads | `threads_content_publish`, `threads_manage_replies`, `threads_delete` | `threads_manage_insights` | `threads_content_publish`, `threads_read_replies`, `threads_manage_replies`, `threads_delete` | none | none | `threads_basic` | | reddit | `submit`, `read`, `mysubreddits`, `flair`, `history`, `edit` | `read`, `history` | `read`, `history`, `edit`, `vote` | `privatemessages` | none | `identity` | | pinterest | `boards:write`, `pins:read`, `pins:write` | `pins:read`, `user_accounts:read` | none | none | `ads:read`, `ads:write`, `boards:write`, `pins:read`, `pins:write` | `boards:read`, `user_accounts:read` | | googlebusiness | `business.manage` | `business.manage` | `business.manage` | none | none | `business.manage`, `userinfo.profile`, `userinfo.email` | | slack | `chat:write`, `chat:write.public`, `chat:write.customize`, `files:write`, `files:read` | none | none | `chat:write`, `chat:write.customize`, `files:write`, `files:read`, `channels:history`, `groups:history`, `im:history`, `mpim:history`, `im:read`, `im:write`, `mpim:read`, `users:read`, `reactions:read`, `reactions:write` | none | `channels:join`, `channels:read`, `groups:read`, `team:read` | 
   headless: true, # Boolean | When true, the user is redirected to your redirect_url with raw OAuth data (code, state) instead of Zernio's default account selection UI. Use this to build a custom connect experience.
   login_method: 'instagram_login', # String | Instagram only. Which of the two Instagram connection methods to use. Ignored for every other platform.  `instagram_login` (the default, and what you get if you omit this): the Instagram Login dialog. The user authorizes their Instagram professional account directly, no Facebook Page required.  `facebook_login`: the Facebook Login dialog, i.e. \"Instagram API with Facebook Login\". The user authorizes a Facebook Page that has a linked Instagram professional account, and every API call for that account then runs through the Page. Use this when the customer manages Instagram through a Page and expects the Facebook consent screen. Because the user has to pick which Page to connect, the callback continues at the account-selection step, `/v1/connect/instagram/select-account`.  `facebook_login` supports `headless=true` like the other selection platforms: the callback redirects to your `redirect_url` with `profileId`, `tempToken`, `platform=instagram`, `step=select_account` and `connect_token`, which you pass into the select-account endpoints to finish. The default `instagram_login` has no selection step, so it connects the account directly. 
@@ -1351,7 +1351,7 @@ end
 | **expected_platform_user_id** | **String** | Only connect if the login lands on this platform account; any other account ends the flow with &#x60;error&#x3D;account_mismatch&#x60; (a 409 &#x60;account_mismatch&#x60; on POST /v1/connect/instagram/select-account) and nothing is written. Compared with every id the platform reports for the authorized account: the &#x60;platformUserId&#x60; of a Zernio account on this platform, or on Instagram either the app-scoped id or the professional account id (&#x60;metadata.instagramScopedId&#x60;, the &#x60;17841...&#x60; id that Facebook Login accounts hold as platformUserId). TikTok open_ids are app-scoped, so an id from your own TikTok app never matches; use expectedUsername there. Honoured by the OAuth callback (every platform that connects without a selection step, Instagram Login included) and by the Instagram selection step; on the other selection endpoints you choose the destination yourself. In headless mode the marker travels in the redirect_url we hand you, so pass that URL back unchanged. On X it counts toward the OAuth state limit described under redirect_url. | [optional] |
 | **expected_username** | **String** | Only connect if the authorized account&#39;s handle is this one (case-insensitive, a leading @ is ignored); otherwise the flow ends with &#x60;error&#x3D;account_mismatch&#x60;, &#x60;error_message&#x60; naming the handle that was authorized, and nothing is written. Same coverage and transport as expectedPlatformUserId; when both are sent both must match. Use this on a first connection, where you hold the handle the user typed but no Zernio id yet. | [optional] |
 | **force_reauth** | **Boolean** | Instagram Login only (the default loginMethod); ignored elsewhere. Makes Instagram show its login page and ask for the credentials of the account to connect even when another Instagram account is logged in on the device or in the app, and hides the Facebook login option on that page. Use it when the person connecting manages several Instagram accounts on one phone: Instagram otherwise logs in, and converts to a professional account, whichever account is active, before any consent screen. Pair it with expectedUsername to also refuse a wrong account at the end. | [optional][default to false] |
-| **redirect_url** | **String** | Your custom redirect URL after connection completes. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. X (twitter) caps the OAuth &#x60;state&#x60; at 500 characters and the redirect is carried inside it, so the URL-encoded &#x60;redirect_url&#x60; must be at most 258 characters for API callers (310 for dashboard sessions; in headless mode the appended &#x60;headless&#x3D;true&#x60; counts toward it); a longer one is rejected with 400 INVALID_REDIRECT_URL. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected&#x3D;{platform}&amp;profileId&#x3D;X&amp;accountId&#x3D;Y&amp;username&#x3D;Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.  On failure, the browser is sent to the same redirect_url with &#x60;error&#x60; and &#x60;platform&#x60; appended. &#x60;error&#x60; and &#x60;platform&#x60; are always present. &#x60;error_message&#x60;, &#x60;is_user_fixable&#x60;, &#x60;reason&#x60;, &#x60;dashboard_url&#x60;, &#x60;missing_scopes&#x60;, &#x60;error_reason&#x60; and the &#x60;platform_error*&#x60; params are conditional and must be treated as optional. Your own query params are kept on every redirect, but ours overwrite a param of yours with the same name. On an error redirect the internal &#x60;headless&#x60;, &#x60;adsConnect&#x60;, &#x60;adsScope&#x60;, &#x60;reconnectAccountId&#x60;, &#x60;expectedPlatformUserId&#x60; and &#x60;expectedUsername&#x60; markers we add during the flow are removed.  Correlation (every redirect from an OAuth callback, success and failure, and the &#x60;redirect_url&#x60; returned by the selection endpoints such as POST /v1/connect/facebook/select-page):   - &#x60;request_id&#x60;: the id we log that request under. Quote it when reporting a problem.   - &#x60;stage&#x60;: where the flow ended. &#x60;authorize&#x60; &#x3D; the platform&#39;s consent dialog returned an     error or denial instead of a code. &#x60;callback&#x60; &#x3D; we processed the returned code (success,     a selection step, or a failure). &#x60;select_page&#x60; &#x3D; the destination-selection endpoint     (page, account, organization, board, location, profile or phone number) completed it.  &#x60;oauth_denied&#x60; carries &#x60;error_message&#x60; and, when the platform sent them, its own values as &#x60;platform_error&#x60; (e.g. &#x60;access_denied&#x60;), &#x60;platform_error_reason&#x60; (e.g. &#x60;user_denied&#x60;) and &#x60;platform_error_description&#x60; (truncated to 500 characters). &#x60;is_user_fixable&#x3D;true&#x60; is set when the platform reported that the user cancelled or declined.  &#x60;no_facebook_pages&#x60; comes with &#x60;is_user_fixable&#x3D;true&#x60;, an &#x60;error_message&#x60; telling the user to click \&quot;Edit previous settings\&quot; in Meta&#39;s dialog and tick the Page (or create one), and, when Meta&#39;s token debug answered, &#x60;error_reason&#x60;:   - &#x60;pages_permission_declined&#x60;: the user declined the pages_show_list permission.   - &#x60;no_pages_granted&#x60;: the permission was granted with no Page ticked. Meta reports a user who     manages no Page the same way, so this covers both.   - &#x60;granted_pages_not_listed&#x60;: Pages were ticked but Meta listed none the user can manage, and a     direct read of each ticked Page returned no access token.  Headless Facebook success (&#x60;step&#x3D;select_page&#x60;): &#x60;userProfile&#x60; is JSON that was percent-encoded once before being set as a query param, so it is encoded twice on the wire. After your framework decodes the query string once, run one more decodeURIComponent (or equivalent) and then JSON.parse it. &#x60;tempToken&#x60; and &#x60;connect_token&#x60; are plain values.  &#x60;code_already_redeemed&#x60; means the same authorization code arrived more than once and an earlier request already processed it (the code is never sent to the platform twice). It is not a failure: check GET /v1/accounts or wait for the &#x60;account.connected&#x60; webhook.  &#x60;missing_google_permissions&#x60; (YouTube, Google Business and Google Ads) means the user unchecked one or more permissions on Google&#39;s consent screen. It always comes with &#x60;is_user_fixable&#x3D;true&#x60;. When Google reported the granted scopes, &#x60;missing_scopes&#x60; is also present: a comma-separated list of the requested Google scopes that were not granted. Ask the user to connect again and keep every permission checked.  &#x60;no_youtube_channel&#x60; means Google authorized the account but it has no YouTube channel we can connect. It always comes with &#x60;is_user_fixable&#x3D;true&#x60; and an &#x60;error_message&#x60;. The usual causes: the user picked their personal Google identity instead of the Brand Account in Google&#39;s account chooser, they only have YouTube Studio access (not Brand Account owner or manager), or the account has no channel yet.  This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized value as a generic failure rather than matching it exhaustively. Existing values are not renamed or removed without notice.  OAuth and callback:   oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,   internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,   missing_google_permissions, missing_tiktok_permissions, platform_requires_destination,   reconnect_account_mismatch, account_mismatch, instagram_login_method_mismatch, invalid_request,   code_already_redeemed  Access and limits:   profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,   profile_limit_exceeded, payment_required  Destination selection:   no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,   google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,   no_youtube_channel, discord_no_guild, slack_no_team  WhatsApp:   whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,   whatsapp_number_pinned_to_profile, whatsapp_coexistence_not_registered, connection_cancelled  Google Ads (platform&#x3D;googleads):   google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,   google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error  TikTok Ads (platform&#x3D;tiktokads):   tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,   tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,   tiktok_ads_callback_error  X Ads (platform&#x3D;xads):   x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,   x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error  Shopify (platform&#x3D;shopify):   shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,   shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error  1. On this endpoint every upstream OAuth error is collapsed into &#x60;oauth_denied&#x60;, with the provider&#39;s own values in the &#x60;platform_error*&#x60; params described above. The dedicated ads flows below are different: they use their own denial slugs and &#x60;google_ads_auth_failed&#x60; and &#x60;tiktok_ads_auth_failed&#x60; may carry the provider&#39;s raw error string in &#x60;error_message&#x60;.  2. On the tiktok and twitter ads flows &#x60;platform&#x60; carries the ads platform id (&#x60;tiktokads&#x60;, &#x60;xads&#x60;), not the value used in the request path. The googleads and shopify flows report &#x60;googleads&#x60; and &#x60;shopify&#x60;.  3. &#x60;missing_tiktok_permissions&#x60; means the TikTok authorization left out a permission the already-connected account needs, so nothing was changed and it keeps working as before. It is user-fixable: connect again and accept every permission on TikTok&#39;s screen.  4. &#x60;instagram_login_method_mismatch&#x60; means an Instagram Login authorization landed on a profile whose Instagram account is connected through Facebook Login, so nothing was changed and it keeps working as before. To refresh it, connect again with &#x60;loginMethod&#x3D;facebook_login&#x60;. To move it to Instagram Login, disconnect it first.  | [optional] |
+| **redirect_url** | **String** | Your custom redirect URL after connection completes. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. X (twitter) caps the OAuth &#x60;state&#x60; at 500 characters and the redirect is carried inside it, so the URL-encoded &#x60;redirect_url&#x60; must be at most 258 characters for API callers (310 for dashboard sessions; in headless mode the appended &#x60;headless&#x3D;true&#x60; counts toward it); a longer one is rejected with 400 INVALID_REDIRECT_URL. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected&#x3D;{platform}&amp;profileId&#x3D;X&amp;accountId&#x3D;Y&amp;username&#x3D;Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.  On failure, the browser is sent to the same redirect_url with &#x60;error&#x60; and &#x60;platform&#x60; appended. &#x60;error&#x60; and &#x60;platform&#x60; are always present. &#x60;error_message&#x60;, &#x60;is_user_fixable&#x60;, &#x60;reason&#x60;, &#x60;dashboard_url&#x60;, &#x60;missing_scopes&#x60;, &#x60;error_reason&#x60; and the &#x60;platform_error*&#x60; params are conditional and must be treated as optional. Your own query params are kept on every redirect, but ours overwrite a param of yours with the same name. On an error redirect the internal &#x60;headless&#x60;, &#x60;adsConnect&#x60;, &#x60;adsScope&#x60;, &#x60;reconnectAccountId&#x60;, &#x60;expectedPlatformUserId&#x60; and &#x60;expectedUsername&#x60; markers we add during the flow are removed.  Correlation (every redirect from an OAuth callback, success and failure, and the &#x60;redirect_url&#x60; returned by the selection endpoints such as POST /v1/connect/facebook/select-page):   - &#x60;request_id&#x60;: the id we log that request under. Quote it when reporting a problem.   - &#x60;stage&#x60;: where the flow ended. &#x60;authorize&#x60; &#x3D; the platform&#39;s consent dialog returned an     error or denial instead of a code. &#x60;callback&#x60; &#x3D; we processed the returned code (success,     a selection step, or a failure). &#x60;select_page&#x60; &#x3D; the destination-selection endpoint     (page, account, organization, board, location, profile or phone number) completed it.  &#x60;oauth_denied&#x60; carries &#x60;error_message&#x60; and, when the platform sent them, its own values as &#x60;platform_error&#x60; (e.g. &#x60;access_denied&#x60;), &#x60;platform_error_reason&#x60; (e.g. &#x60;user_denied&#x60;) and &#x60;platform_error_description&#x60; (truncated to 500 characters). &#x60;is_user_fixable&#x3D;true&#x60; is set when the platform reported that the user cancelled or declined.  &#x60;no_facebook_pages&#x60; comes with &#x60;is_user_fixable&#x3D;true&#x60;, an &#x60;error_message&#x60; telling the user to click \&quot;Edit previous settings\&quot; in Meta&#39;s dialog and tick the Page (or create one), and, when Meta&#39;s token debug answered, &#x60;error_reason&#x60;:   - &#x60;pages_permission_declined&#x60;: the user declined the pages_show_list permission.   - &#x60;no_pages_granted&#x60;: the permission was granted with no Page ticked. Meta reports a user who     manages no Page the same way, so this covers both.   - &#x60;granted_pages_not_listed&#x60;: Pages were ticked but Meta listed none the user can manage, and a     direct read of each ticked Page returned no access token.  Headless Facebook success (&#x60;step&#x3D;select_page&#x60;): &#x60;userProfile&#x60; is JSON that was percent-encoded once before being set as a query param, so it is encoded twice on the wire. After your framework decodes the query string once, run one more decodeURIComponent (or equivalent) and then JSON.parse it. &#x60;tempToken&#x60; and &#x60;connect_token&#x60; are plain values.  &#x60;code_already_redeemed&#x60; means the same authorization code arrived more than once and an earlier request already processed it (the code is never sent to the platform twice). It is not a failure: check GET /v1/accounts or wait for the &#x60;account.connected&#x60; webhook.  &#x60;missing_google_permissions&#x60; (YouTube, Google Business and Google Ads) means the user unchecked one or more permissions on Google&#39;s consent screen. It always comes with &#x60;is_user_fixable&#x3D;true&#x60;. When Google reported the granted scopes, &#x60;missing_scopes&#x60; is also present: a comma-separated list of the requested Google scopes that were not granted. Ask the user to connect again and keep every permission checked.  &#x60;no_youtube_channel&#x60; means Google authorized the account but it has no YouTube channel we can connect. It always comes with &#x60;is_user_fixable&#x3D;true&#x60; and an &#x60;error_message&#x60;. The usual causes: the user picked their personal Google identity instead of the Brand Account in Google&#39;s account chooser, they only have YouTube Studio access (not Brand Account owner or manager), or the account has no channel yet.  This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized value as a generic failure rather than matching it exhaustively. Existing values are not renamed or removed without notice.  OAuth and callback:   oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,   internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,   missing_google_permissions, missing_tiktok_permissions, platform_requires_destination,   reconnect_account_mismatch, account_mismatch, instagram_login_method_mismatch, invalid_request,   code_already_redeemed  Access and limits:   profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,   profile_limit_exceeded, payment_required  Destination selection:   no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,   google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,   no_youtube_channel, discord_no_guild, slack_no_team  WhatsApp:   whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,   whatsapp_number_pinned_to_profile, whatsapp_coexistence_not_registered, connection_cancelled  Google Ads (platform&#x3D;googleads):   google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,   google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error  TikTok Ads (platform&#x3D;tiktokads):   tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,   tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,   tiktok_ads_callback_error  X Ads (platform&#x3D;xads):   x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,   x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error  Reddit Ads (platform&#x3D;redditads):   reddit_ads_auth_failed, reddit_ads_invalid_state, reddit_ads_access_denied,   reddit_ads_scope_not_granted, reddit_ads_no_ad_accounts, reddit_ads_callback_error  Shopify (platform&#x3D;shopify):   shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,   shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error  1. On this endpoint every upstream OAuth error is collapsed into &#x60;oauth_denied&#x60;, with the provider&#39;s own values in the &#x60;platform_error*&#x60; params described above. The dedicated ads flows below are different: they use their own denial slugs and &#x60;google_ads_auth_failed&#x60; and &#x60;tiktok_ads_auth_failed&#x60; may carry the provider&#39;s raw error string in &#x60;error_message&#x60;.  2. On the tiktok and twitter ads flows &#x60;platform&#x60; carries the ads platform id (&#x60;tiktokads&#x60;, &#x60;xads&#x60;), not the value used in the request path. The googleads, redditads and shopify flows report &#x60;googleads&#x60;, &#x60;redditads&#x60; and &#x60;shopify&#x60;.  3. &#x60;missing_tiktok_permissions&#x60; means the TikTok authorization left out a permission the already-connected account needs, so nothing was changed and it keeps working as before. It is user-fixable: connect again and accept every permission on TikTok&#39;s screen.  4. &#x60;instagram_login_method_mismatch&#x60; means an Instagram Login authorization landed on a profile whose Instagram account is connected through Facebook Login, so nothing was changed and it keeps working as before. To refresh it, connect again with &#x60;loginMethod&#x3D;facebook_login&#x60;. To move it to Instagram Login, disconnect it first.  | [optional] |
 | **scopes** | **String** | Comma-separated permission areas to request instead of the platform&#39;s full permission set. Values: &#x60;posting&#x60;, &#x60;analytics&#x60;, &#x60;comments&#x60;, &#x60;messaging&#x60;, &#x60;ads&#x60;. Omit it (the default, and what the dashboard does) to request everything the platform supports.  When present, the consent dialog asks only for the platform scopes behind those areas plus the scopes every connection needs (identity, token refresh, and listing the pages, organizations or channels the user picks from). Scopes the user was never asked for are absent from the account&#39;s &#x60;permissions&#x60;, and the health endpoints report them as not granted, so a &#x60;posting&#x60;-only account cannot read analytics or the inbox until it is connected again with more areas. First comments need &#x60;comments&#x60;: a &#x60;posting&#x60;-only account publishes the post and skips the first comment. Scopes the platform lists under none of the areas (X likes, bookmarks and follows, Pinterest ads-only extras) are requested only when the parameter is omitted.  Supported on facebook, instagram (both login methods), linkedin, twitter, tiktok, youtube, threads, reddit, pinterest, googlebusiness and slack (via &#x60;GET /v1/connect/slack&#x60;). Rejected with 400 &#x60;INVALID_FIELD_VALUE&#x60; (&#x60;param: scopes&#x60;) on bluesky, telegram, discord, snapchat and whatsapp, whose dialog cannot be reduced, and for an empty list or an unknown area.  What each area asks for, per platform (Google scopes shortened to their last path segment):  | Platform | &#x60;posting&#x60; | &#x60;analytics&#x60; | &#x60;comments&#x60; | &#x60;messaging&#x60; | &#x60;ads&#x60; | Always requested | |---|---|---|---|---|---|---| | facebook | &#x60;pages_manage_posts&#x60; | &#x60;read_insights&#x60;, &#x60;pages_read_user_content&#x60; | &#x60;pages_manage_engagement&#x60;, &#x60;pages_read_user_content&#x60; | (in the always-requested set) | &#x60;ads_management&#x60;, &#x60;ads_read&#x60;, &#x60;leads_retrieval&#x60;, &#x60;pages_manage_ads&#x60;, &#x60;instagram_basic&#x60;, &#x60;business_management&#x60; | &#x60;pages_show_list&#x60;, &#x60;pages_read_engagement&#x60;, &#x60;pages_manage_metadata&#x60;, &#x60;pages_messaging&#x60; | | instagram (Instagram Login) | &#x60;instagram_business_content_publish&#x60; | &#x60;instagram_business_manage_insights&#x60; | &#x60;instagram_business_manage_comments&#x60; | &#x60;instagram_business_manage_messages&#x60; | none | &#x60;instagram_business_basic&#x60; | | instagram (&#x60;loginMethod&#x3D;facebook_login&#x60;) | &#x60;instagram_content_publish&#x60; | &#x60;instagram_manage_insights&#x60; | &#x60;instagram_manage_comments&#x60; | &#x60;instagram_manage_messages&#x60; | &#x60;ads_management&#x60;, &#x60;ads_read&#x60;, &#x60;leads_retrieval&#x60;, &#x60;pages_manage_ads&#x60; | &#x60;instagram_basic&#x60;, &#x60;pages_show_list&#x60;, &#x60;pages_read_engagement&#x60;, &#x60;business_management&#x60;, &#x60;pages_messaging&#x60;, &#x60;pages_manage_metadata&#x60; | | linkedin | &#x60;w_member_social&#x60;, &#x60;w_organization_social&#x60;, &#x60;r_organization_social&#x60;, &#x60;r_organization_followers&#x60; | &#x60;r_member_postAnalytics&#x60;, &#x60;r_member_profileAnalytics&#x60;, &#x60;rw_organization_admin&#x60;, &#x60;r_organization_social&#x60;, &#x60;r_organization_followers&#x60; | &#x60;w_member_social&#x60;, &#x60;w_member_social_feed&#x60;, &#x60;w_organization_social&#x60;, &#x60;w_organization_social_feed&#x60;, &#x60;r_organization_social&#x60;, &#x60;r_organization_social_feed&#x60; | none | &#x60;r_ads&#x60;, &#x60;rw_ads&#x60;, &#x60;r_ads_reporting&#x60;, &#x60;r_marketing_leadgen_automation&#x60;, &#x60;rw_conversions&#x60; | &#x60;openid&#x60;, &#x60;profile&#x60;, &#x60;email&#x60;, &#x60;r_basicprofile&#x60;, &#x60;rw_organization_admin&#x60; | | twitter | &#x60;tweet.write&#x60;, &#x60;media.write&#x60; | (in the always-requested set) | &#x60;tweet.write&#x60;, &#x60;like.write&#x60;, &#x60;tweet.moderate.write&#x60; | &#x60;dm.read&#x60;, &#x60;dm.write&#x60;, &#x60;media.write&#x60; | none | &#x60;tweet.read&#x60;, &#x60;users.read&#x60;, &#x60;offline.access&#x60; | | tiktok | &#x60;video.publish&#x60; | &#x60;user.info.stats&#x60;, &#x60;user.insights&#x60;, &#x60;video.list&#x60;, &#x60;video.insights&#x60; | &#x60;comment.list&#x60;, &#x60;comment.list.manage&#x60;, &#x60;video.list&#x60; | &#x60;message.list.read&#x60;, &#x60;message.list.send&#x60;, &#x60;message.list.manage&#x60; | none | &#x60;user.info.basic&#x60;, &#x60;user.info.username&#x60;, &#x60;user.info.profile&#x60;, &#x60;user.account.type&#x60;, &#x60;video.publish&#x60;, &#x60;video.upload&#x60;, &#x60;video.list&#x60; | | youtube | &#x60;youtube.upload&#x60; | &#x60;yt-analytics.readonly&#x60; | &#x60;youtube.force-ssl&#x60; | none | none | &#x60;youtube&#x60; | | threads | &#x60;threads_content_publish&#x60;, &#x60;threads_manage_replies&#x60;, &#x60;threads_delete&#x60; | &#x60;threads_manage_insights&#x60; | &#x60;threads_content_publish&#x60;, &#x60;threads_read_replies&#x60;, &#x60;threads_manage_replies&#x60;, &#x60;threads_delete&#x60; | none | none | &#x60;threads_basic&#x60; | | reddit | &#x60;submit&#x60;, &#x60;read&#x60;, &#x60;mysubreddits&#x60;, &#x60;flair&#x60;, &#x60;history&#x60;, &#x60;edit&#x60; | &#x60;read&#x60;, &#x60;history&#x60; | &#x60;read&#x60;, &#x60;history&#x60;, &#x60;edit&#x60;, &#x60;vote&#x60; | &#x60;privatemessages&#x60; | none | &#x60;identity&#x60; | | pinterest | &#x60;boards:write&#x60;, &#x60;pins:read&#x60;, &#x60;pins:write&#x60; | &#x60;pins:read&#x60;, &#x60;user_accounts:read&#x60; | none | none | &#x60;ads:read&#x60;, &#x60;ads:write&#x60;, &#x60;boards:write&#x60;, &#x60;pins:read&#x60;, &#x60;pins:write&#x60; | &#x60;boards:read&#x60;, &#x60;user_accounts:read&#x60; | | googlebusiness | &#x60;business.manage&#x60; | &#x60;business.manage&#x60; | &#x60;business.manage&#x60; | none | none | &#x60;business.manage&#x60;, &#x60;userinfo.profile&#x60;, &#x60;userinfo.email&#x60; | | slack | &#x60;chat:write&#x60;, &#x60;chat:write.public&#x60;, &#x60;chat:write.customize&#x60;, &#x60;files:write&#x60;, &#x60;files:read&#x60; | none | none | &#x60;chat:write&#x60;, &#x60;chat:write.customize&#x60;, &#x60;files:write&#x60;, &#x60;files:read&#x60;, &#x60;channels:history&#x60;, &#x60;groups:history&#x60;, &#x60;im:history&#x60;, &#x60;mpim:history&#x60;, &#x60;im:read&#x60;, &#x60;im:write&#x60;, &#x60;mpim:read&#x60;, &#x60;users:read&#x60;, &#x60;reactions:read&#x60;, &#x60;reactions:write&#x60; | none | &#x60;channels:join&#x60;, &#x60;channels:read&#x60;, &#x60;groups:read&#x60;, &#x60;team:read&#x60; |  | [optional] |
 | **headless** | **Boolean** | When true, the user is redirected to your redirect_url with raw OAuth data (code, state) instead of Zernio&#39;s default account selection UI. Use this to build a custom connect experience. | [optional][default to false] |
 | **login_method** | **String** | Instagram only. Which of the two Instagram connection methods to use. Ignored for every other platform.  &#x60;instagram_login&#x60; (the default, and what you get if you omit this): the Instagram Login dialog. The user authorizes their Instagram professional account directly, no Facebook Page required.  &#x60;facebook_login&#x60;: the Facebook Login dialog, i.e. \&quot;Instagram API with Facebook Login\&quot;. The user authorizes a Facebook Page that has a linked Instagram professional account, and every API call for that account then runs through the Page. Use this when the customer manages Instagram through a Page and expects the Facebook consent screen. Because the user has to pick which Page to connect, the callback continues at the account-selection step, &#x60;/v1/connect/instagram/select-account&#x60;.  &#x60;facebook_login&#x60; supports &#x60;headless&#x3D;true&#x60; like the other selection platforms: the callback redirects to your &#x60;redirect_url&#x60; with &#x60;profileId&#x60;, &#x60;tempToken&#x60;, &#x60;platform&#x3D;instagram&#x60;, &#x60;step&#x3D;select_account&#x60; and &#x60;connect_token&#x60;, which you pass into the select-account endpoints to finish. The default &#x60;instagram_login&#x60; has no selection step, so it connects the account directly.  | [optional][default to &#39;instagram_login&#39;] |

data/docs/ConversionEvent.md

@@ -4,9 +4,9 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
-| **event_name** | **String** | Standard event name (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, AddPaymentInfo, Subscribe, StartTrial, ViewContent, Search, Contact, SubmitApplication, Schedule) or a custom string (only supported on platforms that accept custom events: Meta and OpenAI Ads).  Per-platform behavior: - Meta: free-form; standard names match Meta's built-ins. - Google: ignored. The conversion action's category determines the type. - LinkedIn: ignored. The conversion rule's `type` is locked to the destination. - OpenAI Ads: a fixed subset of standard names (Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial, Schedule) maps 1:1 onto OpenAI's own event-type enum; anything else is sent as a custom event with the name preserved.  |  |
+| **event_name** | **String** | Standard event name (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, AddPaymentInfo, Subscribe, StartTrial, ViewContent, Search, Contact, SubmitApplication, Schedule) or a custom string (only supported on platforms that accept custom events: Meta, OpenAI Ads and Reddit).  Per-platform behavior: - Meta: free-form; standard names match Meta's built-ins. - Google: ignored. The conversion action's category determines the type. - LinkedIn: ignored. The conversion rule's `type` is locked to the destination. - OpenAI Ads: a fixed subset of standard names (Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial, Schedule) maps 1:1 onto OpenAI's own event-type enum; anything else is sent as a custom event with the name preserved. - Reddit: Purchase, Lead, CompleteRegistration (SIGN_UP), AddToCart, AddToWishlist, ViewContent, Search and PageView (PAGE_VISIT) map onto Reddit's tracking types; anything else is sent as a CUSTOM event with the name preserved.  |  |
 | **event_time** | **Integer** | When the conversion happened, in unix seconds. |  |
-| **event_id** | **String** | Unique dedup key. The same eventId must be used on pixel + CAPI to prevent double-counting. Mapped to event_id on Meta, transactionId on Google, eventId on LinkedIn (LinkedIn deduplicates against Insight Tag events with the same eventId; the Insight Tag event wins when both arrive).  |  |
+| **event_id** | **String** | Unique dedup key. The same eventId must be used on pixel + CAPI to prevent double-counting. Mapped to event_id on Meta, transactionId on Google, eventId on LinkedIn (LinkedIn deduplicates against Insight Tag events with the same eventId; the Insight Tag event wins when both arrive), and `metadata.conversion_id` on Reddit (Reddit's dedup key against Reddit Pixel events).  |  |
 | **value** | **Float** | Conversion value in the specified currency. | [optional] |
 | **currency** | **String** | ISO 4217 currency code. | [optional] |
 | **user** | [**ConversionEventUser**](ConversionEventUser.md) |  |  |

data/docs/ConversionEventUserClickIds.md

@@ -11,6 +11,8 @@
 | **wbraid** | **String** | Google iOS 14.5+ web-to-app attribution ID. | [optional] |
 | **li_fat_id** | **String** | LinkedIn first-party ad tracking click ID. Captured by parsing `li_fat_id` from landing-page URLs after the advertiser enables enhanced conversion tracking on the LinkedIn Insight Tag. Sent to LinkedIn as the LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID userId. Opaque token, not hashed.  | [optional] |
 | **epik** | **String** | Pinterest click ID (the `epik` URL param or `_epik` cookie). Sent to Pinterest as `click_id`, not hashed. | [optional] |
+| **rdt_cid** | **String** | Reddit click ID (the `rdt_cid` URL param Reddit adds to ad clicks). Sent to Reddit as `click_id`, not hashed. | [optional] |
+| **rdt_uuid** | **String** | Reddit Pixel browser id (the `_rdt_uuid` first-party cookie). Sent to Reddit as `user.uuid`, not hashed. | [optional] |
 
 ## Example
 
@@ -24,7 +26,9 @@ instance = Zernio::ConversionEventUserClickIds.new(
   gbraid: null,
   wbraid: null,
   li_fat_id: null,
-  epik: null
+  epik: null,
+  rdt_cid: null,
+  rdt_uuid: null
 )
 ```
 

data/docs/ConversionsApi.md

@@ -244,7 +244,7 @@ end
 
 Create a conversion destination
 
-Creates a new place to send conversion events: a Google Ads conversion action or a LinkedIn conversion rule.  Supported for LinkedIn (conversion rule) and Google Ads (conversion action). Meta and OpenAI Ads pixels are created via their own tracking-tags flow instead (`POST /v1/accounts/{accountId}/tracking-tags`); this endpoint returns 405 for both.  **LinkedIn:** creation is NOT idempotent. A retry creates a second destination. Deduplicate before retrying.  **Google Ads:** calling with a name that already exists reuses the existing conversion action transparently (the response is identical to a fresh create). Calling with the same name but a different category returns a typed `IDEMPOTENCY_CONFLICT` (409) rather than silently returning the mismatched action.  **LinkedIn:** the rule is created with `conversionMethod=CONVERSIONS_API` and (by default) auto-associated with all of the ad account's campaigns via `autoAssociationType=ALL_CAMPAIGNS`. Pass `autoAssociationType: NONE` to opt out and manage associations explicitly via the associations endpoints below.  365-day attribution windows are only valid for `SUBMIT_APPLICATION`, `PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, and `LEAD` rule types; the API rejects other combinations locally.  **Google Ads:** the conversion action is created with `type=UPLOAD_CLICKS` (required for API-uploaded offline conversions, immutable after creation). The `type` field carries the Google `ConversionActionCategory` enum value, e.g. `PURCHASE`, `SUBSCRIBE_PAID`, `SIGNUP`, `IMPORTED_LEAD`, `BOOK_APPOINTMENT`. Unified standard event names (e.g. `Purchase`, `Subscribe`, `CompleteRegistration`, `Lead`, `Schedule`) are resolved to their Google category equivalents automatically. The action defaults to secondary (non-primary) to avoid immediately steering Smart Bidding; pass `primaryForGoal: true` to opt in. 
+Creates a new place to send conversion events: a Google Ads conversion action or a LinkedIn conversion rule.  Supported for LinkedIn (conversion rule) and Google Ads (conversion action). Meta and OpenAI Ads pixels are created via their own tracking-tags flow instead (`POST /v1/accounts/{accountId}/tracking-tags`); this endpoint returns 405 for both, and for Reddit (create Reddit pixels in Reddit Ads Manager).  **LinkedIn:** creation is NOT idempotent. A retry creates a second destination. Deduplicate before retrying.  **Google Ads:** calling with a name that already exists reuses the existing conversion action transparently (the response is identical to a fresh create). Calling with the same name but a different category returns a typed `IDEMPOTENCY_CONFLICT` (409) rather than silently returning the mismatched action.  **LinkedIn:** the rule is created with `conversionMethod=CONVERSIONS_API` and (by default) auto-associated with all of the ad account's campaigns via `autoAssociationType=ALL_CAMPAIGNS`. Pass `autoAssociationType: NONE` to opt out and manage associations explicitly via the associations endpoints below.  365-day attribution windows are only valid for `SUBMIT_APPLICATION`, `PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, and `LEAD` rule types; the API rejects other combinations locally.  **Google Ads:** the conversion action is created with `type=UPLOAD_CLICKS` (required for API-uploaded offline conversions, immutable after creation). The `type` field carries the Google `ConversionActionCategory` enum value, e.g. `PURCHASE`, `SUBSCRIBE_PAID`, `SIGNUP`, `IMPORTED_LEAD`, `BOOK_APPOINTMENT`. Unified standard event names (e.g. `Purchase`, `Subscribe`, `CompleteRegistration`, `Lead`, `Schedule`) are resolved to their Google category equivalents automatically. The action defaults to secondary (non-primary) to avoid immediately steering Smart Bidding; pass `primaryForGoal: true` to opt in. 
 
 ### Examples
 
@@ -908,7 +908,7 @@ end
 
 List conversion destinations
 
-Lists where an ad account can receive conversion events (pixels, conversion actions or rules), so you know where to send them.  Returns the list of pixels (Meta), conversion actions (Google), conversion rules (LinkedIn), pixels (OpenAI Ads) or ad accounts (Pinterest) accessible to the connected ads account. Use the returned `id` as `destinationId` when posting to `POST /v1/ads/conversions`.  For Google and LinkedIn, each destination's `type` reflects the conversion type (PURCHASE, LEAD, SIGN_UP, etc.), and the event type is locked to the destination. For Meta and OpenAI Ads, `type` is absent: pixels accept any event name per request.  For LinkedIn, destinations are returned across every sponsored ad account the connected token can access; the `adAccountId` field on each destination identifies the parent ad account and is required for subsequent CRUD calls (update, delete, associations, metrics). 
+Lists where an ad account can receive conversion events (pixels, conversion actions or rules), so you know where to send them.  Returns the list of pixels (Meta), conversion actions (Google), conversion rules (LinkedIn), pixels (OpenAI Ads, Reddit) or ad accounts (Pinterest) accessible to the connected ads account. Use the returned `id` as `destinationId` when posting to `POST /v1/ads/conversions`.  For Google and LinkedIn, each destination's `type` reflects the conversion type (PURCHASE, LEAD, SIGN_UP, etc.), and the event type is locked to the destination. For Meta, OpenAI Ads and Reddit, `type` is absent: pixels accept any event name per request.  For Reddit, the pixels of every ad account the connection reaches (only the scoped ones when the connection has an ad-account scope), each with the `adAccountId` that owns it. Reddit pixels are created in Reddit Ads Manager, not through Zernio.  For LinkedIn, destinations are returned across every sponsored ad account the connected token can access; the `adAccountId` field on each destination identifies the parent ad account and is required for subsequent CRUD calls (update, delete, associations, metrics). 
 
 ### Examples
 
@@ -922,7 +922,7 @@ Zernio.configure do |config|
 end
 
 api_instance = Zernio::ConversionsApi.new
-account_id = 'account_id_example' # String | SocialAccount ID (metaads, googleads, linkedinads, tiktokads, openaiads, or pinterestads).
+account_id = 'account_id_example' # String | SocialAccount ID (metaads, googleads, linkedinads, tiktokads, openaiads, pinterestads, or redditads).
 
 begin
   # List conversion destinations
@@ -955,7 +955,7 @@ end
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
-| **account_id** | **String** | SocialAccount ID (metaads, googleads, linkedinads, tiktokads, openaiads, or pinterestads). |  |
+| **account_id** | **String** | SocialAccount ID (metaads, googleads, linkedinads, tiktokads, openaiads, pinterestads, or redditads). |  |
 
 ### Return type
 
@@ -1204,7 +1204,7 @@ end
 
 Send conversion events
 
-Sends conversion events, such as purchases or leads, from your server to an ad platform so it can attribute and optimize ads.  Relay one or more conversion events to the target ad platform's native Conversions API. Platform is inferred from the provided `accountId`. Requires the Ads add-on.  Supported platforms:  - Meta (`metaads`) via Graph API - Google Ads (`googleads`) via Data Manager API `ingestEvents` - LinkedIn (`linkedinads`) via `/rest/conversionEvents` - TikTok (`tiktokads`) via the Offline Events API `/offline/batch/` (OFFLINE conversions only) - OpenAI Ads (`openaiads`) via its Conversions API (a separate host, `bzr.openai.com`) - Pinterest (`pinterestads`) via `POST /v5/ad_accounts/{id}/events`  `destinationId` semantics differ per platform:  - Meta: pixel (dataset) ID, e.g. `123456789012345` - Google: conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321` - LinkedIn: conversion rule ID or URN, e.g. `104012` or `urn:lla:llaPartnerConversion:104012` - TikTok: Offline Event Set ID, e.g. `7057103914977558530` - OpenAI Ads: pixel wire id (numeric `pixel_id`, distinct from the internal pixel id), as returned by `GET /v1/accounts/{accountId}/conversion-destinations` - Pinterest: numeric ad account id, e.g. `549755885175` (Pinterest attributes to the ad account, not to a tag)  Pinterest notes: each event needs an `email`, or `ipAddress` plus `userAgent`; others are listed in `failures` with code `INVALID_EVENT` and the rest are still sent. `clickIds.epik` (the `_epik` cookie) is sent as `click_id`. `actionSource` `web` stays `web`, offline sources become `offline`, and app events need `platformData.action_source` `app_android` or `app_ios`. Pinterest answers per event, so one bad event does not fail its chunk (failures carry code `PINTEREST_EVENT_FAILED`). `consent.adUserData: DENIED` sets `opt_out`. The connected user needs a Business Access role on the ad account (403 otherwise).  TikTok notes: this path sends OFFLINE conversions (in-store / CRM / call-center), not web-pixel events. Each event must carry an email or phone (TikTok requires at least one). The connected TikTok ads account must have granted the Offline Events permission; older grants must reconnect.  OpenAI Ads notes: requires a tracking tag (pixel) to already exist on the account. Returns 422 with code `TRACKING_TAG_REQUIRED` if `POST /v1/accounts/{accountId}/tracking-tags` hasn't been called yet.  Callers can list valid destinations via `GET /v1/accounts/{accountId}/conversion-destinations`.  All PII (email, phone, names, external IDs) is hashed with SHA-256 server-side per each platform's normalization spec, including Google's Gmail-specific dot/plus-suffix stripping. Send plaintext. LinkedIn `externalIds` are passed through as plaintext per LinkedIn's spec; only emails and phones are hashed.  For LinkedIn, the connected account must have been authorized after the Conversions API rollout (i.e. the OAuth grant must include `rw_conversions`). Older accounts must reconnect.  Batching is handled automatically. Meta caps at 1000 events per request and rejects the entire batch if any event is malformed. Google caps at 2000. LinkedIn caps at 5000 and is also all-or-nothing per chunk. OpenAI Ads caps at 1000 per request; larger submissions are split into 1000-event chunks, each all-or-nothing (a malformed event fails every event in that chunk, not the whole request).  Dedup: pass a stable `eventId` on every event. Meta and LinkedIn use it to dedupe against browser-side pixel/Insight Tag events; Google maps it to `transactionId`.  Per-platform `eventName` semantics:  - Meta: free-form. Standard names (Purchase, Lead, ...) match Meta's built-in events; custom strings are accepted. - Google: ignored. The conversion action's category determines the event type. Send the standard name closest to your action for documentation, but the platform will not branch on it. - LinkedIn: ignored. The conversion rule's `type` (LEAD, PURCHASE, etc.) is locked to the destination at rule-creation time. Send the standard name for documentation; LinkedIn does not branch on it. - OpenAI Ads: a fixed subset of standard names (Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial, Schedule) maps 1:1 onto OpenAI's own event-type enum; any other standard name or custom string is sent as `type: custom` with the name preserved. - Pinterest: standard names map onto Pinterest's (Purchase = `checkout`, AddToCart = `add_to_cart`, InitiateCheckout = `initiate_checkout`, AddPaymentInfo = `add_payment_info`, Lead = `lead`, CompleteRegistration = `signup`, Subscribe = `subscribe`, ViewContent = `view_content`, Search = `search`, PageView = `page_visit`); any other string is sent as is, so it matches an advertiser defined event of that name. 
+Sends conversion events, such as purchases or leads, from your server to an ad platform so it can attribute and optimize ads.  Relay one or more conversion events to the target ad platform's native Conversions API. Platform is inferred from the provided `accountId`. Requires the Ads add-on.  Supported platforms:  - Meta (`metaads`) via Graph API - Google Ads (`googleads`) via Data Manager API `ingestEvents` - LinkedIn (`linkedinads`) via `/rest/conversionEvents` - TikTok (`tiktokads`) via the Offline Events API `/offline/batch/` (OFFLINE conversions only) - OpenAI Ads (`openaiads`) via its Conversions API (a separate host, `bzr.openai.com`) - Pinterest (`pinterestads`) via `POST /v5/ad_accounts/{id}/events` - Reddit (`redditads`) via the Reddit Conversions API (`POST /api/v3/pixels/{pixelId}/conversion_events`)  `destinationId` semantics differ per platform:  - Meta: pixel (dataset) ID, e.g. `123456789012345` - Google: conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321` - LinkedIn: conversion rule ID or URN, e.g. `104012` or `urn:lla:llaPartnerConversion:104012` - TikTok: Offline Event Set ID, e.g. `7057103914977558530` - OpenAI Ads: pixel wire id (numeric `pixel_id`, distinct from the internal pixel id), as returned by `GET /v1/accounts/{accountId}/conversion-destinations` - Pinterest: numeric ad account id, e.g. `549755885175` (Pinterest attributes to the ad account, not to a tag) - Reddit: pixel id, e.g. `a2_abc123`, as returned by `GET /v1/accounts/{accountId}/conversion-destinations` (any other shape returns 400)  Pinterest notes: each event needs an `email`, or `ipAddress` plus `userAgent`; others are listed in `failures` with code `INVALID_EVENT` and the rest are still sent. `clickIds.epik` (the `_epik` cookie) is sent as `click_id`. `actionSource` `web` stays `web`, offline sources become `offline`, and app events need `platformData.action_source` `app_android` or `app_ios`. Pinterest answers per event, so one bad event does not fail its chunk (failures carry code `PINTEREST_EVENT_FAILED`). `consent.adUserData: DENIED` sets `opt_out`. The connected user needs a Business Access role on the ad account (403 otherwise).  Reddit notes: each event needs a match key: `clickIds.rdt_cid`, `clickIds.rdt_uuid`, `email`, `phone`, `externalId`, or `ipAddress` plus `userAgent`. Reddit accepts events up to 7 days old, and `eventTime` is unix SECONDS (a value more than an hour in the future is refused as milliseconds). Events failing these checks are listed in `failures` with code `INVALID_EVENT` and the rest are still sent. Email (lowercased, dots and `+tags` stripped from the local part), phone (E.164 with the leading `+`) and `externalId` are SHA-256 hashed; IP and user agent go plaintext. `consent.adUserData: DENIED` sends no user fields. `actionSource` maps to WEBSITE (`web`), APP (`app`) or OTHER, overridable with `platformData.action_source`; `platformData.order_id` is forwarded. `testCode` is sent as Reddit's `test_id`. The connection must hold the `adsconversions` permission: one authorized without it returns 403 `reconnect_required` (reconnect via GET /v1/connect/redditads/ads), and a Reddit user with no role on the ad account that owns the pixel returns 403 `insufficient_permissions`. Reddit throttling and other rejections are reported per chunk in `failures` with code `REDDIT_REJECTED`.  TikTok notes: this path sends OFFLINE conversions (in-store / CRM / call-center), not web-pixel events. Each event must carry an email or phone (TikTok requires at least one). The connected TikTok ads account must have granted the Offline Events permission; older grants must reconnect.  OpenAI Ads notes: requires a tracking tag (pixel) to already exist on the account. Returns 422 with code `TRACKING_TAG_REQUIRED` if `POST /v1/accounts/{accountId}/tracking-tags` hasn't been called yet.  Callers can list valid destinations via `GET /v1/accounts/{accountId}/conversion-destinations`.  All PII (email, phone, names, external IDs) is hashed with SHA-256 server-side per each platform's normalization spec, including Google's Gmail-specific dot/plus-suffix stripping. Send plaintext. LinkedIn `externalIds` are passed through as plaintext per LinkedIn's spec; only emails and phones are hashed.  For LinkedIn, the connected account must have been authorized after the Conversions API rollout (i.e. the OAuth grant must include `rw_conversions`). Older accounts must reconnect.  Batching is handled automatically. Meta caps at 1000 events per request and rejects the entire batch if any event is malformed. Google caps at 2000. LinkedIn caps at 5000 and is also all-or-nothing per chunk. OpenAI Ads caps at 1000 per request; larger submissions are split into 1000-event chunks, each all-or-nothing (a malformed event fails every event in that chunk, not the whole request). Reddit works the same way, in chunks of 1000.  Dedup: pass a stable `eventId` on every event. Meta and LinkedIn use it to dedupe against browser-side pixel/Insight Tag events; Google maps it to `transactionId`; Reddit receives it as `conversion_id`, its dedup key against Reddit Pixel events.  Per-platform `eventName` semantics:  - Meta: free-form. Standard names (Purchase, Lead, ...) match Meta's built-in events; custom strings are accepted. - Google: ignored. The conversion action's category determines the event type. Send the standard name closest to your action for documentation, but the platform will not branch on it. - LinkedIn: ignored. The conversion rule's `type` (LEAD, PURCHASE, etc.) is locked to the destination at rule-creation time. Send the standard name for documentation; LinkedIn does not branch on it. - OpenAI Ads: a fixed subset of standard names (Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial, Schedule) maps 1:1 onto OpenAI's own event-type enum; any other standard name or custom string is sent as `type: custom` with the name preserved. - Pinterest: standard names map onto Pinterest's (Purchase = `checkout`, AddToCart = `add_to_cart`, InitiateCheckout = `initiate_checkout`, AddPaymentInfo = `add_payment_info`, Lead = `lead`, CompleteRegistration = `signup`, Subscribe = `subscribe`, ViewContent = `view_content`, Search = `search`, PageView = `page_visit`); any other string is sent as is, so it matches an advertiser defined event of that name. 
 
 ### Examples
 

data/docs/CreateAdCampaignRequest.md

@@ -16,6 +16,8 @@
 | **budget_amount** | **Float** | 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. | [optional] |
 | **budget_type** | **String** |  | [optional] |
 | **status** | **String** |  | [optional][default to 'PAUSED'] |
+| **start_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. | [optional] |
+| **end_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`. | [optional] |
 | **location_targeting_type** | [**GoogleLocationTargetingType**](GoogleLocationTargetingType.md) | Google only (400 elsewhere). Written on the new campaign. | [optional] |
 | **bid_strategy** | **String** | Campaign bid strategy. Meta stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request; sending it without a campaign budget is a 400. A campaign carrying a strategy without its `bid_amount` makes every ad set created under it fail with an error that names the ad set (code 100, subcode 1815857), so the bad state is rejected up front rather than accepted. To bid at ad-set level on Meta, set the strategy there instead. On Google: LOWEST_COST_WITHOUT_CAP = Maximize Conversions, COST_CAP + bidAmount = Target CPA, LOWEST_COST_WITH_MIN_ROAS + roasAverageFloor = Target ROAS, LOWEST_COST_WITH_BID_CAP + bidAmount = Maximize Clicks with a CPC ceiling; portfolioBidStrategyId attaches a portfolio strategy instead. | [optional] |
 | **bid_amount** | **Float** | Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. On Meta, validated here but NOT stored: the campaign object has no bid_amount field, only bid_strategy lives on it, and the amount takes effect once an ad set joins this campaign (existingCampaignId on POST /v1/ads/create) and supplies its own bidAmount there. On Google, stored directly on the campaign's bidding strategy. | [optional] |
@@ -43,6 +45,8 @@ instance = Zernio::CreateAdCampaignRequest.new(
   budget_amount: null,
   budget_type: null,
   status: null,
+  start_date: null,
+  end_date: null,
   location_targeting_type: null,
   bid_strategy: null,
   bid_amount: null,