late-sdk 0.0.723 → 0.0.725

data/lib/zernio-sdk/models/replace_ad_audience_companies_request_companies_inner.rb

@@ -0,0 +1,231 @@
+=begin
+#Zernio API
+
+#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api 
+
+The version of the OpenAPI document: 1.0.4
+Contact: support@zernio.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.19.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Zernio
+  class ReplaceAdAudienceCompaniesRequestCompaniesInner < ApiModelBase
+    attr_accessor :name
+
+    attr_accessor :domain
+
+    attr_accessor :website
+
+    attr_accessor :linkedin_page_url
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'name' => :'name',
+        :'domain' => :'domain',
+        :'website' => :'website',
+        :'linkedin_page_url' => :'linkedinPageUrl'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'name' => :'String',
+        :'domain' => :'String',
+        :'website' => :'String',
+        :'linkedin_page_url' => :'String'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Zernio::ReplaceAdAudienceCompaniesRequestCompaniesInner` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Zernio::ReplaceAdAudienceCompaniesRequestCompaniesInner`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'name')
+        self.name = attributes[:'name']
+      end
+
+      if attributes.key?(:'domain')
+        self.domain = attributes[:'domain']
+      end
+
+      if attributes.key?(:'website')
+        self.website = attributes[:'website']
+      end
+
+      if attributes.key?(:'linkedin_page_url')
+        self.linkedin_page_url = attributes[:'linkedin_page_url']
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      if !@name.nil? && @name.to_s.length > 255
+        invalid_properties.push('invalid value for "name", the character length must be smaller than or equal to 255.')
+      end
+
+      if !@domain.nil? && @domain.to_s.length > 100
+        invalid_properties.push('invalid value for "domain", the character length must be smaller than or equal to 100.')
+      end
+
+      if !@website.nil? && @website.to_s.length > 100
+        invalid_properties.push('invalid value for "website", the character length must be smaller than or equal to 100.')
+      end
+
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      return false if !@name.nil? && @name.to_s.length > 255
+      return false if !@domain.nil? && @domain.to_s.length > 100
+      return false if !@website.nil? && @website.to_s.length > 100
+      true
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] name Value to be assigned
+    def name=(name)
+      if name.nil?
+        fail ArgumentError, 'name cannot be nil'
+      end
+
+      if name.to_s.length > 255
+        fail ArgumentError, 'invalid value for "name", the character length must be smaller than or equal to 255.'
+      end
+
+      @name = name
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] domain Value to be assigned
+    def domain=(domain)
+      if domain.nil?
+        fail ArgumentError, 'domain cannot be nil'
+      end
+
+      if domain.to_s.length > 100
+        fail ArgumentError, 'invalid value for "domain", the character length must be smaller than or equal to 100.'
+      end
+
+      @domain = domain
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] website Value to be assigned
+    def website=(website)
+      if website.nil?
+        fail ArgumentError, 'website cannot be nil'
+      end
+
+      if website.to_s.length > 100
+        fail ArgumentError, 'invalid value for "website", the character length must be smaller than or equal to 100.'
+      end
+
+      @website = website
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          name == o.name &&
+          domain == o.domain &&
+          website == o.website &&
+          linkedin_page_url == o.linkedin_page_url
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [name, domain, website, linkedin_page_url].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/zernio-sdk/models/uploaded_or_derived_audience.rb

@@ -42,7 +42,7 @@ module Zernio
     # Required for engagement audiences. Campaign URNs for the ad source types, organization URNs for pages and events. LinkedIn creates one rule per source, all sharing the same trigger and lookbackDays. 
     attr_accessor :engagement_sources
 
