API Reference

Verve Marketplace Deal API

Table of Contents

1. Overview

The Verve Marketplace Deal API provides secure and programmatic access to create, manage, retrieve, and search deals within the Verve Marketplace.

Key features include:

  • RESTful HTTP endpoints for deal management

  • Create, update, retrieve, and search deals

  • Apply inventory, geo, content, and audience targeting

  • Enforces rate limits of 500 requests per minute and a maximum burst rate of 50 requests per second. Requests exceeding these limits return an HTTP 429 Too Many Requests, see Error Handling.

📘

Important:

The Verve Marketplace Deal API does not currently support DV360 deal workflows. DV360 deals cannot be created, activated, or managed using the endpoints described in this document. Support for DV360 deal workflows is provided through the Sellers API and Verve integration documentation.

2. Authentication

All Verve Marketplace Deal APIs require a valid access token in the Authorization header. Reach out to your Account Manager to get your client credentials.

Authorization: Bearer <access_token>

Access tokens are generated using the provided client ID and client secret. Tokens are valid for one hour. When a token expires, generate a new access token by calling the token endpoint again using the same client credentials.

Generate an Access Token

curl --request POST
 --url https://auth.smaato.com/v2/auth/token/
 --header 'content-type: application/x-www-form-urlencoded' 
 --data client_secret=<client secret> 
 --data client_id=<client id> 
 --data grant_type=client_credentials

3. Endpoints

3.1 Base URL

https://marketplace-api-external.verve.com

3.2 Create a Deal

POST https://marketplace-api-external.verve.com/buyer/deals/v1/deals

3.2.1 Overview

Creates a new marketplace deal.

3.2.2 Request Body (Required)

See the Deal Object and Targeting Object sections for all supported fields.

FieldTypeDescription
namestringDeal name. Maximum 255 characters.
dspGroupIdintegerDSP Group ID associated with the deal.

3.2.3 Request Body Example

📘

Note:

If the status field is not provided in the request, the deal is created with INITIAL status by default. A deal can also be created directly with PAUSED or RUNNING status through the API. Deals in INITIAL status are automatically removed after one day. Once a deal reaches PAUSED or RUNNING status, it cannot be changed back to INITIAL; such requests are ignored.

Content-Type: application/json 
{
  "status": "INITIAL",
  "name": "My new deal",
  "description": "optional description",
  "externalDealId": "my-external-deal-id",
  "advertiserId": 4598,
  "dspGroupId": 9462255,
  "seatId": 784525,
  "timezone": "UTC",
  "start": "2025-11-09 21:59:22",
  "end": "2025-12-05 21:35:53",
  "priceModel": "MIN_PRICE",
  "eCpm": 4.75,
  "dealFeePercentage": 12.357,
  "targetings": {
    "adFormat": {
      "targetedValues": [
        51,
        52
      ]
    },
    "deviceType": {
      "whitelist": false,
      "targetedValues": [
        2158,
        2155
      ]
    },
    "adSize": {
      "whitelist": true,
      "targetedValues": [
        15,
        19
      ]
    },
    "channel": {
      "targetedValues": [
        2161,
        2162
      ]
    },
    "supplyBundleDomain": {
      "whitelist": true,
      "targetedValues": [
        "bundle1",
        "domain1"
      ]
    },
    "performanceVcr": {
      "kpiValue": 59.2
    },
    "performanceViewability": {
      "kpiValue": 72.3
    },
    "geoLocation": {
      "geoCountry": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US",
            "name": "United States"
          }
        ]
      },
      "geoState": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US-CA",
            "name": "California"
          }
        ]
      },
      "geoCity": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "Los Angeles-California-US",
            "name": "Los Angeles",
            "geoNameId": "5368361"
          }
        ]
      }
    },
    "ctvContentChannel": {
      "whitelist": true,
      "targetedValues": [
        2505,
        307
      ]
    },
    "ctvContentGenre": {
      "whitelist": true,
      "targetedValues": [
        123,
        456
      ]
    },
    "ctvContentRating": {
      "whitelist": true,
      "targetedValues": [
        1033
      ]
    },
    "ctvContentLanguage": {
      "whitelist": false,
      "targetedValues": [
        1444
      ]
    },
    "ctvContentLivestream": {
      "whitelist": true,
      "targetedValues": [
        258
      ]
    },
    "ctvContentNetwork": {
      "whitelist": false,
      "targetedValues": [
        3833
      ]
    },
    "ctvSkippable": {
      "whitelist": true,
      "targetedValues": [
        2245
      ]
    },
    "audienceTargeting": {
      "whitelist": true,
      "segments": [
        {
          "id": "7007123",
          "names": [
            "Some first name",
            "Some second name"
          ],
          "cpm": 1.23,
          "dataProvider": 12
        },
        {
          "id": "7007456",
          "names": [
            "Some other first name",
            "Some other second name"
          ],
          "cpm": 4.56,
          "dataProvider": 34
        }
      ]
    },
    "tagId": {
      "targetedValues": [
        "tag-123",
        "tag-456"
      ]
    },
    "inboundDealId": {
      "targetedValues": [
        "inbound-deal-A",
        "inbound-deal-B"
      ]
    }
  }
}

