Ad-server signals

/api/v2/storefront/esa/{esaId}/signals The ad-server signal endpoints let a storefront operator build and manage the signals a seller builds from targeting in an ad server source. The /esa/ path segment and esaId field are stable API identifiers; the operator-facing object is an ad server source. Keep these two layers distinct:

Term	Meaning
Ad-server targeting	Source-native audience segments, custom targeting keys, and custom targeting values already present in the connected ad server
Signal	A named targeting definition the seller creates from one or more source-native targeting primitives; carried as a `signal` on the API wire

Browsing ad-server targeting does not create or import a signal. It shows the raw material available for authoring. Start every authoring workflow by reading source capabilities. Capabilities describe which mapping kinds, API candidate types, value types, composition models, and parent-filtered types the source supports. Do not assume every ad server source supports GAM fields. When a selected targeting candidate includes defaultSignal, use that complete draft as the starting point instead of reconstructing its adapter mapping.

Endpoints

Method	Endpoint	Description
`GET`	`/api/v2/storefront/esa/{esaId}/signals`	List signals created on the source
`GET`	`/api/v2/storefront/esa/{esaId}/signals/{signalId}`	Read one signal
`POST`	`/api/v2/storefront/esa/{esaId}/signals`	Create a signal. Add `?dry_run=true` to validate and preview without persisting
`GET`	`/api/v2/storefront/esa/{esaId}/signals/adapter-capabilities`	Describe source support for signal authoring
`GET`	`/api/v2/storefront/esa/{esaId}/signals/candidates`	Browse source-native ad-server targeting; `candidates` is the API response name

Bulk signal creation with Murph

When you need to create many signals, ask Murph to create them as a batch instead of one by one. Murph still validates and previews the proposed signals before any durable write, and the confirmation gate still fires before creation. The batch is approved once, then Murph creates the set together.

Paste a list or upload rows. Murph maps each row to the source’s supported signal shape after reading source capabilities.
One approval for the batch. You review the full set and approve once rather than approving every signal individually.
Continues on error. If one signal fails, the rest continue. Murph reports a per-signal result so you can retry only the failures.

Use this for requests such as “create signals from these 49 GAM values,” “set up my first audience signals,” or “build signals from these key-values.”

Source capabilities

curl https://api.interchange.io/api/v2/storefront/esa/123/signals/adapter-capabilities \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

{
  "data": {
    "adapter": "google_ad_manager",
    "supportsSignalMappingAuthoring": true,
    "mappingKinds": [
      {
        "mappingKind": "audience_segment",
        "label": "Audience segment",
        "candidateType": "audience_segment",
        "supportsSearch": true
      },
      {
        "mappingKind": "gam_targeting_groups",
        "label": "GAM targeting groups",
        "candidateType": null,
        "supportsSearch": false
      }
    ],
    "supportedCandidateTypes": [
      "audience_segment",
      "custom_targeting_key",
      "custom_targeting_value"
    ],
    "candidateTypes": [
      {
        "candidateType": "custom_targeting_key",
        "label": "Custom targeting key",
        "browseOnly": true,
        "childCandidateTypes": ["custom_targeting_value"],
        "supportsSearch": true
      },
      {
        "candidateType": "custom_targeting_value",
        "label": "Custom targeting value",
        "mappingKind": "custom_key_value",
        "directlyMappable": true,
        "parentCandidateType": "custom_targeting_key",
        "supportsParentFilter": true,
        "supportsSearch": true
      }
    ],
    "targetingSemantics": {
      "supportsComposed": true,
      "compositionModels": ["groups"],
      "supportedModes": ["include", "exclude"],
      "mappingKinds": [
        {
          "mappingKind": "gam_targeting_groups",
          "supportsComposed": true,
          "compositionModels": ["groups"],
          "exclusiveWithOtherSignals": true,
          "notes": "Grouped GAM targeting must be used alone for buyer targeting that consumes this field."
        }
      ]
    },
    "valueTypes": ["binary", "categorical", "numeric"]
  }
}

Capability fields

Field	Notes
`adapter`	Adapter implementation behind the ad server source, for example `google_ad_manager`
`supportsSignalMappingAuthoring`	`false` means the source can list signals but cannot create drafts from this API
`mappingKinds`	Signal mapping kinds the adapter can create, such as `audience_segment`, `custom_key_value`, or `gam_targeting_groups`
`candidateTypes`	API types for browseable ad-server targeting. Types listed under `childCandidateTypes` can require `parent_id` when `supportsParentFilter` is true
`targetingSemantics`	Composition behavior, include/exclude modes, buyer targeting fields, and warnings such as exclusivity
`valueTypes`	Allowed `valueType` values for signal drafts