-    # Required for company_list audiences (LinkedIn only): plain-text company rows for account targeting. Each row needs at least one identifier. LinkedIn recommends 1,000+ companies for a usable match rate and takes up to 48h to process the list. 
+    # Required for company_list audiences (LinkedIn only): plain-text company rows for account targeting. Each row needs at least one identifier. Not hashed, LinkedIn matches these against its own company graph. LinkedIn recommends 1,000+ companies for a usable match rate and takes up to 48h to process the list. Replace the list later with POST /v1/ads/audiences/{audienceId}/companies. 
     attr_accessor :companies
 
     # Required for website audiences
@@ -69,7 +69,10 @@ module Zernio
     # Required for lookalike audiences
     attr_accessor :ratio
 
-    # Optional raw Meta rule, forwarded verbatim: pixel event rule for website audiences, or the engagement rule for meta_engagement (overrides the built rule, e.g. for event/canvas/lead-form sources).
+    # website only. Narrows the audience from all visitors to visitors of URLs containing this substring. Ignored when `rule` is supplied. 
+    attr_accessor :url_contains
+
+    # Optional raw Meta rule, replacing the one we build. Omit it for all visitors of `pixelId`, or use `urlContains` for the common page-match case.  For `website` this is Meta's Flexible Audience Rule and is VALIDATED before we call Meta: every entry in `inclusions.rules` (and `exclusions.rules`) must carry `event_sources`, `retention_seconds` AND `filter`. Meta rejects a rule missing any of the three with code 100 / subcode 1713098 (\"Invalid rule JSON format\"), so a bad shape is a 400 here instead. The pre-2018 flat shapes (`{url: ...}`, `{event: ...}`) are not accepted by Meta at all (subcode 1870029).  Example, visitors of /checkout in the last 30 days: `{\"inclusions\":{\"operator\":\"or\",\"rules\":[{\"event_sources\":[{\"id\":\"<pixelId>\",\"type\":\"pixel\"}],\"retention_seconds\":2592000,\"filter\":{\"operator\":\"and\",\"filters\":[{\"field\":\"url\",\"operator\":\"i_contains\",\"value\":\"/checkout\"}]}}]}}`  Note Meta DERIVES `retention_days` from `retention_seconds` and stores `event_sources[].id` as a number, so a rule read back will not be byte-identical to the one you sent.  For `meta_engagement` the rule is forwarded verbatim and NOT validated: that type has two dialects (the `video` source uses a legacy flat array), so no single schema covers both. 
     attr_accessor :rule
 
     # Data source declaration for GDPR compliance (customer_list only)
@@ -119,6 +122,7 @@ module Zernio
         :'source_audience_id' => :'sourceAudienceId',
         :'country' => :'country',
         :'ratio' => :'ratio',
+        :'url_contains' => :'urlContains',
         :'rule' => :'rule',
         :'customer_file_source' => :'customerFileSource'
       }
@@ -156,6 +160,7 @@ module Zernio
         :'source_audience_id' => :'String',
         :'country' => :'String',
         :'ratio' => :'Float',
+        :'url_contains' => :'String',
         :'rule' => :'Object',
         :'customer_file_source' => :'String'
       }
@@ -273,6 +278,10 @@ module Zernio
         self.ratio = attributes[:'ratio']
       end
 
+      if attributes.key?(:'url_contains')
+        self.url_contains = attributes[:'url_contains']
+      end
+
       if attributes.key?(:'rule')
         self.rule = attributes[:'rule']
       end
@@ -568,6 +577,7 @@ module Zernio
           source_audience_id == o.source_audience_id &&
           country == o.country &&
           ratio == o.ratio &&
+          url_contains == o.url_contains &&
           rule == o.rule &&
           customer_file_source == o.customer_file_source
     end
@@ -581,7 +591,7 @@ module Zernio
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [account_id, ad_account_id, name, description, type, match_rules, source_type, trigger, lookback_days, engagement_sources, companies, pixel_id, retention_days, engagement_source, source_id, event, source_audience_id, country, ratio, rule, customer_file_source].hash
+      [account_id, ad_account_id, name, description, type, match_rules, source_type, trigger, lookback_days, engagement_sources, companies, pixel_id, retention_days, engagement_source, source_id, event, source_audience_id, country, ratio, url_contains, rule, customer_file_source].hash
     end
 
     # Builds the object from hash