3.2.4 Response Example

Returns the successfully created deal object. For possible error responses, see Error Handling.

{
  "id": 1005687,
  "marketplaceDealId": "17ca954f-c8da-4201-83c2-6d45e7f6d3e3",
  "externalDealId": "my-external-deal-id",
  "status": "INITIAL",
  "name": "My new deal",
  "description": "optional description",
  "advertiserId": 4598,
  "advertiserName": "My advertiser",
  "dspGroupId": 9462255,
  "dspGroupName": "A DSP name",
  "seatId": 784525,
  "seatName": "A seat name",
  "timezone": "UTC",
  "start": "2025-11-09 21:59:22",
  "end": "2025-12-05 21:35:53",
  "priceModel": "MIN_PRICE",
  "eCpm": 4.75,
  "dealFeePercentage": 12.357,
  "targetings": {
    "adFormat": {
      "whitelist": true,
      "targetedValues": [
        51,
        52
      ]
    },
    "deviceType": {
      "whitelist": false,
      "targetedValues": [
        2158,
        2155
      ]
    },
    "adSize": {
      "whitelist": true,
      "targetedValues": [
        15,
        19
      ]
    },
    "channel": {
      "whitelist": true,
      "targetedValues": [
        2161,
        2162
      ]
    },
    "supplyBundleDomain": {
      "whitelist": true,
      "targetedValues": [
        "bundle1",
        "domain1"
      ]
    },
    "performanceVcr": {
      "kpiValue": 59.2
    },
    "performanceViewability": {
      "kpiValue": 72.3
    },
    "geoLocation": {
      "geoCountry": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US",
            "name": "United States"
          }
        ]
      },
      "geoState": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US-CA",
            "name": "California"
          }
        ]
      },
      "geoCity": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "Los Angeles-California-US",
            "name": "Los Angeles",
            "geoNameId": "5368361"
          }
        ]
      }
    },
    "ctvContentChannel": {
      "whitelist": true,
      "targetedValues": [
        2505,
        307
      ]
    },
    "ctvContentGenre": {
      "whitelist": true,
      "targetedValues": [
        123,
        456
      ]
    },
    "ctvContentRating": {
      "whitelist": true,
      "targetedValues": [
        1033
      ]
    },
    "ctvContentLanguage": {
      "whitelist": false,
      "targetedValues": [
        1444
      ]
    },
    "ctvContentLivestream": {
      "whitelist": true,
      "targetedValues": [
        258
      ]
    },
    "ctvContentNetwork": {
      "whitelist": false,
      "targetedValues": [
        3833
      ]
    },
    "ctvSkippable": {
      "whitelist": true,
      "targetedValues": [
        2245
      ]
    },
    "audienceTargeting": {
      "whitelist": true,
      "segments": [
        {
          "id": "7007123",
          "names": [
            "Some first name",
            "Some second name"
          ],
          "cpm": 1.23,
          "dataProvider": 12
        },
        {
          "id": "7007456",
          "names": [
            "Some other first name",
            "Some other second name"
          ],
          "cpm": 4.56,
          "dataProvider": 34
        }
      ]
    },
    "tagId": {
      "whitelist": true,
      "targetedValues": [
        "tag-123",
        "tag-456"
      ]
    },
    "inboundDealId": {
      "whitelist": true,
      "targetedValues": [
        "inbound-deal-A",
        "inbound-deal-B"
      ]
    }
  }
}
📘

Note