Browse ad-server targeting

Ad-server targeting records are source-native values that can be used to build a signal draft. The endpoint returns them in a candidates array; that is the wire name, not a separate operator-facing object. For hierarchical API types, first browse the parent type and then pass its externalId as parent_id when browsing the nested type.

curl "https://api.interchange.io/api/v2/storefront/esa/123/signals/candidates?candidate_type=custom_targeting_key&q=DAYOFWEEK&limit=10" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl "https://api.interchange.io/api/v2/storefront/esa/123/signals/candidates?candidate_type=custom_targeting_value&parent_id=17467172&q=FRIDAY&limit=10" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

{
  "data": {
    "candidates": [
      {
        "candidateType": "custom_targeting_value",
        "externalId": "451422266753",
        "name": "FRIDAY",
        "parentId": "17467172",
        "path": ["DAY OF WEEK", "FRIDAY"],
        "mappingKind": "custom_key_value",
        "defaultSignal": {
          "signalId": "dayofweek_friday",
          "name": "DAY OF WEEK: FRIDAY",
          "valueType": "binary",
          "adapterConfig": {
            "type": "passthrough",
            "kind": "custom_key_value",
            "keyId": "17467172",
            "valueId": "451422266753"
          }
        }
      }
    ],
    "count": 1,
    "nextCursor": null
  }
}

defaultSignal is the adapter-authored complete draft for that targeting candidate. Use it directly for validation, changing only signalId or name when the seller needs different buyer-facing wording. Validate again after any change.

Ad-server targeting query parameters

Parameter	Required	Notes
`candidate_type`	Yes	API type from `candidateTypes[].candidateType`
`q` or `query`	No	Adapter search string
`parent_id`	No	Parent candidate `externalId`, required by candidate types with `supportsParentFilter: true`
`limit`	No	Page size
`cursor`	No	Cursor returned as `nextCursor`

Signal draft shape

Creation and validation use the same request body:

Field	Type	Required	Notes
`signalId`	string	Yes	Stable caller-supplied signal identifier
`name`	string	Yes	Human-readable signal name
`description`	string or null	No	Operator-facing description
`valueType`	string	Yes	`binary`, `categorical`, or `numeric`; must appear in the adapter capability `valueTypes`
`tags`	string[]	No	Optional labels
`adapterConfig`	object	Yes	Adapter mapping configuration

How signals relate to products

Products describe the sellable inventory package. Signals describe targetable attributes that can be exposed to buyers or used in targeting workflows. For GAM key-values, do not treat “not in the product selector fields” as “not supported.” Key-value signal targeting is supported when the source capabilities advertise the relevant signal mapping kind. Use custom_key_value for a direct key/value mapping and gam_targeting_groups for composite GAM key-value logic. Then validate the signal and use it according to the adapter’s targetingSemantics. If targetingSemantics.mappingKinds[].exclusiveWithOtherSignals is true for gam_targeting_groups, use that grouped signal by itself for the buyer targeting field it consumes. Some large networks use GAM key-values to identify site lists or other seller-defined groups inside their network. Those keys and values are browseable as ad-server targeting and can be used to create signals. Publisher coverage still comes from adagents.json. Buyer property-list references are forwarded and resolved today; the seller’s agent decides whether and how to map the requested subset to products or ad-server controls. See Custom targeting and properties.

Audience segment

{
  "signalId": "auto_intenders",
  "name": "Auto intenders",
  "valueType": "binary",
  "adapterConfig": {
    "type": "passthrough",
    "kind": "audience_segment",
    "segmentId": "987654321"
  }
}

Direct GAM key-value signal

Use a direct custom_key_value signal when the adapter exposes a specific custom targeting value as directly mappable. Browse values with parent_id so the value remains tied to the correct key.

{
  "signalId": "dayofweek_friday",
  "name": "DAY OF WEEK: FRIDAY",
  "valueType": "binary",
  "adapterConfig": {
    "type": "passthrough",
    "kind": "custom_key_value",
    "keyId": "17467172",
    "valueId": "451422266753"
  }
}

Grouped GAM targeting

Use gam_targeting_groups for composite GAM logic. Groups are OR’d together; criteria inside a group are AND’d together; multiple values inside one criterion are OR’d by GAM for that key. A criterion with exclude: true excludes matching values. Grouped GAM targeting can be exclusive depending on the adapter semantics. If targetingSemantics.mappingKinds[].exclusiveWithOtherSignals is true, do not combine the grouped signal with another signal targeting the same buyer field.