data/lib/zernio-sdk/version.rb

@@ -11,5 +11,5 @@ Generator version: 7.19.0
 =end
 
 module Zernio
-  VERSION = '0.0.723'
+  VERSION = '0.0.725'
 end

data/lib/zernio-sdk.rb

@@ -878,6 +878,7 @@ require 'zernio-sdk/models/list_ad_keywords200_response'
 require 'zernio-sdk/models/list_ad_keywords200_response_keywords_inner'
 require 'zernio-sdk/models/list_ad_labels200_response'
 require 'zernio-sdk/models/list_ad_studies200_response'
+require 'zernio-sdk/models/list_ad_videos200_response'
 require 'zernio-sdk/models/list_ads202_response'
 require 'zernio-sdk/models/list_ads_business_centers200_response'
 require 'zernio-sdk/models/list_api_keys200_response'
@@ -1135,6 +1136,9 @@ require 'zernio-sdk/models/remove_bookmark200_response'
 require 'zernio-sdk/models/remove_conversion_associations200_response'
 require 'zernio-sdk/models/remove_discord_member_role200_response'
 require 'zernio-sdk/models/remove_whats_app_group_participants_request'
+require 'zernio-sdk/models/replace_ad_audience_companies200_response'
+require 'zernio-sdk/models/replace_ad_audience_companies_request'
+require 'zernio-sdk/models/replace_ad_audience_companies_request_companies_inner'
 require 'zernio-sdk/models/reply_to_google_business_review200_response'
 require 'zernio-sdk/models/reply_to_google_business_review_request'
 require 'zernio-sdk/models/reply_to_inbox_post200_response'

data/openapi.yaml

@@ -42006,7 +42006,7 @@ paths:
                     square: { type: string, format: uri, description: "Square 1:1 marketing image URL (e.g. 1080x1080). Required for Google Display." }
                 video:
                   type: object
-                  description: "Meta (facebook, instagram) and LinkedIn. When set, creates a VIDEO ad on the legacy (or, for Meta, attach) shape. Mutually exclusive with `imageUrl`. For Meta multi-creative, set `video` per entry inside `creatives[]` instead. For LinkedIn the video is uploaded to LinkedIn under the authoring Company Page (see `organizationId`) and the campaign format is set to SINGLE_VIDEO; LinkedIn ignores `thumbnailUrl` (it auto-generates the poster frame) — supply MP4 H.264/AAC, 3s-30min, 75KB-500MB."
+                  description: "Meta (facebook, instagram) and LinkedIn. Creates a single VIDEO ad. Mutually exclusive with `imageUrl`. Supply `url` to upload a file, or `id` to reuse a video already on the ad account (list them with GET /v1/ads/videos). Works on the single-ad and attach (`adSetId`) shapes; for Meta multi-creative, set `video` per entry inside `creatives[]` instead. For LinkedIn the video is uploaded to LinkedIn under the authoring Company Page (see `organizationId`) and the campaign format is set to SINGLE_VIDEO; LinkedIn ignores `thumbnailUrl` (it auto-generates the poster frame) — supply MP4 H.264/AAC, 3s-30min, 75KB-500MB."
                   properties:
                     url: { type: string, format: uri, description: "Public URL of the video. Meta: uploaded via chunked transfer on /act_X/advideos, then the request blocks on Meta's transcoding until status.video_status === 'ready'. LinkedIn: uploaded via the Videos API (multipart), then the request blocks until LinkedIn finishes transcoding (status AVAILABLE) — short clips take ~10-30s. Provide either `url` or `id`."}
                     id: { type: string, description: "Meta only. Reuse a video ALREADY uploaded to this ad account instead of re-uploading the file: pass the `videoId` returned by a previous create. Wins over `url`, so N ads that differ only in copy share one upload (`existingCreativeId` only covers the identical-copy case). Provide either `url` or `id`."}