After a deal is created with INITIAL status, activate it by calling the Update a Deal endpoint and setting status to RUNNING.
Once the deal reaches RUNNING status, it becomes active and eligible for delivery.

3.3 Update a Deal

PUT https://marketplace-api-external.verve.com/buyer/deals/v1/deals/{id}

3.3.1 Overview

Updates an existing deal.

3.3.2 Path Parameter

ParameterTypeRequiredDescription
idintegerYesUnique deal identifier

3.3.3 Request Body

See the Deal Object and Targeting Object section for all supported fields.

3.3.4 Request Body Example

Content-Type: application/json 
{
  "status": "RUNNING",
  "name": "My new deal",
  "description": "optional description",
  "externalDealId": "my-external-deal-id",
  "advertiserId": 4598,
  "dspGroupId": 9462255,
  "seatId": 784525,
  "timezone": "UTC",
  "start": "2025-11-09 21:59:22",
  "end": "2025-12-05 21:35:53",
  "priceModel": "MIN_PRICE",
  "eCpm": 4.75,
  "dealFeePercentage": 12.357,
  "targetings": {
    "adFormat": {
      "targetedValues": [
        51,
        52
      ]
    },
    "deviceType": {
      "whitelist": false,
      "targetedValues": [
        2158,
        2155
      ]
    },
    "adSize": {
      "whitelist": true,
      "targetedValues": [
        15,
        19
      ]
    },
    "channel": {
      "targetedValues": [
        2161,
        2162
      ]
    },
    "supplyBundleDomain": {
      "whitelist": true,
      "targetedValues": [
        "bundle1",
        "domain1"
      ]
    },
    "performanceVcr": {
      "kpiValue": 59.2
    },
    "performanceViewability": {
      "kpiValue": 72.3
    },
    "geoLocation": {
      "geoCountry": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US",
            "name": "United States"
          }
        ]
      },
      "geoState": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US-CA",
            "name": "California"
          }
        ]
      },
      "geoCity": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "Los Angeles-California-US",
            "name": "Los Angeles",
            "geoNameId": "5368361"
          }
        ]
      }
    },
    "ctvContentChannel": {
      "whitelist": true,
      "targetedValues": [
        2505,
        307
      ]
    },
    "ctvContentGenre": {
      "whitelist": true,
      "targetedValues": [
        1033
      ]
    },
    "ctvContentRating": {
      "whitelist": true,
      "targetedValues": [
        1097
      ]
    },
    "ctvContentLanguage": {
      "whitelist": false,
      "targetedValues": [
        1444
      ]
    },
    "ctvContentLivestream": {
      "whitelist": true,
      "targetedValues": [
        258
      ]
    },
    "ctvContentNetwork": {
      "whitelist": false,
      "targetedValues": [
        3833
      ]
    },
    "ctvSkippable": {
      "whitelist": true,
      "targetedValues": [
        2245
      ]
    },
    "audienceTargeting": {
      "whitelist": true,
      "segments": [
        {
          "id": "7007123",
          "names": [
            "Some first name",
            "Some second name"
          ],
          "cpm": 1.23,
          "dataProvider": 12
        },
        {
          "id": "7007456",
          "names": [
            "Some other first name",
            "Some other second name"
          ],
          "cpm": 4.56,
          "dataProvider": 34
        }
      ]
    },
    "tagId": {
      "targetedValues": [
        "tag-123",
        "tag-458"
      ]
    },
    "inboundDealId": {
      "targetedValues": [
        "inbound-deal-A",
        "inbound-deal-C"
      ]
    }
  }
}

3.3.5 Response Example

Returns the successfully updated deal object. For other possible error responses, see Error Handling.

