Targeting

Every deal is either targeted — carrying one or more targeting groups — or
Run of Network, which matches all eligible supply with
no targeting rules at all. Exactly one of targeting and runOfNetwork must
be present on a submission.

For targeted deals, within the targeting model:

• Groups OR together — a request matches if any group matches.
• Rules within a group AND together.
• Values within a rule OR together.

Each rule either includes or excludes its values via match (include is the
default; use exclude to negate).

🚧

Only audience.segmentids values are checked

An unrecognized segment id is rejected with a 400 naming the ids in
question.

For every other attribute, a value that doesn't match the formats below is
accepted and then simply never matches traffic, with no error at any
point — so send the exact formats shown here.

👍

Read the vocabulary live

Rather than relying on this page staying current, you can read the accepted
values live — see
Discovering attributes and values.
GET /targeting-attributes lists every attribute and whether it has an
enumerable set of values, and GET /targeting-attributes/{attribute}/values
returns the values themselves. The endpoints are the source of truth; the
tables below are a snapshot for reading.

Run of Network

To create a deal with no targeting rules, send runOfNetwork: true instead
of targeting:

{
  "name": "Acme CTV Run of Network Q1",
  "adFormat": "video",
  "environments": ["ctv"],
  "runOfNetwork": true,
  "pricing": { "model": "auction", "floor": 12.0, "currency": "USD" },
  "commercial": { "takeRate": 0.15 },
  "schedule": { "startDate": "2027-01-01" },
  "buyers": [{ "partner": "thetradedesk", "seatIds": ["your-seat-id"] }]
}

A Run of Network deal matches all eligible supply within the deal's
adFormat and environment — those two fields still scope the deal; only the
targeting rules are absent.

• runOfNetwork and targeting are mutually exclusive; sending both (or
  neither) returns a 400.
• The only accepted value is true — to make a deal targeted, send
  targeting instead.
• A Run of Network deal must specify exactly one environment.

In responses, every deal carries a runOfNetwork boolean, and targeting is
null for Run of Network deals.

Switching modes after creation works through PATCH: sending
{ "runOfNetwork": true } converts a targeted deal to Run of Network
(its targeting rules are removed), and sending a targeting array converts a
Run of Network deal back to targeted. This is also the only way to remove
targeting from a deal — targeting itself cannot be cleared or set to an
empty array.

Discovering attributes and values

Two read-only endpoints expose the live vocabulary, so you don't have to track
changes to this page.

GET /sovrnos/v1/targeting-attributes lists every attribute a rule may use,
with a valueFormat telling you whether its values can be enumerated:

{
  "data": [
    {
      "attribute": "device.deviceType",
      "description": "OpenRTB device-type code as an integer, not a label. 3 is Connected TV.",
      "valueFormat": "enumerated",
      "valuesPath": "/sovrnos/v1/targeting-attributes/device.deviceType/values"
    },
    {
      "attribute": "site.domain",
      "description": "Registrable site domain, as free text — no scheme or path. For example \"espn.com\".",
      "valueFormat": "freeText",
      "valuesPath": null
    }
  ]
}

GET /sovrnos/v1/targeting-attributes/{attribute}/values returns the accepted
values for an enumerated attribute, each with a label:

{
  "attribute": "device.deviceType",
  "total": 8,
  "data": [{ "value": "3", "label": "Connected TV" }]
}

A freeText attribute has no list to return, so asking for its values responds
400 rather than an empty array — check valueFormat first, or follow
valuesPath, which is null exactly when there's nothing to enumerate.

Attribute reference

device.geo.country

Country as an ISO 3166-1 alpha-3 code (three uppercase letters). Alpha-2
codes such as US will not match.

Examples: USA, GBR, CAN, DEU, JPN, AUS.

device.deviceType

OpenRTB device-type code (integer), not a label:

Example: [3] targets Connected TV.

adUnit.size

A Sovrn size token (not a raw WxH string). Tokens are namespaced by medium
— wd web display, wv web video, mwd mobile web display, mb mobile in-app
banner, mv mobile video, ctv connected TV — as pixel tokens of the form
{medium}.px.{width}x{height}, plus category and aspect-ratio tokens. Send the
token exactly, e.g. wd.px.300x250.

This list grows as Sovrn adds sizes. For the current set, call
GET /sovrnos/v1/targeting-attributes/adUnit.size/values. If you need a size
that doesn't appear there, ask your Sovrn representative.

audience.segmentids

Sovrn-assigned audience segment IDs (integers). Read the current list from
GET /sovrnos/v1/targeting-attributes/audience.segmentids/values, which returns
each id with its human-readable label. Segment availability is account-specific,
so confirm which ids are provisioned to you with your Sovrn representative.

This is the one attribute whose values are validated. An id Sovrn doesn't
recognize is rejected at submission with a 400 naming the offending ids,
instead of creating a deal that silently never matches:

{
  "message": "body/targeting/0/rules/0/values unknown audience segment id(s): 999999999999. Segment availability is account-specific — ask your Sovrn representative for the ids provisioned to you."
}

Ids may be sent as integers or strings — 366 and "366" behave identically.
Only the unrecognized ids are named, so a rule mixing valid and invalid ids
tells you exactly which to fix.

geo.zip

Postal / ZIP code, as free text. Example: ["10001", "90210"].

site.domain

Registrable site domain, as free text (no scheme or path). Example:
["espn.com", "weather.com"].

app.bundleId

App-store bundle identifier, as free text — an iOS numeric store ID or an Android
package name. Example: ["284035177", "com.example.app"].