@@ -43279,6 +43279,53 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '501': { description: Only supported on Meta (facebook/instagram) }
 
+  /v1/ads/videos:
+    get:
+      x-resource-group: "ads"
+      operationId: listAdVideos
+      tags: ["Ad Creatives"]
+      x-platforms: ["meta"]
+      summary: Ad video library
+      description: |-
+        Lists the ad account's video library (Meta's `/act_X/advideos`), rows returned verbatim.
+        The default projection covers id, title, status, poster frames and length; `fields` is a
+        raw-passthrough override. Any `id` here is reusable as `video.id` on the create
+        endpoints, so N ads that differ only in copy share one upload.
+
+        This is the only way to reach a video uploaded OUTSIDE Zernio (Ads Manager, another
+        tool); videos we uploaded also come back as `creative.videoId` on GET /v1/ads.
+
+        Meta transcodes asynchronously, so a row is only usable once `status.video_status`
+        reads `ready`. There is no upload operation here: upload by URL inline via `video.url`
+        on POST /v1/ads/create.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
+        - { name: adAccountId, in: query, required: true, schema: { type: string }, description: "Meta ad account id (act_<n>)." }
+        - { name: fields, in: query, schema: { type: string }, description: "Comma-separated Graph field override (supports nested {} projections)." }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
+        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
+      responses:
+        '200':
+          description: Ad videos (raw Meta shape)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  adAccountId: { type: string }
+                  data:
+                    type: array
+                    items: { type: object, description: "Raw Meta ad video row (id, title, status, picture, thumbnails, length)." }
+                  paging:
+                    type: object
+                    properties:
+                      after: { type: [string, "null"], description: "Cursor for the next page; null when exhausted." }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { description: Only supported on Meta (facebook/instagram) }
+
   /v1/ads/interests:
     get:
       x-resource-group: "ads"
@@ -43737,11 +43784,21 @@ paths:
       summary: Create custom audience
       description: |
         Create a custom audience. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest;