{
  "id": 1005687,
  "marketplaceDealId": "17ca954f-c8da-4201-83c2-6d45e7f6d3e3",
  "externalDealId": "my-external-deal-id",
  "status": "RUNNING",
  "name": "My new deal",
  "description": "optional description",
  "advertiserId": 4598,
  "advertiserName": "My advertiser",
  "dspGroupId": 9462255,
  "dspGroupName": "A DSP name",
  "seatId": 784525,
  "seatName": "A seat name",
  "timezone": "UTC",
  "start": "2026-02-09 21:59:22",
  "end": "2026-06-05 21:35:53",
  "priceModel": "MIN_PRICE",
  "eCpm": 4.75,
  "dealFeePercentage": 12.357,
  "targetings": {
    "adFormat": {
      "whitelist": true,
      "targetedValues": [
        51,
        52
      ]
    },
    "deviceType": {
      "whitelist": false,
      "targetedValues": [
        2158,
        2155
      ]
    },
    "adSize": {
      "whitelist": true,
      "targetedValues": [
        15,
        19
      ]
    },
    "channel": {
      "whitelist": true,
      "targetedValues": [
        2161,
        2162
      ]
    },
    "supplyBundleDomain": {
      "whitelist": true,
      "targetedValues": [
        "bundle1",
        "domain1"
      ]
    },
    "performanceVcr": {
      "kpiValue": 59.2
    },
    "performanceViewability": {
      "kpiValue": 72.3
    },
    "geoLocation": {
      "geoCountry": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US",
            "name": "United States"
          }
        ]
      },
      "geoState": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US-CA",
            "name": "California"
          }
        ]
      },
      "geoCity": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "Los Angeles-California-US",
            "name": "Los Angeles",
            "geoNameId": "5368361"
          }
        ]
      }
    },
    "ctvContentChannel": {
      "whitelist": true,
      "targetedValues": [
        2505,
        307
      ]
    },
    "ctvContentGenre": {
      "whitelist": true,
      "targetedValues": [
        1033
      ]
    },
    "ctvContentRating": {
      "whitelist": true,
      "targetedValues": [
        1097
      ]
    },
    "ctvContentLanguage": {
      "whitelist": false,
      "targetedValues": [
        1444
      ]
    },
    "ctvContentLivestream": {
      "whitelist": true,
      "targetedValues": [
        258
      ]
    },
    "ctvContentNetwork": {
      "whitelist": false,
      "targetedValues": [
        3833
      ]
    },
    "ctvSkippable": {
      "whitelist": true,
      "targetedValues": [
        2245
      ]
    },
    "audienceTargeting": {
      "whitelist": true,
      "segments": [
        {
          "id": "7007123",
          "names": [
            "Some first name",
            "Some second name",
            "Some third name"
          ],
          "cpm": 1.23,
          "dataProvider": 12
        },
        {
          "id": "7007456",
          "names": [
            "Some other first name",
            "Some other second name",
            "Some other third name"
          ],
          "cpm": 4.56,
          "dataProvider": 34
        }
      ]
    },
    "tagId": {
      "whitelist": true,
      "targetedValues": [
        "tag-123",
        "tag-458"
      ]
    },
    "inboundDealId": {
      "whitelist": true,
      "targetedValues": [
        "inbound-deal-A",
        "inbound-deal-C"
      ]
    }
  }
}

3.4 Get a Deal

GET https://marketplace-api-external.verve.com/buyer/deals/v1/deals/{id}

3.4.1 Overview

Retrieves a deal by its ID.

3.4.2 Path Parameter

ParameterTypeRequiredDescription
idintegerYesUnique deal identifier

3.4.3 Response Example

Returns the deal object for the specified deal ID. For possible error responses, see Error Handling.

