Function buildActivateSignalRequest

Parameters

• signal:
      | {
          restricted_attributes?: RestrictedAttribute[];
          demographic_predicate?: DemographicPredicate;
          policy_categories?: string[];
          taxonomy?: {
              ref: string;
              version?: string;
              segtax?: number;
              etag?: string;
              values: { id: string; path?: string; modifiers?: string[] }[];
              value_mappings?: {
                  value: string;
                  taxonomy_value_id: string;
                  path?: string;
                  modifiers?: string[];
              }[];
              parent_match_behavior?: | "unknown"
              | "exact_only"
              | "descendants_supported";
          };
          segmentation_criteria?: string;
          criteria_url?: string;
          data_sources?: (
              | "email"
              | "app_behavior"
              | "app_usage"
              | "web_usage"
              | "geo_location"
              | "tv_ott_or_stb_device"
              | "panel"
              | "online_ecommerce"
              | "credit_data"
              | "loyalty_card"
              | "transaction"
              | "online_survey"
              | "offline_survey"
              | "public_record_census"
              | "public_record_voter_file"
              | "public_record_other"
              | "offline_transaction"
          )[];
          methodology?: "declared"
          | "inferred"
          | "modeled"
          | "observed"
          | "derived";
          audience_expansion?: boolean;
          device_expansion?: boolean;
          refresh_cadence?:
              | "daily"
              | "weekly"
              | "monthly"
              | "quarterly"
              | "intra_day"
              | "bi_monthly"
              | "bi_annually"
              | "annually";
          lookback_window?: | "daily"
          | "weekly"
          | "monthly"
          | "quarterly"
          | "intra_day"
          | "bi_monthly"
          | "bi_annually"
          | "annually";
          onboarder?: {
              match_keys: (
                  | "email"
                  | "name"
                  | "address"
                  | "postal"
                  | "lat_long"
                  | "mobile_id"
                  | "cookie_id"
                  | "ip"
                  | "customer_id"
                  | "phone"
              )[];
              pre_onboarding_audience_expansion?: boolean;
              pre_onboarding_device_expansion?: boolean;
              pre_onboarding_precision_level?: | "individual"
              | "household"
              | "business"
              | "geography";
          };
          countries?: string[];
          consent_basis?: ConsentBasis[];
          art9_basis?: | "explicit_consent"
          | "manifestly_made_public"
          | "substantial_public_interest"
          | "vital_interests";
          modeling?: {
              method: "lookalike"
              | "supervised"
              | "embedding"
              | "rules";
              seed_source: {
                  type:
                      | "panel"
                      | "first_party_crm"
                      | "declared_survey"
                      | "transactional"
                      | "behavioral";
                  provider_signed: boolean;
              };
              training_data_jurisdictions: string[];
              ai_act_risk_class: "limited"
              | "minimal"
              | "high_risk";
              disclosure?: {
                  required: boolean;
                  jurisdictions?: [
                      {
                          country: string;
                          region?: string;
                          regulation: string;
                          disclosure_text?: string;
                          disclosure_url?: string;
                          audience?: "buyer"
                          | "public"
                          | "data_subject"
                          | "regulator";
                      },
                      ...{
                          country: string;
                          region?: string;
                          regulation: string;
                          disclosure_text?: string;
                          disclosure_url?: string;
                          audience?: "buyer"
                          | "public"
                          | "data_subject"
                          | "regulator";
                      }[],
                  ];
                  notes?: string;
              };
          };
          data_subject_rights?: {
              upstream_source_domain?: string;
              channels: {
                  rights: (
                      "access"
                      | "rectification"
                      | "erasure"
                      | "portability"
                      | "objection"
                  )[];
                  url?: string;
                  email?: string;
                  languages?: string[];
                  countries?: string[];
              }[];
              response_sla_days?: number;
              ccpa_opt_out_url?: string;
          };
          last_updated?: string;
          dts_compliant_version?: string;
          signal_ref?: SignalRef;
          signal_id?: SignalID;
          name: string;
          description: string;
          methodology_url?: string;
          value_type?: SignalValueType;
          categories?: string[];
          range?: { min: number; max: number };
          signal_agent_segment_id: string;
          signal_type: SignalAvailabilityType;
          data_provider?: string;
          coverage_percentage?: number;
          coverage_forecast?: {
              points: [
                  ForecastPoint & { dimensions: {}; metrics?: {} },
                  ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
              ];
              forecast_range_unit: "availability";
              method: ForecastMethod;
              scope: {
                  kind: "product" | "inventory" | "custom" | "account";
                  label: string;
                  product_id?: string;
                  countries?: [string, ...string[]];
                  line_item_types?: [string, ...string[]];
                  date_range?: DateRange;
              };
              bucket_semantics: "exclusive"
              | "overlapping";
              bucket_completeness: "complete" | "partial";
              generated_at?: string;
              valid_until?: string;
              ext?: ExtensionObject;
          };
          deployments: Deployment[];
          pricing_options?: VendorPricingOption[];
      }
      | NormalizedDiscoveredSignal
  • {
        restricted_attributes?: RestrictedAttribute[];
        demographic_predicate?: DemographicPredicate;
        policy_categories?: string[];
        taxonomy?: {
            ref: string;
            version?: string;
            segtax?: number;
            etag?: string;
            values: { id: string; path?: string; modifiers?: string[] }[];
            value_mappings?: {
                value: string;
                taxonomy_value_id: string;
                path?: string;
                modifiers?: string[];
            }[];
            parent_match_behavior?: "unknown"
            | "exact_only"
            | "descendants_supported";
        };
        segmentation_criteria?: string;
        criteria_url?: string;
        data_sources?: (
            | "email"
            | "app_behavior"
            | "app_usage"
            | "web_usage"
            | "geo_location"
            | "tv_ott_or_stb_device"
            | "panel"
            | "online_ecommerce"
            | "credit_data"
            | "loyalty_card"
            | "transaction"
            | "online_survey"
            | "offline_survey"
            | "public_record_census"
            | "public_record_voter_file"
            | "public_record_other"
            | "offline_transaction"
        )[];
        methodology?: "declared"
        | "inferred"
        | "modeled"
        | "observed"
        | "derived";
        audience_expansion?: boolean;
        device_expansion?: boolean;
        refresh_cadence?:
            | "daily"
            | "weekly"
            | "monthly"
            | "quarterly"
            | "intra_day"
            | "bi_monthly"
            | "bi_annually"
            | "annually";
        lookback_window?: | "daily"
        | "weekly"
        | "monthly"
        | "quarterly"
        | "intra_day"
        | "bi_monthly"
        | "bi_annually"
        | "annually";
        onboarder?: {
            match_keys: (
                | "email"
                | "name"
                | "address"
                | "postal"
                | "lat_long"
                | "mobile_id"
                | "cookie_id"
                | "ip"
                | "customer_id"
                | "phone"
            )[];
            pre_onboarding_audience_expansion?: boolean;
            pre_onboarding_device_expansion?: boolean;
            pre_onboarding_precision_level?: | "individual"
            | "household"
            | "business"
            | "geography";
        };
        countries?: string[];
        consent_basis?: ConsentBasis[];
        art9_basis?: | "explicit_consent"
        | "manifestly_made_public"
        | "substantial_public_interest"
        | "vital_interests";
        modeling?: {
            method: "lookalike"
            | "supervised"
            | "embedding"
            | "rules";
            seed_source: {
                type:
                    | "panel"
                    | "first_party_crm"
                    | "declared_survey"
                    | "transactional"
                    | "behavioral";
                provider_signed: boolean;
            };
            training_data_jurisdictions: string[];
            ai_act_risk_class: "limited"
            | "minimal"
            | "high_risk";
            disclosure?: {
                required: boolean;
                jurisdictions?: [
                    {
                        country: string;
                        region?: string;
                        regulation: string;
                        disclosure_text?: string;
                        disclosure_url?: string;
                        audience?: "buyer"
                        | "public"
                        | "data_subject"
                        | "regulator";
                    },
                    ...{
                        country: string;
                        region?: string;
                        regulation: string;
                        disclosure_text?: string;
                        disclosure_url?: string;
                        audience?: "buyer"
                        | "public"
                        | "data_subject"
                        | "regulator";
                    }[],
                ];
                notes?: string;
            };
        };
        data_subject_rights?: {
            upstream_source_domain?: string;
            channels: {
                rights: (
                    "access"
                    | "rectification"
                    | "erasure"
                    | "portability"
                    | "objection"
                )[];
                url?: string;
                email?: string;
                languages?: string[];
                countries?: string[];
            }[];
            response_sla_days?: number;
            ccpa_opt_out_url?: string;
        };
        last_updated?: string;
        dts_compliant_version?: string;
        signal_ref?: SignalRef;
        signal_id?: SignalID;
        name: string;
        description: string;
        methodology_url?: string;
        value_type?: SignalValueType;
        categories?: string[];
        range?: { min: number; max: number };
        signal_agent_segment_id: string;
        signal_type: SignalAvailabilityType;
        data_provider?: string;
        coverage_percentage?: number;
        coverage_forecast?: {
            points: [
                ForecastPoint & { dimensions: {}; metrics?: {} },
                ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
            ];
            forecast_range_unit: "availability";
            method: ForecastMethod;
            scope: {
                kind: "product" | "inventory" | "custom" | "account";
                label: string;
                product_id?: string;
                countries?: [string, ...string[]];
                line_item_types?: [string, ...string[]];
                date_range?: DateRange;
            };
            bucket_semantics: "exclusive"
            | "overlapping";
            bucket_completeness: "complete" | "partial";
            generated_at?: string;
            valid_until?: string;
            ext?: ExtensionObject;
        };
        deployments: Deployment[];
        pricing_options?: VendorPricingOption[];
    }

    • Optionalrestricted_attributes?: RestrictedAttribute[]

      Restricted attribute categories this listing touches. Required with demographic_predicate and must include age. For referenced provider/source signals, any projected values must match the authoritative definition.

    • Optionaldemographic_predicate?: DemographicPredicate

    • Optionalpolicy_categories?: string[]

      Policy categories this signal is sensitive for.

    • Optionaltaxonomy?: {
          ref: string;
          version?: string;
          segtax?: number;
          etag?: string;
          values: { id: string; path?: string; modifiers?: string[] }[];
          value_mappings?: {
              value: string;
              taxonomy_value_id: string;
              path?: string;
              modifiers?: string[];
          }[];
          parent_match_behavior?: "unknown"
          | "exact_only"
          | "descendants_supported";
      }

      Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.

    • Optionalsegmentation_criteria?: string

    • Optionalcriteria_url?: string

    • Optionaldata_sources?: (
          | "email"
          | "app_behavior"
          | "app_usage"
          | "web_usage"
          | "geo_location"
          | "tv_ott_or_stb_device"
          | "panel"
          | "online_ecommerce"
          | "credit_data"
          | "loyalty_card"
          | "transaction"
          | "online_survey"
          | "offline_survey"
          | "public_record_census"
          | "public_record_voter_file"
          | "public_record_other"
          | "offline_transaction"
      )[]

    • Optionalmethodology?: "declared" | "inferred" | "modeled" | "observed" | "derived"

    • Optionalaudience_expansion?: boolean

    • Optionaldevice_expansion?: boolean

    • Optionalrefresh_cadence?:
          | "daily"
          | "weekly"
          | "monthly"
          | "quarterly"
          | "intra_day"
          | "bi_monthly"
          | "bi_annually"
          | "annually"

    • Optionallookback_window?:
          | "daily"
          | "weekly"
          | "monthly"
          | "quarterly"
          | "intra_day"
          | "bi_monthly"
          | "bi_annually"
          | "annually"

    • Optionalonboarder?: {
          match_keys: (
              | "email"
              | "name"
              | "address"
              | "postal"
              | "lat_long"
              | "mobile_id"
              | "cookie_id"
              | "ip"
              | "customer_id"
              | "phone"
          )[];
          pre_onboarding_audience_expansion?: boolean;
          pre_onboarding_device_expansion?: boolean;
          pre_onboarding_precision_level?: | "individual"
          | "household"
          | "business"
          | "geography";
      }

    • Optionalcountries?: string[]

    • Optionalconsent_basis?: ConsentBasis[]

      Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.

    • Optionalart9_basis?:
          | "explicit_consent"
          | "manifestly_made_public"
          | "substantial_public_interest"
          | "vital_interests"

      Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis.

    • Optionalmodeling?: {
          method: "lookalike" | "supervised" | "embedding" | "rules";
          seed_source: {
              type:
                  | "panel"
                  | "first_party_crm"
                  | "declared_survey"
                  | "transactional"
                  | "behavioral";
              provider_signed: boolean;
          };
          training_data_jurisdictions: string[];
          ai_act_risk_class: "limited"
          | "minimal"
          | "high_risk";
          disclosure?: {
              required: boolean;
              jurisdictions?: [
                  {
                      country: string;
                      region?: string;
                      regulation: string;
                      disclosure_text?: string;
                      disclosure_url?: string;
                      audience?: "buyer"
                      | "public"
                      | "data_subject"
                      | "regulator";
                  },
                  ...{
                      country: string;
                      region?: string;
                      regulation: string;
                      disclosure_text?: string;
                      disclosure_url?: string;
                      audience?: "buyer"
                      | "public"
                      | "data_subject"
                      | "regulator";
                  }[],
              ];
              notes?: string;
          };
      }

      • method: "lookalike" | "supervised" | "embedding" | "rules"

      • seed_source: {
            type:
                | "panel"
                | "first_party_crm"
                | "declared_survey"
                | "transactional"
                | "behavioral";
            provider_signed: boolean;
        }

        • type: "panel" | "first_party_crm" | "declared_survey" | "transactional" | "behavioral"

        • provider_signed: boolean

          Provider assertion that the seed source carries a signed attestation. Consumers MUST NOT treat this boolean alone as cryptographic proof.

      • training_data_jurisdictions: string[]

      • ai_act_risk_class: "limited" | "minimal" | "high_risk"

      • Optionaldisclosure?: {
            required: boolean;
            jurisdictions?: [
                {
                    country: string;
                    region?: string;
                    regulation: string;
                    disclosure_text?: string;
                    disclosure_url?: string;
                    audience?: "buyer"
                    | "public"
                    | "data_subject"
                    | "regulator";
                },
                ...{
                    country: string;
                    region?: string;
                    regulation: string;
                    disclosure_text?: string;
                    disclosure_url?: string;
                    audience?: "buyer"
                    | "public"
                    | "data_subject"
                    | "regulator";
                }[],
            ];
            notes?: string;
        }

        • required: boolean

          The provider's claim that a modeling or AI-use disclosure is required for this signal in at least one applicable jurisdiction. This is a declared compliance signal, not a protocol-level legal determination.

        • Optionaljurisdictions?: [
              {
                  country: string;
                  region?: string;
                  regulation: string;
                  disclosure_text?: string;
                  disclosure_url?: string;
                  audience?: "buyer"
                  | "public"
                  | "data_subject"
                  | "regulator";
              },
              ...{
                  country: string;
                  region?: string;
                  regulation: string;
                  disclosure_text?: string;
                  disclosure_url?: string;
                  audience?: "buyer"
                  | "public"
                  | "data_subject"
                  | "regulator";
              }[],
          ]

          Jurisdictions where a modeling or AI-use disclosure applies.

          Min Items

          1

        • Optionalnotes?: string

          Optional provider notes on how the disclosure should be interpreted. Informational only; buyers should not branch programmatically on this text.

    • Optionaldata_subject_rights?: {
          upstream_source_domain?: string;
          channels: {
              rights: (
                  "access"
                  | "rectification"
                  | "erasure"
                  | "portability"
                  | "objection"
              )[];
              url?: string;
              email?: string;
              languages?: string[];
              countries?: string[];
          }[];
          response_sla_days?: number;
          ccpa_opt_out_url?: string;
      }

      Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.

    • Optionallast_updated?: string

      When this listing record was last updated. This indicates freshness of the listing record, not an attestation that the underlying data or model was refreshed at that time.

    • Optionaldts_compliant_version?: string

    • Optionalsignal_ref?: SignalRef

    • Optionalsignal_id?: SignalID

    • name: string

      Human-readable signal name

    • description: string

      Detailed signal description

    • Optionalmethodology_url?: string

      Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.

    • Optionalvalue_type?: SignalValueType

    • Optionalcategories?: string[]

      Valid values for categorical signals. Present when value_type is 'categorical'. Buyers must use one of these values in SignalTargeting.values.

    • Optionalrange?: { min: number; max: number }

      Valid range for numeric signals. Present when value_type is 'numeric'.

      • min: number

        Minimum value (inclusive)

      • max: number

        Maximum value (inclusive)

    • signal_agent_segment_id: string

      Opaque resolved-segment handle issued by this signal source. Pass this string verbatim to activate_signal.signal_agent_segment_id, and echo it in package signal targeting when the selected product option exposes the same handle. Treat the value as provider-scoped and opaque: providers MAY namespace it so two providers can expose similarly named signals without relying on a shared taxonomy. Do not pass the signal_id object as this handle, and do not reconstruct a segment handle from categorical values when get_signals returned a resolved segment.

    • signal_type: SignalAvailabilityType

    • Optionaldata_provider?: string

      Human-readable source name for the signal, when applicable. For data_provider-scoped signals this is the data provider name; for signal_source-scoped signals it may identify the signal source or proprietary origin.

    • Optionalcoverage_percentage?: number

      Deprecated

      DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only. If coverage_forecast includes an absent bucket over the same denominator, coverage_percentage SHOULD align with 100 * (1 - absent coverage_rate.mid).

      Minimum

      0

      Maximum

      100

    • Optionalcoverage_forecast?: {
          points: [
              ForecastPoint & { dimensions: {}; metrics?: {} },
              ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
          ];
          forecast_range_unit: "availability";
          method: ForecastMethod;
          scope: {
              kind: "product" | "inventory" | "custom" | "account";
              label: string;
              product_id?: string;
              countries?: [string, ...string[]];
              line_item_types?: [string, ...string[]];
              date_range?: DateRange;
          };
          bucket_semantics: "exclusive"
          | "overlapping";
          bucket_completeness: "complete" | "partial";
          generated_at?: string;
          valid_until?: string;
          ext?: ExtensionObject;
      }

      • points: [
            ForecastPoint & { dimensions: {}; metrics?: {} },
            ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
        ]

        Coverage or availability points. Each point reuses the standard ForecastPoint shape, MUST include a signal dimension, and MUST include metrics.coverage_rate. Use metrics.impressions for count denominators and metrics.coverage_rate for the fraction of the declared scope represented by the point.

        Min Items

        1

      • forecast_range_unit: "availability"

        How to interpret the points array. Signal coverage forecasts always use 'availability' because the points describe available inventory or population coverage, not spend curves or temporal pacing.

      • method: ForecastMethod

      • scope: {
            kind: "product" | "inventory" | "custom" | "account";
            label: string;
            product_id?: string;
            countries?: [string, ...string[]];
            line_item_types?: [string, ...string[]];
            date_range?: DateRange;
        }

        Explicit denominator for the coverage forecast. This identifies the inventory, product, account, or custom universe that coverage_rate values are relative to. Additional seller-specific qualifiers are allowed for scopes such as line item type, ad server, inventory class, country, or flight window.

        • kind: "product" | "inventory" | "custom" | "account"

          Denominator family for the coverage forecast.

        • label: string

          Human-readable denominator label, such as 'network price-priority inventory'.

        • Optionalproduct_id?: string

          Product denominator when kind is 'product'.

        • Optionalcountries?: [string, ...string[]]

          Countries included in the denominator, as ISO 3166-1 alpha-2 codes.

          Min Items

          1

        • Optionalline_item_types?: [string, ...string[]]

          Seller or ad-server line item types included in the denominator.

          Min Items

          1

        • Optionaldate_range?: DateRange

      • bucket_semantics: "exclusive" | "overlapping"

        'exclusive' means the returned signal-value buckets do not overlap with each other. 'overlapping' means one impression or user can appear in multiple returned buckets, so coverage_rate values may sum above 1.0. This field describes overlap among returned buckets; bucket_completeness declares whether the returned buckets cover the full denominator.

      • bucket_completeness: "complete" | "partial"

        'complete' means the returned buckets cover the declared denominator. For complete + exclusive forecasts, count metrics and coverage_rate values can be treated as a full partition, subject to metric additivity rules. 'partial' means omitted denominator share represents undisclosed, other, or unsupported buckets; buyers MUST NOT infer totals by summing returned points.

      • Optionalgenerated_at?: string

        When this coverage forecast was computed.

      • Optionalvalid_until?: string

        When this coverage forecast expires.

      • Optionalext?: ExtensionObject

    • deployments: Deployment[]

      Array of deployment targets

    • Optionalpricing_options?: VendorPricingOption[]

      Pricing options available for this signal when it has an incremental price. The buyer selects one and passes its pricing_option_id in report_usage or package-level signal_targeting_groups for billing verification. Omit when pricing is unavailable to the caller, bundled into the destination product, or has no incremental cost.

  • NormalizedDiscoveredSignal
• options: BuildActivateSignalRequestOptions