Verve Marketplace Deal API

1. Overview

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

Key features include:

  • RESTful HTTP endpoints for deal management.
  • Open Auction and Private Auction deals.
  • Inventory, geo, content, and audience targeting.
  • Rate limits of 500 requests per minute and a maximum burst rate of 50 requests per second. Requests exceeding these limits return 429 Too Many Requests, see the 429 error example.

Auction types

Every deal has an auction type, set in the auctionType field. The auction type determines whether the deal runs in a private auction or is open to any DSP. All endpoints support both auction types.

  • Open Auction (OPEN_AUCTION) is the default. The deal has one DSP and, optionally, one seat.
  • Private Auction (PRIVATE_AUCTION) lets you invite several DSPs and seats to the same deal. A deal ID from the publisher (the Inbound Deal ID) is required to run a Private Auction. When an impression carries one of the deal's Inbound Deal IDs, only the invited DSPs and seats can bid on it.
Open AuctionPrivate Auction
auctionTypeOPEN_AUCTION (default)PRIVATE_AUCTION
DSPsOne DSP in dspGroupIdOne or more DSPs in privateAuction.invitedDspGroupIds
SeatsOptional, one seat in seatIdAt least one seat per invited DSP in privateAuction.invitedSeatIds
Inbound Deal IDOptionalRequired before the deal can run
externalDealIdAllowedNot allowed
📘

Note:

DV360 deal workflows are supported. DV360 documentation will be published separately and linked from this page.

2. Authentication

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

  1. Generate an access token with your client ID and client secret:
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
  1. Send the token in the Authorization header of every request:
Authorization: Bearer <access_token>
🚧

Tokens expire after one hour.

To continue, generate a new access token with the same client credentials.

3. Endpoints

EndpointMethodPath
Create a DealPOST/buyer/deals/v1/deals
Update a DealPUT/buyer/deals/v1/deals/{id}
Get a DealGET/buyer/deals/v1/deals/{id}
Get a Deal ListGET/buyer/deals/v1/deals

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)

For all supported fields, see Deal Object and Targeting Object.

FieldTypeRequiredDescription
namestringYesDeal name. Maximum 255 characters.
dspGroupIdintegerYes, for Open AuctionID of the DSP associated with the deal.
auctionTypestringNoOPEN_AUCTION or PRIVATE_AUCTION. Default: OPEN_AUCTION.
privateAuctionobjectYes, for Private AuctionInvited DSPs and seats. See Private Auction Object.

3.2.3 Request Body Example

📘

Note:

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

The following example creates a Private Auction deal. For an Open Auction deal, omit auctionType and privateAuction and provide dspGroupId. See Auction types for the other differences.

Request Body Example