{
  "id": 1005687,
  "marketplaceDealId": "17ca954f-c8da-4201-83c2-6d45e7f6d3e3",
  "externalDealId": "my-external-deal-id",
  "status": "RUNNING",
  "name": "My new deal",
  "description": "optional description",
  "advertiserId": 4598,
  "advertiserName": "My advertiser",
  "dspGroupId": 9462255,
  "dspGroupName": "A DSP name",
  "seatId": 784525,
  "seatName": "A seat name",
  "timezone": "UTC",
  "start": "2026-02-09 21:59:22",
  "end": "2026-05-05 21:35:53",
  "priceModel": "MIN_PRICE",
  "eCpm": 4.75,
  "dealFeePercentage": 12.357,
  "targetings": {
    "adFormat": {
      "whitelist": true,
      "targetedValues": [
        123,
        456
      ]
    },
    "deviceType": {
      "whitelist": false,
      "targetedValues": [
        2158,
        2155
      ]
    },
    "adSize": {
      "whitelist": true,
      "targetedValues": [
        15,
        19
      ]
    },
    "channel": {
      "whitelist": true,
      "targetedValues": [
        2161,
        2162
      ]
    },
    "supplyBundleDomain": {
      "whitelist": true,
      "targetedValues": [
        "bundle1",
        "domain1"
      ]
    },
    "performanceVcr": {
      "kpiValue": 59.2
    },
    "performanceViewability": {
      "kpiValue": 72.3
    },
    "geoLocation": {
      "geoCountry": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US",
            "name": "United States"
          }
        ]
      },
      "geoState": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "US-CA",
            "name": "California"
          }
        ]
      },
      "geoCity": {
        "whitelist": true,
        "targetedValues": [
          {
            "code": "Los Angeles-California-US",
            "name": "Los Angeles",
            "geoNameId": "5368361"
          }
        ]
      }
    },
    "ctvContentChannel": {
      "whitelist": true,
      "targetedValues": [
        2505,
        307
      ]
    },
    "ctvContentGenre": {
      "whitelist": true,
      "targetedValues": [
        1033
      ]
    },
    "ctvContentRating": {
      "whitelist": true,
      "targetedValues": [
        1097
      ]
    },
    "ctvContentLanguage": {
      "whitelist": false,
      "targetedValues": [
        1444
      ]
    },
    "ctvContentLivestream": {
      "whitelist": true,
      "targetedValues": [
        258
      ]
    },
    "ctvContentNetwork": {
      "whitelist": false,
      "targetedValues": [
        3833
      ]
    },
    "ctvSkippable": {
      "whitelist": true,
      "targetedValues": [
        2245
      ]
    },
    "audienceTargeting": {
      "whitelist": true,
      "segments": [
        {
          "id": "7007123",
          "names": [
            "Some first name",
            "Some second name",
            "Some third name"
          ],
          "cpm": 1.23,
          "dataProvider": 12
        },
        {
          "id": "7007456",
          "names": [
            "Some other first name",
            "Some other second name",
            "Some other third name"
          ],
          "cpm": 4.56,
          "dataProvider": 34
        }
      ]
    },
  "tagId": {
      "whitelist": true,
      "targetedValues": [
        "tag-123",
        "tag-458"
      ]
    },
    "inboundDealId": {
      "whitelist": true,
      "targetedValues": [
        "inbound-deal-A",
        "inbound-deal-C"
      ]
    }

  }
}

3.5 Get a Deal List

GET https://marketplace-api-external.verve.com/buyer/deals/v1/deals

3.5.1 Overview

Retrieves a paginated list of deals.

3.5.2 Pagination

The Get a Deal List endpoint returns paginated results. Use the page-number and page-size parameters to retrieve results page by page.

To retrieve all matching deals:

  1. Start with page-number = 0

  2. Increase page-number by 1 for each subsequent request

  3. Continue requesting pages until the response contains fewer records than the requested page-size or until numberOfElements = 0 If you request a page after the last page with content, the API returns an empty list of elements and numberOfElements=0.

Example: Retrieve the first page

GET {base_url}/buyer/deals/v1/deals?page-number=0&page-size=100

Example: Retrieve the next page

GET {base_url}/buyer/deals/v1/deals?page-number=1&page-size=100

3.5.3 Query Parameters

ParameterTypeRequiredDefaultDescription
page-numberintegerNo0Page number to retrieve. Minimum: 0
page-sizeintegerNo100Number of records per page. Minimum: 1, Maximum: 1000.
search-termstringNo-Search supports deal name, marketplaceDealId, externalDealId, buyer name, advertiser name, DSP group name, or seat name. Search terms are case-insensitive and support partial matches.

3.5.4 Response Example

{
  "data": {
    "deals": [
      {
        "id": 10000001,
        "marketplaceDealId": "60100000-ee1d-435d-84bf-a13d8y20fdaa",
        "externalDealId": "externaldealid-weaw1f2gf4a",
        "name": "Deal 5",
        "status": "RUNNING",
        "start": "2026-05-15 00:00:00",
        "end": "2026-06-15 23:59:59"
      }
    ]
  },
  "metaData": {
    "numberOfElements": 1,
    "pageNumber": 0,
    "pageSize": 100,
    "totalNumberOfElements": 1,
    "timestamp": 1778857186410,
    "duration": 10,
    "searchTerm": "externaldealid-weaw1f2gf4a"
  }
}

4. Deal Object

