How to authenticate your requests to the Verve Marketplace Deal API.
Create an Open Auction or Private Auction deal, with its targeting.
Change an existing deal's settings, status, invited DSPs and seats, or targeting.
Retrieve a single deal, or a paginated and searchable list of deals.
Every field you can send or receive, with filters, status and supported values.
HTTP status codes, response bodies and auction type validation errors.
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
500requests per minute and a maximum burst rate of50requests per second. Requests exceeding these limits return429 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 Auction | Private Auction | |
|---|---|---|
auctionType | OPEN_AUCTION (default) | PRIVATE_AUCTION |
| DSPs | One DSP in dspGroupId | One or more DSPs in privateAuction.invitedDspGroupIds |
| Seats | Optional, one seat in seatId | At least one seat per invited DSP in privateAuction.invitedSeatIds |
| Inbound Deal ID | Optional | Required before the deal can run |
externalDealId | Allowed | Not 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.
- Generate an access token with your
client IDandclient 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- Send the token in the
Authorizationheader 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
| Endpoint | Method | Path |
|---|---|---|
| Create a Deal | POST | /buyer/deals/v1/deals |
| Update a Deal | PUT | /buyer/deals/v1/deals/{id} |
| Get a Deal | GET | /buyer/deals/v1/deals/{id} |
| Get a Deal List | GET | /buyer/deals/v1/deals |
3.1 Base URL
https://marketplace-api-external.verve.com3.2 Create a Deal
POST https://marketplace-api-external.verve.com/buyer/deals/v1/deals3.2.1 Overview
Creates a new marketplace deal.
3.2.2 Request Body (Required)
For all supported fields, see Deal Object and Targeting Object.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Deal name. Maximum 255 characters. |
dspGroupId | integer | Yes, for Open Auction | ID of the DSP associated with the deal. |
auctionType | string | No | OPEN_AUCTION or PRIVATE_AUCTION. Default: OPEN_AUCTION. |
privateAuction | object | Yes, for Private Auction | Invited DSPs and seats. See Private Auction Object. |
3.2.3 Request Body Example
Note:
If
statusis 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
{ "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
{ "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
statusset toRUNNING. 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, andinboundDealIdare deleted only if your credentials have write access to them; otherwise they are retained. For Private Auction deals, omittinginboundDealIdreturns400 Bad Request.- Deal fields:
description,advertiserId,seatId,start,end,externalDealId, anddealFeePercentageare cleared.timezoneis reset toUTC,priceModeltoMIN_PRICE, andeCpmto0.01.- Retained:
adExperience(including each CTA individually),auctionType, and the invited DSPs and seats inprivateAuction.
3.3.2 Path Parameter
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Unique 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
{ "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
{ "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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Unique 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/deals3.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:
- Start with page-number = 0.
- Increase page-number by 1 for each subsequent request.
- Stop when
numberOfElementsis less thanpageSize, or when it is 0. Requesting a page after the last one returns an emptydealsarray withnumberOfElements= 0.
GET https://marketplace-api-external.verve.com/buyer/deals/v1/deals?page-number=0&page-size=100&search-term=5b2e7a103.5.3 Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page-number | integer | No | 0 | Page number to retrieve. Minimum: 0. |
page-size | integer | No | 100 | Number of records per page. Minimum: 1, maximum: 1000. |
search-term | string | No | - | 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
{ "data": { "deals": [ { "id": 1005690, "marketplaceDealId": "5b2e7a10-9c4f-4d1e-a3b8-0f6c2d9e1a77", "name": "My deal", "status": "RUNNING", "auctionType": "PRIVATE_AUCTION", "privateAuction": {4. Deal Object
| Field | Type | Status | Description |
|---|---|---|---|
id | integer | Optional | Read-only. Unique deal identifier. |
marketplaceDealId | string | Optional | Read-only. Marketplace deal ID. |
externalDealId | string | Optional | External deal ID. Maximum 256 characters, ^[a-zA-Z0-9+#,-]+$. Not allowed for Private Auction deals. |
auctionType | string | Optional | Supported values: OPEN_AUCTION, PRIVATE_AUCTION. Default: OPEN_AUCTION. Cannot be changed after the deal is created. PRIVATE_AUCTION is not available for DV360 deals. |
name | string | Required | Deal name. Maximum 255 characters. Angle brackets are not allowed. |
description | string | Optional | Deal description. Maximum 2500 characters. Angle brackets are not allowed. |
status | string | Optional | Supported 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. |
advertiserId | integer | Optional | Advertiser ID. |
advertiserName | string | Optional | Advertiser name. |
dspGroupId | integer | Required for Open Auction | ID 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. |
dspGroupName | string | Optional | Read-only. DSP name. |
seatId | integer | Optional | Seat ID. Not allowed for Private Auction deals; use privateAuction.invitedSeatIds. |
seatName | string | Optional | Read-only. Seat name. |
privateAuction | object | Required for Private Auction | Invited 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. | integer[] | Required for Private Auction | IDs of the invited DSPs. At least one. Each must be active. |
privateAuction. | integer[] | Required for Private Auction | IDs of the invited seats. At least one per invited DSP. Each must be active and belong to an invited DSP. |
privateAuction. | string[] | Optional | Read-only. Names of the invited DSPs. |
privateAuction. | string[] | Optional | Read-only. Names of the invited seats. |
priceModel | string | Optional | Supported values: MIN_PRICE, FIXED_PRICE. Default: MIN_PRICE. |
eCpm | decimal | Optional | Minimum 0.01, maximum 1000.00, up to 2 decimal places. Default: 0.01. |
timezone | string | Optional | Timezone. Default: UTC. |
start | string | Optional | Start date and time in yyyy-MM-dd HH:mm:ss format. Cannot be modified after the deal first reaches RUNNING status. |
end | string | Optional | End date and time in yyyy-MM-dd HH:mm:ss format. Cannot be modified after the deal first reaches RUNNING status. |
dealFeePercentage | decimal | Optional | Deal fee percentage. Minimum 0.0000, maximum 99.9999, up to 4 decimal places. |
5. Targeting Object
| Property | Type | Status | Default | Example | Notes / supported values |
|---|---|---|---|---|---|
adFormat. | boolean | Optional | true | N/A | The default value is true. When it is set to false, the API returns 400 Bad Request, see Error Handling. |
adFormat. | integer[] | Required | None | [51,52] | Ad Format IDs: 51 = Video, 52 = Banner, 59 = Native, 3941 = Rewarded Video, etc. |
deviceType. | boolean | Optional | true | true/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. |
deviceType. | integer[] | Required | None | [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. | boolean | Optional | true | true/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. |
adSize. | integer[] | Required | None | [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. | boolean | Optional | true | N/A | The default value is true. When it is set to false, the API returns 400 Bad Request, see Error Handling. |
channel. | integer[] | Required | None | [2161,2162] | Channel IDs: 2161 = Mobile In-App, 2162 = Mobile Web, 3936 = CTV, 3940 = Desktop Web, etc. |
supplyBundleDomain. | boolean | Optional | true | true/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. |
supplyBundleDomain. | string[] | Required | None | ["com.example.app","example.com"] | Bundle IDs or domains (max 250,000 entries). Invalid bundle/domain names are ignored. |
performanceVcr. | decimal | Required | None | 60.0 | Range: 40.0–90.0 (increments of 5), 1 decimal. Values outside the supported range or increment return 400 Bad Request, see Error Handling. |
performanceViewability. | decimal | Required | None | 70.0 | Range: 40.0–90.0 (increments of 5), 1 decimal. Values outside the supported range or increment return 400 Bad Request, see Error Handling. |
geoLocation | object | Optional | None | N/A | If geoLocation is specified, at least one of geoCountry, geoState, or geoCity must be provided. |
geoLocation. | boolean | Optional | true | true/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. | string | Required | None | "US" | Country code. Max 50 characters. |
geoLocation. | string | Required | None | "United States" | Country name. Max 200 characters. |
geoLocation. | boolean | Optional | true | true/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. | string | Required | None | "US-CA" | State code. Max 50 characters. |
geoLocation. | string | Required | None | "California" | State name. Max 200 characters. |
geoLocation. | boolean | Optional | true | true/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. | string | Required | None | "Los Angeles-California-US" | City code. Max 50 characters. |
geoLocation. | string | Required | None | "Los Angeles" | City name. Max 200 characters. |
geoLocation. | string | Optional | None | "5368361" | GeoNames identifier. |
ctvContentChannel. | boolean | Optional | true | true/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. |
ctvContentChannel. | integer[] | Required | None | [2505, 307] | CTV Content Channel IDs: 2505 = 1001.tv, 307 = 2048 World Cup, etc. |
ctvContentGenre. | boolean | Optional | true | true/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. |
ctvContentGenre. | integer[] | Required | None | [1033] | CTV Genre IDs: 1033 = Action & Adventure, 1034 = Animation, etc. |
ctvContentRating. | boolean | Optional | true | true/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. |
ctvContentRating. | integer[] | Required | None | [1097] | CTV Rating IDs: 1097 = TV-14, 1098 = Movie-G, etc. |
ctvContentLanguage. | boolean | Optional | true | true/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. |
ctvContentLanguage. | integer[] | Required | None | [1444] | CTV Language IDs: 1444 = Arabic, 1437 = Abkhazian, 1438 = Afar, etc. |
ctvContentLivestream. | boolean | Optional | true | true/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. |
ctvContentLivestream. | integer[] | Required | None | [258] | Livestream IDs (max 1 value): 258 = Livestream |
ctvContentNetwork. | boolean | Optional | true | true/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. |
ctvContentNetwork. | integer[] | Required | None | [3833] | Network IDs: 3833 = ABC, 3436 = 9 Story Media Group, etc. |
ctvSkippable. | boolean | Optional | true | true/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. |
ctvSkippable. | integer[] | Required | None | [2245] | Skippable IDs (max 1 value). |
audienceTargeting. | boolean | Optional | true | true/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. |
audienceTargeting. | object[] | Required | None | N/A | List of audience segment definitions. Maximum 100 segments. Each segment uses the segments.* properties below. |
audienceTargeting. | string | Required | None | "7007123" | Audience segment ID. |
audienceTargeting. | string[] | Required | None | ["Sports Fans"] | Audience segment names, min. one entry. |
audienceTargeting. | decimal | Required | None | 1.25 | CPM value, up to 2 decimal places. |
audienceTargeting. | integer | Required | None | 11 | Data provider ID. |
audienceTargeting. | string | Optional | None | N/A | Segment classification. |
audienceTargeting. | string | Optional | None | N/A | Audience data type. |
tagId. | boolean | Optional | true | N/A | The default value is true. Only allowlisting is supported. When it is set to false, the API returns 400 Bad Request, see Error Handling. |
tagId. | string[] | Required | N/A | "tag-123", "tag-456" | Tag IDs (max 250,000 entries). Tag ID values are not validated. |
inboundDealId. | boolean | Optional | true | N/A | The default value is true. Only allowlisting is supported. When it is set to false, the API returns 400 Bad Request, see Error Handling. |
inboundDealId. | string[] | Required for Private Auction | N/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 Code | Description | Response Body |
|---|---|---|
200 OK | The deal was retrieved or updated successfully. | See Update a Deal Response Example |
201 Created | The deal was created successfully. | See Create a Deal Response Example |
400 Bad Request | The request contains invalid field values. For auction type errors, see Auction Type Validation Errors. | See the 400 Bad Request (field value) example |
400 Bad Request | The 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 Unauthorized | The access token is missing or invalid. | N/A |
403 Forbidden | The operation is not allowed for this token. | See the 403 Forbidden example |
404 Not Found | The requested deal was not found. | See the 404 Not Found example |
429 Too Many Requests | The 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 Error | Internal 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"
}{
"message": "Invalid Data",
"validationErrors": [
{
"field": "targetings.adFormat.targetedValues",
"messageKey": "BLACKLIST_VIOLATION.deal.targetings.adFormat.targetedValues",
"message": "blacklisting is not supported for targeting type adFormat"
}
],
"status": "400 BAD_REQUEST"
}{
"message": "Forbidden",
"status": "403 FORBIDDEN"
}{
"message": "Deal with deal ID 998877 not found",
"status": "404 NOT_FOUND"
}{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Limits: 50 req/sec, 500 req/min."
}{
"message": "Internal Server Error",
"status": "500 INTERNAL_SERVER_ERROR"
}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.
| Cause | Field | Message Key |
|---|---|---|
| Auction type changed after creation | auctionType | api.deal.write.auctionType.update.forbidden |
| DV360 deal set to Private Auction | auctionType | api.deal.write.auctionType.invalid |
| Invited DSPs sent on an Open Auction deal | privateAuction.invitedDspGroupIds | api.deal.write.invitedDspGroupIds.invalid |
| Invited seats sent on an Open Auction deal | privateAuction.invitedSeatIds | api.deal.write.invitedSeatIds.invalid |
| Private Auction deal with no invited DSPs | privateAuction.invitedDspGroupIds | api.deal.write.invitedDspGroupIds.invalid |
| Private Auction deal with no invited seats | privateAuction.invitedSeatIds | api.deal.write.invitedSeatIds.invalid |
| An invited DSP has no invited seat | privateAuction.invitedSeatIds | api.deal.write.invitedSeatIds.invalid |
| Invited seat is unknown, inactive, or belongs to a DSP that is not invited | seatId | api.deal.write.seatId.notFound |
Private Auction deal sent with a single seatId | seatId | api.deal.write.seatId.notFound |
Private Auction deal sent with an externalDealId | externalDealId | api.deal.write.externalDealId.invalid |
| Private Auction deal left without any Inbound Deal ID | inboundDealIds | api.deal.targetSelection.inboundDealIds.required |
| Invited DSP is unknown or inactive | dspGroupId | api.deal.write.sdxDspGroupId.notFound |