-        `website` and `lookalike` are Meta-only. `saved_targeting` stores a reusable TargetingSpec (no member upload,
-        no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`. Upload-backed audiences
-        are created empty, add members via `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the
-        audience is provisioned lazily on the first member upload (until then its status is `pending`). Create is not
-        idempotent, never auto-retry.
+        `website` and `lookalike` are Meta-only; `company_list`, `engagement` and `website_retargeting` are LinkedIn-only.
+        `saved_targeting` stores a reusable TargetingSpec (no member upload, no adAccountId) that you reference later via
+        `savedTargetingId` on `POST /v1/ads/create`.
+
+        How the audience gets filled depends on the type:
+
+        - `customer_list` is created empty. Add members with `POST /v1/ads/audiences/{audienceId}/users`.
+          On TikTok and Pinterest the audience is provisioned lazily on that first upload (until then its status is `pending`).
+        - `company_list` is filled AT CREATION from the `companies` array below, which is required. To change the list
+          afterwards send the new full list to `POST /v1/ads/audiences/{audienceId}/companies` (a replace, not a merge).
+          The `/users` endpoint rejects these audiences with a 422.
+        - `website`, `website_retargeting`, `engagement`, `meta_engagement` and `lookalike` fill themselves from the pixel,
+          engagement source or seed audience you point them at. They take no member upload at all.
+
+        Create is not idempotent, never auto-retry.
       security:
         - bearerAuth: []
       requestBody:
@@ -43819,8 +43876,10 @@ paths:
                       description: |
                         Required for company_list audiences (LinkedIn only): plain-text
                         company rows for account targeting. Each row needs at least one
-                        identifier. LinkedIn recommends 1,000+ companies for a usable
-                        match rate and takes up to 48h to process the list.
+                        identifier. Not hashed, LinkedIn matches these against its own
+                        company graph. LinkedIn recommends 1,000+ companies for a usable
+                        match rate and takes up to 48h to process the list. Replace the
+                        list later with POST /v1/ads/audiences/{audienceId}/companies.
                       items:
                         type: object
                         additionalProperties: false
@@ -43850,7 +43909,36 @@ paths:
                     sourceAudienceId: { type: string, description: Required for lookalike audiences }
                     country: { type: string, description: "2-letter code, required for lookalike audiences" }
                     ratio: { type: number, minimum: 0.01, maximum: 0.20, description: Required for lookalike audiences }
-                    rule: { type: object, description: "Optional raw Meta rule, forwarded verbatim: pixel event rule for website audiences, or the engagement rule for meta_engagement (overrides the built rule, e.g. for event/canvas/lead-form sources)." }
+                    urlContains:
+                      type: string
+                      description: |
+                        website only. Narrows the audience from all visitors to visitors of
+                        URLs containing this substring. Ignored when `rule` is supplied.
+                    rule:
+                      type: object
+                      description: |
+                        Optional raw Meta rule, replacing the one we build. Omit it for all
+                        visitors of `pixelId`, or use `urlContains` for the common page-match
+                        case.
+
+                        For `website` this is Meta's Flexible Audience Rule and is VALIDATED
+                        before we call Meta: every entry in `inclusions.rules` (and
+                        `exclusions.rules`) must carry `event_sources`, `retention_seconds`
+                        AND `filter`. Meta rejects a rule missing any of the three with code
+                        100 / subcode 1713098 ("Invalid rule JSON format"), so a bad shape is
+                        a 400 here instead. The pre-2018 flat shapes (`{url: ...}`,
+                        `{event: ...}`) are not accepted by Meta at all (subcode 1870029).
+
+                        Example, visitors of /checkout in the last 30 days:
+                        `{"inclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<pixelId>","type":"pixel"}],"retention_seconds":2592000,"filter":{"operator":"and","filters":[{"field":"url","operator":"i_contains","value":"/checkout"}]}}]}}`
+
+                        Note Meta DERIVES `retention_days` from `retention_seconds` and
+                        stores `event_sources[].id` as a number, so a rule read back will
+                        not be byte-identical to the one you sent.
+
+                        For `meta_engagement` the rule is forwarded verbatim and NOT
+                        validated: that type has two dialects (the `video` source uses a
+                        legacy flat array), so no single schema covers both.
                     customerFileSource: { type: string, description: "Data source declaration for GDPR compliance (customer_list only)" }
                 - type: object
                   title: SavedTargetingAudience
@@ -43993,6 +44081,9 @@ paths:
         Upload user data to a customer_list audience. Data is SHA256-hashed server-side before sending to the platform.
         Email is used on every platform; phone is used on Meta only (other platforms ignore it). On TikTok and Pinterest,
         the first upload also provisions the audience (deferred create). LinkedIn uploads are full-replace. Max 10,000 users per request.
+
+        customer_list only. A LinkedIn `company_list` audience takes company rows, not people: send those to
+        `POST /v1/ads/audiences/{audienceId}/companies`. This endpoint 422s for every other audience type.
       security:
         - bearerAuth: []
       parameters:
@@ -44034,6 +44125,73 @@ paths:
         '422':
           description: Audience is not a customer_list type or has no platform ID yet
 
+  /v1/ads/audiences/{audienceId}/companies:
+    post:
+      x-resource-group: "ads"
+      operationId: replaceAdAudienceCompanies
+      tags: ["Ad Audiences"]
+      x-platforms: ["linkedin"]
+      summary: Replace audience companies
+      description: |
+        Upload the company rows of a LinkedIn `company_list` audience (account-based marketing).
+        LinkedIn-only, every other platform returns 422.
+
+        A LinkedIn audience segment holds exactly one uploaded list, so the list you send here REPLACES the
+        segment's list instead of being appended to it: always send the full set of companies. LinkedIn returns
+        only the identifier of the uploaded file, never its rows, so the merge cannot be done for you, keep the
+        source list on your side. LinkedIn does not document how quickly companies dropped from the list stop
+        being targeted, so treat removals as eventual rather than immediate.
+        Rows are plain text (not hashed), matched against LinkedIn's own company graph. Matching is asynchronous:
+        LinkedIn takes up to 48h for a new audience and up to 24h for a later update, and the audience stays
+        `processing` meanwhile. LinkedIn recommends at least 1,000 companies for a usable match rate, and caps a
+        list at 300,000.
+
+        The initial list is sent with `companies` on `POST /v1/ads/audiences`; this endpoint is for every
+        change after that.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: audienceId, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [companies]
+              properties:
+                companies:
+                  type: array
+                  minItems: 1
+                  maxItems: 300000
+                  description: 'The complete company list. Each row needs at least one of name, domain, website or linkedinPageUrl.'
+                  items:
+                    type: object
+                    additionalProperties: false
+                    properties:
+                      name: { type: string, maxLength: 255 }
+                      domain: { type: string, maxLength: 100 }
+                      website: { type: string, maxLength: 100 }
+                      linkedinPageUrl: { type: string }
+      responses:
+        '200':
+          description: Companies uploaded
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message: { type: string }
+                  numReceived: { type: integer, description: 'Rows sent to LinkedIn. Matching happens asynchronously, so this is not the matched company count.' }
+        '400':
+          description: 'Invalid input (malformed audienceId, empty companies array, a row with no identifier)'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
+        '404': { $ref: '#/components/responses/NotFound' }
+        '422':
+          description: 'Audience is not a company_list type, is not on LinkedIn, or has no platform ID yet'
+
   /v1/ads/conversions/quality:
     get:
       x-resource-group: "ads"

data/spec/api/ad_audiences_api_spec.rb

@@ -34,7 +34,7 @@ describe 'AdAudiencesApi' do
 
   # unit tests for add_users_to_ad_audience
   # Add users to audience
-  # Upload user data to a customer_list audience. Data is SHA256-hashed server-side before sending to the platform. Email is used on every platform; phone is used on Meta only (other platforms ignore it). On TikTok and Pinterest, the first upload also provisions the audience (deferred create). LinkedIn uploads are full-replace. Max 10,000 users per request. 
+  # Upload user data to a customer_list audience. Data is SHA256-hashed server-side before sending to the platform. Email is used on every platform; phone is used on Meta only (other platforms ignore it). On TikTok and Pinterest, the first upload also provisions the audience (deferred create). LinkedIn uploads are full-replace. Max 10,000 users per request.  customer_list only. A LinkedIn `company_list` audience takes company rows, not people: send those to `POST /v1/ads/audiences/{audienceId}/companies`. This endpoint 422s for every other audience type. 
   # @param audience_id 
   # @param add_users_to_ad_audience_request 
   # @param [Hash] opts the optional parameters
@@ -47,7 +47,7 @@ describe 'AdAudiencesApi' do
 
   # unit tests for create_ad_audience
   # Create custom audience
-  # Create a custom audience. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest; `website` and `lookalike` are Meta-only. `saved_targeting` stores a reusable TargetingSpec (no member upload, no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`. Upload-backed audiences are created empty, add members via `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the audience is provisioned lazily on the first member upload (until then its status is `pending`). Create is not idempotent, never auto-retry. 
+  # Create a custom audience. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest; `website` and `lookalike` are Meta-only; `company_list`, `engagement` and `website_retargeting` are LinkedIn-only. `saved_targeting` stores a reusable TargetingSpec (no member upload, no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`.  How the audience gets filled depends on the type:  - `customer_list` is created empty. Add members with `POST /v1/ads/audiences/{audienceId}/users`.   On TikTok and Pinterest the audience is provisioned lazily on that first upload (until then its status is `pending`). - `company_list` is filled AT CREATION from the `companies` array below, which is required. To change the list   afterwards send the new full list to `POST /v1/ads/audiences/{audienceId}/companies` (a replace, not a merge).   The `/users` endpoint rejects these audiences with a 422. - `website`, `website_retargeting`, `engagement`, `meta_engagement` and `lookalike` fill themselves from the pixel,   engagement source or seed audience you point them at. They take no member upload at all.  Create is not idempotent, never auto-retry. 
   # @param create_ad_audience_request 
   # @param [Hash] opts the optional parameters
   # @return [CreateAdAudience201Response]
@@ -96,6 +96,19 @@ describe 'AdAudiencesApi' do
     end
   end
 
+  # unit tests for replace_ad_audience_companies
+  # Replace audience companies
+  # Upload the company rows of a LinkedIn `company_list` audience (account-based marketing). LinkedIn-only, every other platform returns 422.  A LinkedIn audience segment holds exactly one uploaded list, so the list you send here REPLACES the segment's list instead of being appended to it: always send the full set of companies. LinkedIn returns only the identifier of the uploaded file, never its rows, so the merge cannot be done for you, keep the source list on your side. LinkedIn does not document how quickly companies dropped from the list stop being targeted, so treat removals as eventual rather than immediate. Rows are plain text (not hashed), matched against LinkedIn's own company graph. Matching is asynchronous: LinkedIn takes up to 48h for a new audience and up to 24h for a later update, and the audience stays `processing` meanwhile. LinkedIn recommends at least 1,000 companies for a usable match rate, and caps a list at 300,000.  The initial list is sent with `companies` on `POST /v1/ads/audiences`; this endpoint is for every change after that. 
+  # @param audience_id 
+  # @param replace_ad_audience_companies_request 
+  # @param [Hash] opts the optional parameters
+  # @return [ReplaceAdAudienceCompanies200Response]
+  describe 'replace_ad_audience_companies test' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   # unit tests for update_ad_audience
   # Update an audience
   # Update an audience. `saved_targeting` audiences accept `name`, `description`, and `spec` (full replacement, no merge, Zernio-only, no platform call). Platform audiences (uploaded/website/lookalike) accept `name` and `description` only, updated on the platform first and then mirrored locally; their rules are immutable, so `spec` returns 400 for them. Platform audience updates are Meta-only for now (other platforms return 501). Ads already created from a saved_targeting audience are unaffected, they snapshot the targeting at creation. 

data/spec/api/ad_creatives_api_spec.rb

@@ -154,6 +154,22 @@ describe 'AdCreativesApi' do
     end
   end
 
+  # unit tests for list_ad_videos
+  # Ad video library
+  # Lists the ad account's video library (Meta's `/act_X/advideos`), rows returned verbatim. The default projection covers id, title, status, poster frames and length; `fields` is a raw-passthrough override. Any `id` here is reusable as `video.id` on the create endpoints, so N ads that differ only in copy share one upload.  This is the only way to reach a video uploaded OUTSIDE Zernio (Ads Manager, another tool); videos we uploaded also come back as `creative.videoId` on GET /v1/ads.  Meta transcodes asynchronously, so a row is only usable once `status.video_status` reads `ready`. There is no upload operation here: upload by URL inline via `video.url` on POST /v1/ads/create.
+  # @param account_id Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token.
+  # @param ad_account_id Meta ad account id (act_<n>).
+  # @param [Hash] opts the optional parameters
+  # @option opts [String] :fields Comma-separated Graph field override (supports nested {} projections).
+  # @option opts [Integer] :limit Rows per page
+  # @option opts [String] :after Cursor from paging.after of the previous page.
+  # @return [ListAdVideos200Response]
+  describe 'list_ad_videos test' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   # unit tests for update_ad_creative
   # Rename a creative
   # Renames a creative. Creatives are immutable on Meta beyond `name` — for content changes create a new creative (POST /v1/ads/creatives) and swap it onto the ad (PUT /v1/ads/{adId} with `creative`).