FieldTypeRequiredDescription
idintegerNoRead-only. Unique deal identifier
marketplaceDealIdstringNoRead-only. Marketplace deal ID
externalDealIdstringNoExternal deal ID: Maximum 256 characters ^[a-zA-Z0-9+#,-]+$
namestringYesDeal name: Maximum 255 characters. Angle brackets are not allowed
descriptionstringNoDeal description. Maximum 2500 characters. Angle brackets are not allowed
statusstringNoDeal status. Default: INITIAL Supported values:
  • INITIAL
  • PAUSED
  • RUNNING
advertiserIdintegerNoAdvertiser ID
advertiserNamestringNoAdvertiser Name
dspGroupIdintegerYesDSP group ID associated with the deal. The dspGroupId cannot be modified after the deal reaches RUNNING status for the first time.
dspGroupNamestringNoRead-only. DSP group name
seatIdintegerNoSeat ID
seatNamestringNoRead-only. Seat name
priceModelstringNoSupported values: MIN_PRICE, FIXED_PRICE. Default: MIN_PRICE.
eCpmdecimalNoeCpm value. Minimum 0.01, maximum 1000.00 , max 2 decimal places, default 0.01
timezonestringNoTimezone. Default: UTC
startstringNoDeal start date and time in "yyyy-MM-dd HH:mm:ss" format. Cannot be modified after the deal reaches RUNNING status for the first time
endstringNoDeal end date and time in "yyyy-MM-dd HH:mm:ss" format. Cannot be modified after the deal reaches RUNNING status for the first time.
dealFeePercentagedecimalNoDeal fee percentage. Minimum 0.0000, maximum 99.9999 Maximum 4 decimal places

5. Targeting Object

All Targeting Objects are optional.

📘

Note: To view all columns, place your cursor over the table, then use the ← and → arrow keys on your keyboard to scroll horizontally, or use the horizontal scrollbar at the bottom of the table.

Targeting ObjectPropertyTypeRequiredDefaultExampleNotes / Supported Values
adFormatwhitelistN/ANoN/AN/AThe default value is true. When it is set to false, the API returns 400 BAD_REQUEST error, see Error Handling.
adFormattargetedValuesinteger[]YesNone[51,52]Ad Format IDs:
  • 51=Video,
  • 52=Banner,
  • 59=Native,
  • 3941=Rewarded Video, etc.
deviceTypewhitelistbooleanNotruetrue/false

  • whitelist = true: Only the device types listed in targetedValues are eligible for targeting.

  • whitelist = false: The device types listed in targetedValues are excluded from targeting. All other device types remain eligible.

deviceTypetargetedValuesinteger[]YesNone[2158,2155]Device Type IDs:
  • 2158 = Connected TV,
  • 2155 =Mobile/Tablet - General,
  • 2157=Personal Computer,
  • 2159=Phone,
  • 2156= Tablet,
  • 3942 = Connected Device,
  • 3943 = Set Top Box, etc.
adSizewhitelistbooleanNotruetrue/false

  • whitelist = true: Only the ad sizes listed in targetedValues are eligible for targeting.

  • whitelist = false: The ad sizes listed in targetedValues are excluded from targeting. All other ad sizes remain eligible.

adSizetargetedValuesinteger[]YesNone[15,19]Ad Size IDs:

  • 15 = 300 X 50,

  • 19 = 320 X 50,

  • 8 = 320 X 100,

  • 5 = 250 X 250,

  • 4 = 728 X 90,

  • 3 = 120 X 600,

  • 2 = 300 X 250,

  • 31 = 336 X 280, etc.

channelwhitelistNoneNoN/AN/AThe default value is true. When it is set to false, the API returns a 400 BAD_REQUEST error, see Error Handling.
channeltargetedValuesinteger[]YesNone[2161,2162]

Channel IDs:

2161= Mobile In-App, 2162 = Mobile Web, 3936= CTV, 3940 = Desktop Web, etc.

supplyBundleDomainwhitelistbooleanNotruetrue/false

  • whitelist= true: Only the bundles/domains listed in targetedValues are eligible for targeting.

  • whitelist= false: The bundles/domains listed in targetedValues are excluded from targeting. All other bundles/domains remain eligible.

supplyBundleDomaintargetedValuesstring[]YesNone["com.example.app","example.com"]Bundle IDs or Domains (max 250,000 entries). Invalid bundle/domain names are ignored.
performanceVcrkpiValuedecimalYesNone60.0Range: 40.0–90.0 (increments of 5), decimal of 1. Values outside the supported range or increment will result in a 400 Bad Request, see Error Handling.
performanceViewabilitykpiValuedecimalYesNone70.0Range: 40.0–90.0 (increments of 5), decimal of 1. Values outside the supported range or increment will result in a 400 Bad Request, see Error Handling.
geoLocationgeoLocationobjectNoNoneN/AIf geoLocation is specified, at least one of geoCountry, geoState, or geoCity must be provided.
geoLocation.geoCountrywhitelistbooleanNotruetrue/false
  • whitelist = true: Only the countries listed in targetedValues are eligible for targeting .
  • whitelist = false: The countries listed in targetedValues are excluded from targeting. All other countries remain eligible.
geoLocation.geoCountrytargetedvalue.codestringYesNone"US"Country Code; Max 50 characters
geoLocation.geoCountrytargetedvalue.namestringYesNone"United States"Country Name, Max 200 characters
geoLocation.geoStatewhitelistbooleanNotruetrue/false

  • whitelist = true: Only the states listed in targetedValues are eligible for targeting.

  • whitelist = false: The states listed in targetedValues are excluded from targeting. All other states remain eligible.

geoLocation.geoStatetargetedvalue.codestringYesNone"US-CA"State Code, Max 50 characters
geoLocation.geoStatetargetedvalue.namestringYesNone""California""State Name, Max 200 characters
geoLocation.geoCitywhitelistbooleanNotruetrue/false

  • whitelist = true: Only the cities listed in targetedValues are eligible for targeting.

  • whitelist = false: The cities listed in targetedValues are excluded from targeting. All other cities remain eligible.

geoLocation.geoCitytargetedvalue.codestringYesNone"Los Angeles-California-US"City Code, max 50 characters
geoLocation.geoCitytargetedvalue.namestringYesNone"Los Angeles"City Name, Max 200 characters
geoLocation.geoCitytargetedvalue.geoNameIdstringNoNone"5368361"GeoNames identifier
ctvContentChannelwhitelistbooleanNotruetrue/false

  • whitelist = true: Only the CTV channels listed in targetedValues are eligible for targeting.

  • whitelist = false: The CTV channels listed in targetedValues are excluded from targeting. All other CTV channels remain eligible.

ctvContentChanneltargetedValuesinteger[]YesNone[2505, 307]CTV Content Channel IDs:
  • 2505= 1001.tv,
  • 307 = 2048 World Cup, etc.
ctvContentGenrewhitelistbooleanNotruetrue/false

  • whitelist = true: Only the CTV content genres listed in targetedValues are eligible for targeting.

  • whitelist = false: The CTV content genres listed in targetedValues are excluded from targeting. All other CTV content genres remain eligible.

ctvContentGenretargetedValuesinteger[]YesNone[1033]CTV Genre IDs:
  • 1033 = Action & Adventure
  • 1034 = Animation, etc.
ctvContentRatingwhitelistbooleanNotruetrue/false

  • whitelist = true: Only the CTV content ratings listed in targetedValues are eligible for targeting.

  • whitelist = false: The CTV content ratings listed in targetedValues are excluded from targeting. All other CTV content ratings remain eligible.

ctvContentRatingtargetedValuesinteger[]YesNone[1097]CTV Rating IDs:
  • 1097= TV-14,
  • 1098 = Movie-G, etc.
ctvContentLanguagewhitelistbooleanNotruetrue/false

  • whitelist = true: Only the CTV content languages listed in targetedValues are eligible for targeting.

  • whitelist = false: The CTV content languages listed in targetedValues are excluded from targeting. All other CTV content languages remain eligible.

ctvContentLanguagetargetedValuesinteger[]YesNone[1444]CTV Language IDs:
  • 1444 = Arabic,
  • 1437 = Abkhazian,
  • 1438 = Afar, etc.
ctvContentLivestreamwhitelistbooleanNotruetrue/false

  • whitelist = true: Only the livestream content types listed in targetedValues are eligible for targeting.

  • whitelist = false: The livestream content types listed in targetedValues are excluded from targeting. All other livestream content types remain eligible.

ctvContentLivestreamtargetedValuesinteger[]YesNone[258]Livestream IDs (max 1 value)
  • 258 = Livestream
ctvContentNetworkwhitelistbooleanNotruetrue/false

  • whitelist = true: Only the CTV content networks listed in targetedValues are eligible for targeting.

  • whitelist = false: The CTV content networks listed in targetedValues are excluded from targeting. All other CTV content networks remain eligible.

ctvContentNetworktargetedValuesinteger[]YesNone[3833]Network IDs:

  • 3833 = ABC,

  • 3436 = 9 Story Media Group, etc.

ctvSkippablewhitelistbooleanNotruetrue/false
  • whitelist = true: Only the skippable content types listed in targetedValues are eligible for targeting.
  • whitelist = false: The skippable content types listed in targetedValues are excluded from targeting. All other skippable content types remain eligible.
ctvSkippabletargetedValuesinteger[]YesNone[2245]Skippable IDs (max 1 value)
audienceTargetingwhitelistbooleanNotruetrue/false

  • whitelist = true: Only the audience segments listed in segments are eligible for targeting.

  • whitelist = false: The audience segments listed in segments are excluded from targeting. All other audience segments remain eligible.

audienceTargetingsegmentsobject[]YesNoneSee Audience Segment Objectlist of audience segment definitions, Maximum 100 segments
tagIdwhitelistbooleanNotrueN/AThe default value is true. Only allowlist is supported.
When it is set to false, the API returns 400 BAD_REQUEST error, see Error Handling.
tagIdtargetedValuesstring[]YesN/A“tag-123”, “tag-456”Tag IDs (max 250,000 entries).
Tag ID values are not validated.
inboundDealIdwhitelistbooleanNotrueN/AThe default value is true. Only allowlist is supported.
When it is set to false, the API returns 400 BAD_REQUEST error, see Error Handling.
inboundDealIdtargetedValuesstring[]NoN/A“in-bound-deal-A”, “inbound-deal-B”Inbound Deal IDs (max 250,000 entries).
Inbound Deal ID values are not validated.

5.1 Audience Segment Object

PropertyTypeRequiredExampleDescription
segments.idstringYes"7007123"Audience segment ID
segments.namesstring[]Yes["Sports Fans"]Audience segment names, min one entry
segments.cpmdecimalYes1.25CPM value, max 2 decimal places
segments.dataProviderintegerYes11Data provider ID
segments.segmentTypestringNo-Segment classification
segments.dataTypestringNo-Audience data type

6. Error Handling

HTTP Status CodeDescriptionResponse Body
200 OKReturned when a deal is retrieved successfully.See Get a Deal Response Example
200 OKReturned when a deal is updated successfully.See Update a Deal Response Example
201 CreatedReturned when a deal is created successfully.See Create a Deal Response Example
400 Bad RequestThe request payload contains invalid field values.json { "message": "Invalid Data", "validationErrors": [ { "field": "eCpm", "messageKey": "DecimalMin.deal.eCpm", "message": "must be greater than or equal to 0.01" } ], "status": "400 BAD_REQUEST" }
400 Bad RequestThe request contains an unsupported targeting configuration. Setting the whitelist value to false is not supported for adFormat or channel.json { "message": "Invalid Data", "validationErrors": [ { "field": "targetings.adFormat.targetedValues", "messageKey": "BLACKLIST_VIOLATION.deal.targetings.adFormat.targetedValues", "message": "blacklisting is not supported for targeting type adFormat" }, { "field": "targetings.channel.targetedValues", "messageKey": "BLACKLIST_VIOLATION.deal.targetings.channel.targetedValues", "message": "blacklisting is not supported for targeting type channel" } ], "status": "400 BAD_REQUEST" }
401 UnauthorizedAccess token is missing or invalid.N/A
403 ForbiddenThe operation is not allowed based on token privileges.json { "message": "Forbidden", "status": "403 FORBIDDEN" }
404 Not FoundThe requested deal was not found.json { "message": "Deal with deal ID 998877 not found", "status": "404 NOT_FOUND" }
429 Too Many RequestsThe request exceeded the allowed rate limits. Reduce the request rate and retry later.json { "error": "rate_limit_exceeded", "message": "Rate limit exceeded. Limits: 50 req/sec, 500 req/min." }
5xx Server ErrorInternal server error. Retry the request. If the issue continues, contact your Account Manager for support.json { "message": "Internal Server Error", "status": "500 INTERNAL_SERVER_ERROR" }

Updated 7 days ago

Updated 7 days ago