--- updatedAt: 2026-08-20T21:15:52.000Z agentTools: projectIndex: https://developer.sovrn.com/llms.txt --- # Get a targeting attribute's values The accepted values for one enumerated attribute. Free-text attributes have no list to enumerate, and asking for one returns `400`, so check `valueFormat` first. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Curation API", "summary": "Create and manage programmatic deals against Sovrn's curated supply.", "version": "1.28.0", "description": "# Curation API\n\nThe Curation API lets a curation partner create and manage programmatic\ndeals against Sovrn's supply: private-marketplace deals (`pmp`), where each\nbuyer names the seats that may transact, and `open` deals, which any buyer on\nthe DSP can transact on. You submit a deal request; Sovrn creates the deal in\nreal time and returns a Sovrn external deal ID (`SVN_…`) that you hand to your\nbuyer or DSP. You can then poll the deal's status and edit it.\n\n## Authentication\n\nEvery request must include the API key Sovrn issued to you, in the\n`x-api-key` request header:\n\n```\nx-api-key: \n```\n\nYour key is scoped to the Curation API. Treat it as a secret: it grants\nthe ability to create and edit deals on your account. Contact your Sovrn\nrepresentative to obtain or rotate a key.\n\n## Base URL\n\n```\nhttps://api.sovrn.com/sovrnos/v1\n```\n\nProduction is the only environment available to partners.\n\n## Rate limit\n\nRequests are limited to **15 per minute**. If you exceed it, requests are\nthrottled, so space out bulk operations accordingly.\n\n## Deal lifecycle\n\nA deal's status comes from its buyers: it is worked out from the state of\neach buyer on the deal, and you observe it through the read endpoints.\nPossible values: `active`, `scheduled`, `paused`, `review`,\n`dsp review`, `archived`. A deal with a future start date is created as\n`scheduled` and becomes `active` on its start date. You can also set the\nstatus yourself with `PATCH /deal-requests/{id}` when the deal reads\n`statusSettable: true`, which a read of the single deal reports; see the\nDeal lifecycle guide. A deal reads `review` when a buyer reported an\nerror, or when its buyers are not all in the same state. When a buyer did\nnot accept the deal, a read of the single deal names that buyer in\n`buyerIssues`: each entry carries the buyer's `partner`, a `message`\nand, when the issue maps to one, the `field` to correct. Correct the deal\nwith `PATCH /deal-requests/{id}`; saving the deal sends it to that buyer\nagain.\n\n## Targeting\n\nA deal is either targeted, carrying at least one targeting group, or Run of\nNetwork (`runOfNetwork: true`), which carries no targeting groups. A create\ncarries exactly one of `targeting` and `runOfNetwork`. Within the targeting\nmodel: **groups OR together** (a request matches if any group matches),\n**rules within a group AND together**, and **values within a rule OR\ntogether**. Each rule either includes or excludes its values (`match`).\nA deal request carries **at most 25 targeting groups** and **at most 100\nrules in total** across all groups. There is no limit on the number of\nvalues in a rule, but the whole request body is capped at 1 MB (1,048,576\nbytes), and a larger one returns `413`. Exceeding either targeting limit\nreturns a `400` naming the limit. Values are checked on submission for every\nattribute whose `valueFormat` is `enumerated` except `adUnit.size`: an\nunknown audience segment id, or a country code that is not available for\ntargeting, returns a `400` naming it, as does a device-type code that is not\namong the attribute's values or a `content.categorization.v1` code that is\nnot in IAB Content Taxonomy 1.0, and a 2-letter ISO 3166-1 alpha-2 country code\nsuch as `US` is converted to its 3-letter code, `USA`, before the deal is\nstored. Free-text attributes accept any value, and so do ad sizes, although\nthey have a list, so send the formats the Targeting guide shows. The one\nexception is `publisher.id`: a publisher id that is not a positive whole\nnumber up to 2147483647 returns a `400` naming it.\nDiscover the attributes and their accepted values with\n`GET /targeting-attributes`, and never hardcode the attribute list.\n\n## Take rate\n\n`commercial.takeRate` is your take rate, expressed as a decimal fraction\nbetween 0 and 0.85 (for example, `0.15` = 15%).\n\n## DV360 buyers\n\nA deal whose buyers include `dv360` is also created on DV360's side, and\nDV360 requires fields that are otherwise optional. Requests that include a\n`dv360` buyer must carry:\n\n- `description`: required; at most 2000 characters for `open` deals and\n 250 for `pmp` deals.\n- `schedule.endDate`: required, and later than `schedule.startDate`.\n- `schedule.startDate`: no more than one year from today.\n- `pricing.floor`: required, greater than 0, at most 6 decimal places.\n- `name`: at most 240 characters.\n\nA request missing any of these returns `400` with a message naming the\nfield and DV360.\n\nDV360 also fixes a deal's format and its medium type when the deal is\ncreated, and DOOH isn't available on DV360 deals. On an existing deal with a\n`dv360` buyer, `adFormat` cannot be changed, `environments` cannot\ninclude `dooh`, and `environments` can change only to a list that keeps\nthe deal's medium type; to change the format or the medium type, create a\nnew deal request instead. Each of these returns `400`. The message for a\nmedium-type change names the old and new environments, and the one for\n`dooh` says DOOH isn't available on DV360 deals.\n\nThe medium type DV360 lists a deal under follows from its `adFormat` and\n`environments`:\n\n- TV: a `banner`, `video` or `native` deal whose only environment is\n `ctv`.\n- Audio: an `audio` deal whose only environment is `web`, or whose only\n environment is `app`.\n- Digital: every other deal on `web`, `app` or `ctv`, including any\n deal with more than one environment. Digital includes CTV.\n\nSo a `banner`, `video` or `native` deal on `web` can add `app`, but\none whose only environment is `ctv` cannot add `web`.\n\n## Errors\n\nErrors return a JSON object with a human-readable `message`, except the\n`401` and the `500` described below, which are plain text.\n**`message` is always present on JSON errors: key off it.** The shapes:\n\n- `400`: request validation failed. Framework-generated: carries\n `statusCode`, `code` and `error` alongside `message` (for example\n `\"error\": \"Bad Request\"`); they supplement `message`, never replace it.\n- `401`: **not JSON.** Your key is validated at Sovrn's gateway before the\n request reaches the service, and a failure returns\n `content-type: text/plain` with a bare string body. Do not parse a\n `401` body as JSON.\n- `403`, `404`: carry `message` only.\n- `502`: the downstream deal system rejected the request, or returned a\n result the API could not use. Carries a required `upstream` field\n alongside `message`. A `502` from a write does not mean the request\n left nothing behind. On a create, the deal may already exist on Sovrn's\n side with no deal request recorded for it, so check with your Sovrn\n representative before retrying. On a `PATCH` that sets `status`, the\n other fields may already be applied, so re-send the same request until it\n returns `200`. An archived deal refuses every edit with a `502`, so\n re-sending will not help: if you were archiving the deal and the re-send\n keeps returning `502`, read the deal, and if it reads `archived`, the\n archive has already landed. See the Errors guide.\n\nIf the deal system cannot be reached or does not answer in time, the\nresponse is a `500`, not a `502`, and its body is the plain text\n`Internal Server Error`, not JSON. Take the same care before retrying a\nwrite as after a `502`. Treat any other unexpected `5xx` defensively: it\nmay not carry a JSON body either.\n\n## Testing\n\n`POST /deal-requests?dryRun=true` runs a request through every check this\nAPI makes and then stops, without contacting the deal system: nothing is\ncreated, and a request that fails returns the same error a real submission\nwould. Dry runs are for `POST` only: `?dryRun=true` on a `PATCH` is\nignored and the edit is applied. The Testing guide gives the recommended\nintegration flow. Contact your Sovrn representative before validating bid\nactivity or spend end to end.", "contact": { "name": "Sovrn", "url": "https://www.sovrn.com" } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Sovrn-issued API key. Send it in the `x-api-key` header on every request; Sovrn's API gateway exchanges it for the internal credential before the request reaches the service." } }, "schemas": { "AttributeValueList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attribute": { "type": "string", "enum": [ "device.geo.country", "geo.zip", "site.domain", "app.bundleId", "device.deviceType", "adUnit.size", "audience.segmentids", "device.language", "device.geo.region", "content.categorization.v3", "content.genre", "publisher.id", "content.categorization.v1" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeValue" } } }, "required": [ "attribute", "total", "data" ] }, "AttributeValue": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] }, "Error": { "type": "object", "description": "Deliberate application error. `message` is the single field guaranteed on every JSON error response.", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "FrameworkError": { "description": "Framework-generated request-validation failure. Carries `statusCode`, `code` and `error` alongside `message`; they supplement `message`, never replace it.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "FST_ERR_VALIDATION" }, "error": { "type": "string", "example": "Bad Request" } }, "required": [ "statusCode", "code", "error" ] } ] }, "UpstreamError": { "description": "The downstream deal system rejected the request, or returned a result the API could not use. `upstream` names the system that failed and is always present on a `502`.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "upstream": { "type": "string", "example": "vulcan" } }, "required": [ "upstream" ] } ] } }, "responses": { "Unauthorized": { "description": "The API key was missing or not accepted. **Not JSON**: a bare `text/plain` string: `api key not provided`, `invalid api key`, or `invalid api key syntax`.", "content": { "text/plain": { "schema": { "type": "string", "example": "invalid api key" } } } }, "Forbidden": { "description": "The key is valid but not permitted. `{\"message\": \"Insufficient scope\"}`: a read-only key sent a write (`POST` or `PATCH`). It is checked before the body is validated, even with `?dryRun=true`. `{\"message\": \"Partner not authorized for this API\"}`: the account is not enabled for this API. It is checked after the request is validated, so an invalid request gets its `400` first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpstreamError": { "description": "The downstream deal system rejected the request, or returned a result the API could not use. On a create the deal may already exist, so check with your Sovrn representative before retrying; on a `PATCH` that set `status`, re-send the same request until it returns `200`. An archived deal refuses every edit with a `502`, so re-sending will not help. Carries a required `upstream` field. See the Errors guide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } }, "AttributeValuesBadRequest": { "description": "The attribute accepts free text (no list to enumerate; `message` only) or the attribute key is unrecognized (framework-shaped). Check `valueFormat` first.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } } } }, "paths": { "/targeting-attributes/{attribute}/values": { "get": { "summary": "Get a targeting attribute's values", "tags": [ "Targeting Attributes" ], "parameters": [ { "schema": { "type": "string", "enum": [ "device.geo.country", "geo.zip", "site.domain", "app.bundleId", "device.deviceType", "adUnit.size", "audience.segmentids", "device.language", "device.geo.region", "content.categorization.v3", "content.genre", "publisher.id", "content.categorization.v1" ] }, "in": "path", "name": "attribute", "required": true } ], "responses": { "200": { "description": "The accepted values for the attribute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeValueList" } } } }, "400": { "$ref": "#/components/responses/AttributeValuesBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "502": { "$ref": "#/components/responses/UpstreamError" } }, "operationId": "getTargetingAttributeValues", "description": "The accepted values for one enumerated attribute. Free-text attributes have no list to enumerate, and asking for one returns `400`, so check `valueFormat` first." } } }, "servers": [ { "url": "https://api.sovrn.com/sovrnos/v1", "description": "Production" } ], "tags": [ { "name": "Targeting Attributes", "description": "Discover the targeting attributes a deal request may use, and the accepted values for each. Read-only." } ], "x-readme": { "explorer-enabled": false }, "security": [ { "apiKey": [] } ] } ````