{
  "signalId": "weekday_or_sports",
  "name": "Weekday or sports package",
  "valueType": "binary",
  "adapterConfig": {
    "type": "passthrough",
    "kind": "gam_targeting_groups",
    "groups": [
      {
        "criteria": [
          {
            "keyId": "17467172",
            "values": ["451422266753", "451420638792"]
          },
          {
            "keyId": "98765",
            "values": ["12345"],
            "exclude": true
          }
        ]
      },
      {
        "criteria": [
          {
            "keyId": "24680",
            "values": ["13579"]
          }
        ]
      }
    ]
  }
}

Validate a signal draft with `dry_run=true`

Use POST /api/v2/storefront/esa/{esaId}/signals?dry_run=true to validate and preview a signal draft without persisting it. The request body is the same as POST /signals, but the response is a validation result rather than a saved signal object. Read the valid flag, not the HTTP status — a dry run returns 200 even when the draft is invalid, and the issues[] array explains why. A malformed request body still returns 422.

curl -X POST "https://api.interchange.io/api/v2/storefront/esa/123/signals?dry_run=true" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signalId": "weekday_or_sports",
    "name": "Weekday or sports package",
    "valueType": "binary",
    "adapterConfig": {
      "type": "passthrough",
      "kind": "gam_targeting_groups",
      "groups": [
        {
          "criteria": [
            {
              "keyId": "17467172",
              "values": ["451422266753"]
            }
          ]
        }
      ]
    }
  }'

{
  "data": {
    "valid": true,
    "issues": []
  }
}

A dry run does not persist the signal. When the draft is valid the response also includes a preview with the rendered wire signal and source projections. Use a dry run before create when a client is assembling adapterConfig manually, or before update to preview a change.

Create a signal

curl -X POST https://api.interchange.io/api/v2/storefront/esa/123/signals \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signalId": "dayofweek_friday",
    "name": "DAY OF WEEK: FRIDAY",
    "valueType": "binary",
    "adapterConfig": {
      "type": "passthrough",
      "kind": "custom_key_value",
      "keyId": "17467172",
      "valueId": "451422266753"
    }
  }'

{
  "data": {
    "signalId": "dayofweek_friday",
    "name": "DAY OF WEEK: FRIDAY",
    "valueType": "binary",
    "adapterConfig": {
      "type": "passthrough",
      "kind": "custom_key_value",
      "keyId": "17467172",
      "valueId": "451422266753"
    }
  }
}

List and get signals

curl https://api.interchange.io/api/v2/storefront/esa/123/signals \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl https://api.interchange.io/api/v2/storefront/esa/123/signals/dayofweek_friday \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Signal response objects include at least signalId and name; sources can return additional fields such as description, status, valueType, adapterConfig, coverageForecast, createdAt, and updatedAt.

Errors

400 VALIDATION_ERROR — invalid ad server source id, malformed draft, missing required fields, or a source validation issue.
401 UNAUTHORIZED — missing or invalid bearer token.
404 NOT_FOUND — ad server source or signal does not exist for the caller.
502 or 503 — the ad server source or its upstream service could not complete the request.

See Errors for the full error contract.

Storefront signal tasks

Create and manage storefront signals

Custom targeting and properties

How GAM key-values relate to site lists and publisher coverage

Signal overview

Signal model and lifecycle

Storefront API reference

OpenAPI reference for storefront routes

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Endpoints

Bulk signal creation with Murph

Source capabilities

Capability fields

Browse ad-server targeting

Ad-server targeting query parameters

Signal draft shape

How signals relate to products

Audience segment

Direct GAM key-value signal

Grouped GAM targeting

Validate a signal draft with `dry_run=true`

Create a signal

List and get signals

Errors

Storefront signal tasks

Custom targeting and properties

Signal overview

Storefront API reference

​Endpoints

​Bulk signal creation with Murph

​Source capabilities

​Capability fields

​Browse ad-server targeting

​Ad-server targeting query parameters

​Signal draft shape

​How signals relate to products

​Audience segment

​Direct GAM key-value signal

​Grouped GAM targeting

​Validate a signal draft with dry_run=true

​Create a signal

​List and get signals

​Errors

​Related

Storefront signal tasks

Custom targeting and properties

Signal overview

Storefront API reference

Endpoints

Bulk signal creation with Murph

Source capabilities

Capability fields

Browse ad-server targeting

Ad-server targeting query parameters

Signal draft shape

How signals relate to products

Audience segment

Direct GAM key-value signal

Grouped GAM targeting

Validate a signal draft with `dry_run=true`

Create a signal

List and get signals

Errors

Related