JSONField reference (4)
{  "auctionType": "PRIVATE_AUCTION",  "name": "My deal",  "description": "optional description",  "advertiserId": 4598,  "privateAuction": {    "invitedDspGroupIds": [9462255, 9462301],    "invitedSeatIds": [784525, 784530, 790112]  },  "timezone": "UTC",

3.2.4 Response Example

Returns the created deal object. For Open Auction deals, privateAuction is null. For error responses, see Error Handling.

201 Created

JSONField reference (4)
{  "id": 1005690,  "marketplaceDealId": "5b2e7a10-9c4f-4d1e-a3b8-0f6c2d9e1a77",  "auctionType": "PRIVATE_AUCTION",  "privateAuction": {    "invitedDspGroupIds": [9462255, 9462301],    "invitedDspGroupNames": ["A DSP name", "Another DSP name"],    "invitedSeatIds": [784525, 784530, 790112],    "invitedSeatNames": ["Seat A", "Seat B", "Seat C"]  },
📘

Note:

To activate a deal created with INITIAL status, call Update a Deal with status set to RUNNING. Deals in RUNNING status are 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. The request replaces the deal, so it must include every field and targeting group to be retained.

🚧

Fields omitted from the request are not retained.

  • Targeting: omitted targeting groups are deleted. Omitting targetings deletes all targeting. qualityTier, tagId, and inboundDealId are deleted only if your credentials have write access to them; otherwise they are retained. For Private Auction deals, omitting inboundDealId returns 400 Bad Request.
  • Deal fields: description, advertiserId, seatId, start, end, externalDealId, and dealFeePercentage are cleared. timezone is reset to UTC, priceModel to MIN_PRICE, and eCpm to 0.01.
  • Retained: adExperience (including each CTA individually), auctionType, and the invited DSPs and seats in privateAuction.

3.3.2 Path Parameter

ParameterTypeRequiredDescription
idintegerYesUnique deal identifier

3.3.3 Request Body

For all supported fields, see Deal Object and Targeting Object.

3.3.4 Request Body Example

The following example activates the deal from the Create a Deal example, changes eCpm to 7.0, and invites an additional seat. All other fields and targeting groups are included with their current values.

Request Body Example

JSONField reference (4)
{  "auctionType": "PRIVATE_AUCTION",  "status": "RUNNING",  "name": "My deal",  "description": "optional description",  "advertiserId": 4598,  "privateAuction": {    "invitedDspGroupIds": [9462255, 9462301],    "invitedSeatIds": [784525, 784530, 790112, 790115]  },

3.3.5 Response Example

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

200 OK

JSONField reference (4)
{  "id": 1005690,  "marketplaceDealId": "5b2e7a10-9c4f-4d1e-a3b8-0f6c2d9e1a77",  "auctionType": "PRIVATE_AUCTION",  "privateAuction": {    "invitedDspGroupIds": [9462255, 9462301],    "invitedDspGroupNames": ["A DSP name", "Another DSP name"],    "invitedSeatIds": [784525, 784530, 790112, 790115],    "invitedSeatNames": ["Seat A", "Seat B", "Seat C", "Seat D"]  },

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 with its current values, in the same format as the Update a Deal response. For error responses, see Error Handling.

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. Stop when numberOfElements is less than pageSize, or when it is 0. Requesting a page after the last one returns an empty deals array with numberOfElements = 0.
GET https://marketplace-api-external.verve.com/buyer/deals/v1/deals?page-number=0&page-size=100&search-term=5b2e7a10

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-Searches deal name, marketplaceDealId, externalDealId, buyer name, advertiser name, DSP name, and seat name. Case-insensitive; partial matches are supported. Omit to list all deals.

3.5.4 Response Example

200 OK

JSONField reference (4)
{  "data": {    "deals": [      {        "id": 1005690,        "marketplaceDealId": "5b2e7a10-9c4f-4d1e-a3b8-0f6c2d9e1a77",        "name": "My deal",        "status": "RUNNING",        "auctionType": "PRIVATE_AUCTION",        "privateAuction": {

4. Deal Object

Showing 24 of 24 fields
FieldTypeStatusDescription
idintegerOptionalRead-only. Unique deal identifier.
marketplaceDealIdstringOptionalRead-only. Marketplace deal ID.
externalDealIdstringOptionalExternal deal ID. Maximum 256 characters, ^[a-zA-Z0-9+#,-]+$. Not allowed for Private Auction deals.
auctionTypestringOptionalSupported values: OPEN_AUCTION, PRIVATE_AUCTION. Default: OPEN_AUCTION. Cannot be changed after the deal is created. PRIVATE_AUCTION is not available for DV360 deals.
namestringRequiredDeal name. Maximum 255 characters. Angle brackets are not allowed.
descriptionstringOptionalDeal description. Maximum 2500 characters. Angle brackets are not allowed.
statusstringOptionalSupported values: INITIAL, PAUSED, RUNNING. Default: INITIAL. A Private Auction deal is set to RUNNING only when it has at least one invited seat and one Inbound Deal ID. Otherwise, the request succeeds but the status does not change.
advertiserIdintegerOptionalAdvertiser ID.
advertiserNamestringOptionalAdvertiser name.
dspGroupIdintegerRequired for Open AuctionID of the DSP associated with the deal. Cannot be modified after the deal first reaches RUNNING status. For Private Auction deals, it must be one of the invited DSPs; if omitted, it is set to one of them.
dspGroupNamestringOptionalRead-only. DSP name.
seatIdintegerOptionalSeat ID. Not allowed for Private Auction deals; use privateAuction.invitedSeatIds.
seatNamestringOptionalRead-only. Seat name.
privateAuctionobjectRequired for Private AuctionInvited DSPs and seats. null for Open Auction deals; sending it on an Open Auction deal returns 400 Bad Request. In an update request, the lists provided replace the current lists. If privateAuction is omitted, the current invited DSPs and seats are retained.
privateAuction.invitedDspGroupIdsinteger[]Required for Private AuctionIDs of the invited DSPs. At least one. Each must be active.
privateAuction.invitedSeatIdsinteger[]Required for Private AuctionIDs of the invited seats. At least one per invited DSP. Each must be active and belong to an invited DSP.
privateAuction.invitedDspGroupNamesstring[]OptionalRead-only. Names of the invited DSPs.
privateAuction.invitedSeatNamesstring[]OptionalRead-only. Names of the invited seats.
priceModelstringOptionalSupported values: MIN_PRICE, FIXED_PRICE. Default: MIN_PRICE.
eCpmdecimalOptionalMinimum 0.01, maximum 1000.00, up to 2 decimal places. Default: 0.01.
timezonestringOptionalTimezone. Default: UTC.
startstringOptionalStart date and time in yyyy-MM-dd HH:mm:ss format. Cannot be modified after the deal first reaches RUNNING status.
endstringOptionalEnd date and time in yyyy-MM-dd HH:mm:ss format. Cannot be modified after the deal first reaches RUNNING status.
dealFeePercentagedecimalOptionalDeal fee percentage. Minimum 0.0000, maximum 99.9999, up to 4 decimal places.

5. Targeting Object

Showing 49 of 49 fields
PropertyTypeStatusDefaultExampleNotes / supported values
adFormat.whitelistbooleanOptionaltrueN/AThe default value is true. When it is set to false, the API returns 400 Bad Request, see Error Handling.
adFormat.targetedValuesinteger[]RequiredNone[51,52]Ad Format IDs: 51 = Video, 52 = Banner, 59 = Native, 3941 = Rewarded Video, etc.
deviceType.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
deviceType.targetedValuesinteger[]RequiredNone[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.
adSize.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
adSize.targetedValuesinteger[]RequiredNone[15,19]Ad Size IDs: 15 = 300 × 50, 19 = 320 × 50, 8 = 320 × 100, 5 = 250 × 250, 4 = 728 × 90, 3 = 120 × 600, 2 = 300 × 250, 31 = 336 × 280, etc.
channel.whitelistbooleanOptionaltrueN/AThe default value is true. When it is set to false, the API returns 400 Bad Request, see Error Handling.
channel.targetedValuesinteger[]RequiredNone[2161,2162]Channel IDs: 2161 = Mobile In-App, 2162 = Mobile Web, 3936 = CTV, 3940 = Desktop Web, etc.
supplyBundleDomain.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
supplyBundleDomain.targetedValuesstring[]RequiredNone["com.example.app","example.com"]Bundle IDs or domains (max 250,000 entries). Invalid bundle/domain names are ignored.
performanceVcr.kpiValuedecimalRequiredNone60.0Range: 40.0–90.0 (increments of 5), 1 decimal. Values outside the supported range or increment return 400 Bad Request, see Error Handling.
performanceViewability.kpiValuedecimalRequiredNone70.0Range: 40.0–90.0 (increments of 5), 1 decimal. Values outside the supported range or increment return 400 Bad Request, see Error Handling.
geoLocationobjectOptionalNoneN/AIf geoLocation is specified, at least one of geoCountry, geoState, or geoCity must be provided.
geoLocation.geoCountry.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.geoCountry.targetedValue.codestringRequiredNone"US"Country code. Max 50 characters.
geoLocation.geoCountry.targetedValue.namestringRequiredNone"United States"Country name. Max 200 characters.
geoLocation.geoState.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.geoState.targetedValue.codestringRequiredNone"US-CA"State code. Max 50 characters.
geoLocation.geoState.targetedValue.namestringRequiredNone"California"State name. Max 200 characters.
geoLocation.geoCity.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.geoCity.targetedValue.codestringRequiredNone"Los Angeles-California-US"City code. Max 50 characters.
geoLocation.geoCity.targetedValue.namestringRequiredNone"Los Angeles"City name. Max 200 characters.
geoLocation.geoCity.targetedValue.geoNameIdstringOptionalNone"5368361"GeoNames identifier.
ctvContentChannel.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvContentChannel.targetedValuesinteger[]RequiredNone[2505, 307]CTV Content Channel IDs: 2505 = 1001.tv, 307 = 2048 World Cup, etc.
ctvContentGenre.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvContentGenre.targetedValuesinteger[]RequiredNone[1033]CTV Genre IDs: 1033 = Action & Adventure, 1034 = Animation, etc.
ctvContentRating.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvContentRating.targetedValuesinteger[]RequiredNone[1097]CTV Rating IDs: 1097 = TV-14, 1098 = Movie-G, etc.
ctvContentLanguage.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvContentLanguage.targetedValuesinteger[]RequiredNone[1444]CTV Language IDs: 1444 = Arabic, 1437 = Abkhazian, 1438 = Afar, etc.
ctvContentLivestream.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvContentLivestream.targetedValuesinteger[]RequiredNone[258]Livestream IDs (max 1 value): 258 = Livestream
ctvContentNetwork.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvContentNetwork.targetedValuesinteger[]RequiredNone[3833]Network IDs: 3833 = ABC, 3436 = 9 Story Media Group, etc.
ctvSkippable.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
ctvSkippable.targetedValuesinteger[]RequiredNone[2245]Skippable IDs (max 1 value).
audienceTargeting.whitelistbooleanOptionaltruetrue/falsewhitelist = 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.
audienceTargeting.segmentsobject[]RequiredNoneN/AList of audience segment definitions. Maximum 100 segments. Each segment uses the segments.* properties below.
audienceTargeting.segments.idstringRequiredNone"7007123"Audience segment ID.
audienceTargeting.segments.namesstring[]RequiredNone["Sports Fans"]Audience segment names, min. one entry.
audienceTargeting.segments.cpmdecimalRequiredNone1.25CPM value, up to 2 decimal places.
audienceTargeting.segments.dataProviderintegerRequiredNone11Data provider ID.
audienceTargeting.segments.segmentTypestringOptionalNoneN/ASegment classification.
audienceTargeting.segments.dataTypestringOptionalNoneN/AAudience data type.
tagId.whitelistbooleanOptionaltrueN/AThe default value is true. Only allowlisting is supported. When it is set to false, the API returns 400 Bad Request, see Error Handling.
tagId.targetedValuesstring[]RequiredN/A"tag-123", "tag-456"Tag IDs (max 250,000 entries). Tag ID values are not validated.
inboundDealId.whitelistbooleanOptionaltrueN/AThe default value is true. Only allowlisting is supported. When it is set to false, the API returns 400 Bad Request, see Error Handling.
inboundDealId.targetedValuesstring[]Required for Private AuctionN/A"pub-deal-001", "pub-deal-002"Inbound Deal IDs.
Open Auction: Optional. Maximum 250,000 entries. Values are not validated.
Private Auction: Required before the deal can run. 1 to 250,000 entries, no blank values. Required in every update request; omitting it returns 400 Bad Request. The last value cannot be removed.

6. Error Handling

HTTP Status CodeDescriptionResponse Body
200 OKThe deal was retrieved or updated successfully.See Update a Deal Response Example
201 CreatedThe deal was created successfully.See Create a Deal Response Example
400 Bad RequestThe request contains invalid field values. For auction type errors, see Auction Type Validation Errors.See the 400 Bad Request (field value) example
400 Bad RequestThe request contains an unsupported targeting configuration. whitelist = false is not supported for adFormat, channel, tagId, or inboundDealId.See the 400 Bad Request (targeting) example
401 UnauthorizedThe access token is missing or invalid.N/A
403 ForbiddenThe operation is not allowed for this token.See the 403 Forbidden example
404 Not FoundThe requested deal was not found.See the 404 Not Found example
429 Too Many RequestsThe request exceeded the rate limits. Reduce the request rate and retry later. The response has no Retry-After header, and its body uses a different format from other errors.See the 429 Too Many Requests example
5xx Server ErrorInternal server error. Retry the request. If the issue persists, contact your Account Manager.See the 5xx Server Error example

Response body examples

{
  "message": "Invalid Data",
  "validationErrors": [
    {
      "field": "eCpm",
      "messageKey": "DecimalMin.deal.eCpm",
      "message": "must be greater than or equal to 0.01"
    }
  ],
  "status": "400 BAD_REQUEST"
}

6.1 Auction Type Validation Errors

Auction type validation errors return 400 Bad Request in the same format as the field value example above. Use field and messageKey to identify the cause.

CauseFieldMessage Key
Auction type changed after creationauctionTypeapi.deal.write.auctionType.update.forbidden
DV360 deal set to Private AuctionauctionTypeapi.deal.write.auctionType.invalid
Invited DSPs sent on an Open Auction dealprivateAuction.invitedDspGroupIdsapi.deal.write.invitedDspGroupIds.invalid
Invited seats sent on an Open Auction dealprivateAuction.invitedSeatIdsapi.deal.write.invitedSeatIds.invalid
Private Auction deal with no invited DSPsprivateAuction.invitedDspGroupIdsapi.deal.write.invitedDspGroupIds.invalid
Private Auction deal with no invited seatsprivateAuction.invitedSeatIdsapi.deal.write.invitedSeatIds.invalid
An invited DSP has no invited seatprivateAuction.invitedSeatIdsapi.deal.write.invitedSeatIds.invalid
Invited seat is unknown, inactive, or belongs to a DSP that is not invitedseatIdapi.deal.write.seatId.notFound
Private Auction deal sent with a single seatIdseatIdapi.deal.write.seatId.notFound
Private Auction deal sent with an externalDealIdexternalDealIdapi.deal.write.externalDealId.invalid
Private Auction deal left without any Inbound Deal IDinboundDealIdsapi.deal.targetSelection.inboundDealIds.required
Invited DSP is unknown or inactivedspGroupIdapi.deal.write.sdxDspGroupId.notFound