Contact support
    • Maestro
    • Developers
    • Use the APIs

    Manage deals with the API

    Table of Contents

    Overview Swagger UI Authentication Required information Authentication workflow Step 1: Request the access token from Auth0 Step 2: Request the user token Step 3: Use the user token in API requests Work with Maestro Auction Package API Endpoint Data minimization Limits Request and response headers Reference lookups Retrieve resources: GET / Available resources Parameters Example for extendedSearch with limit Example of search for specified partners Hyperlocal targeting Create deal: POST /deals General fields Pricing fields Pricing examples Guaranteed price Targeting fields Delivery capping Frequency capping Publisher budget allocations Example of deal creation with targeting criteria Example deal targeting a DSP Hyperlocal targeting fields Example of deal creation with hyperlocal targeting criteria Hyperlocal targeting and geotargeting combined Retrieve list of deals GET /deals Item limitation Filter reference Example of deal list retrieval response Hyperlocal targeting Retrieve deal information: GET /deals/ Example of deal information retrieval Hyperlocal targeting Edit deal: PUT /deals Example of deal editing Hyperlocal targeting Delete deal: DELETE /deals/{id} Domain lists: POST and DELETE /deals/{id}/domainlists Add a domain list: POST /deals/{id}/domainlists Remove a domain list: DELETE /deals/{id}/domainlists Count breakdown: GET /deals/countBreakdown Validation rules Deal reporting

    Overview

    With the Auction Package API, developers can automate the creation, editing, updating, and pausing of deals. For complete field-level reference, see the live Swagger documentation. This help page focuses on surface coverage, behavioral rules, and integration guidance.

    Swagger UI

    You can use the Swagger UI to explore and test the API endpoints interactively.

    Authentication

    The authentication workflow involves Equativ’s authentication provider (Auth0) and Equativ’s own Maestro user API.

    Required information

    To authenticate and use the Maestro API, you need the following credentials, which will be provided by your Equativ contact:

    • the client_id and client_secret
    • the username and password used to access the Maestro platform

    Treat any received credentials as confidential and don't share them with third parties.

     

    Authentication workflow

    Step 1: Request the access token from Auth0

    Request the access token from Equativ’s authentication provider Auth0:  

    curl --request POST \
  --url 'https://´smartadserver.eu.auth0.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=http://auth0.com/oauth/grant-type/password-realm' \
  --data 'realm=Username-Password-Authentication' \
  --data 'audience=api.demand.smartadserver.com' \
  --data-urlencode 'username={username}' \
  --data-urlencode 'password={password}' \
  --data 'client_id={client id}' \
  --data 'client_secret={client secret}'

    In the response, you will receive the access token, which has a time to live of 10 hours (36000 seconds):  

    {
"access_token":"<access token>",
"expires_in": 36000,
"token_type": "Bearer"
}

    Step 2: Request the user token

    With the access token obtained in Step 1, you must now request the user token, which you will use in all future API requests:   

    curl --request GET \
--url https://demand-api.eqtv.io/authorize \
--header 'Authorization: Bearer <access token>'

    The response body will only contain the user token which has a time to live of 10 hours.

    Step 3: Use the user token in API requests

    Use the user token obtained in Step 2 in the Authorization header of all your API requests:

    curl --request GET \
--url https://demand-api.eqtv.io/deals \
--header 'Authorization: Bearer <user token>'

    Work with Maestro Auction Package API

    Endpoint

    The endpoint for the Maestro Auction Package API is:

    https://demand-api.eqtv.io/

    Data minimization

    To ensure performance, security, and privacy, make sure you retrieve only the data your application requires.

    Limits

    • Within a 5-minute window, you can authenticate a maximum of 10 times. Any additional authentication attempts during this period will be unsuccessful. 
    • By default, the API allows up to 500 requests per day for deal updates and 15 requests per day for deal creations. Exceeding these limits will result in an error message. These limits reset daily.

    Request and response headers

    Header Direction Description
    Location POST response The URL of the newly created resource
    X-HistoryId POST response The history tracking ID for the created deal
    X-CopyOfDealId POST request The new deal created as a copy of the specified deal ID
    X-Pagination-Total-Count GET /deals response The total number of items across all pages
    Link GET /deals response The RFC 5988 pagination links (first, next, prev, last)

    Reference lookups

    The following reference tables describe enum values used in deal objects.

    Deal types (typeId)

    Value Name
    1 PrivateAuction
    2 DirectDeal
    3 GuaranteedDeal

    Deal priorities (priorityId)

    Value Description
    1 Low
    2 Medium
    3 High

    Deal criticalities (dealCriticalityId)

    Value Description
    1 Standard
    2 High

    Capping time frames (timeFrameId)

    Document the available values (for example, hourly, daily, weekly, lifetime—get exact values from the codebase or Swagger doc).

    Impression types (impressionTypeIds)

    Value Name
    0 Display
    1 Native
    2 In-Stream
    3 Out-Stream
    4 Audio
    5 Unknown

    Platforms (platformIds)

    Value Name
    1 Desktop
    2 Tablet
    3 Smartphone
    4 TV
    5 SetTopBox
    6 GameConsole

    Pricing models (pricingModel)

    Value Name
    0 Variable floor
    1 Fixed price
    2 Custom floor
    3 Guaranteed price

    Sort filters (sortBy)

    Document available sortBy values for the GET /deals endpoint.

    DSP caller restrictions: the following lookups are blocked for DSP callers: identity providers, third-party providers, and domain lists. These resources return a 403 Forbidden error when called with DSP credentials.

     

    Retrieve resources: GET /<RESOURCE>

    Before creating a deal, you need to aggregate the identifiers of each of the filters you want to apply, such as publisher ID, country ID, buyer ID, or partner. The path to retrieve these identifiers is the same for all available resources.

    Available resources

    • buyers
    • partners
    • dsps
    • countries
    • publishers
    • impressionTypes
    • inventoryTypes
    • cities
    • states
    • regions
    • dmas
    • videoPlacementTypes
    • adBreakTypes
    • videoPlayerSizeBuckets
    • audienceSegmentProviders
    • semanticSegmentProviders
    • audienceSegments
    • semanticSegments
    • platforms

    Parameters

    The following query parameters can be used to filter the results:

    Query parameter Definition
    Ids A comma-separated list of identifiers to fetch for the specified resource
    extendedSearch The string to search in the resource’s name
    limit An integer to limit the results to the n first items
    offset An integer to offset the results by an increment of n items

    Example for extendedSearch with limit

    The following example requests the items containing "London" in the countries resource with a limit of three items to be returned: 

    https://demand-api.eqtv.io/cities?extendedSearch=London&limit=3

    The following example shows the corresponding response:

    [
	{
		"name": "London",
		"countryId": 78,
		"regionId": 164,
		"stateId": 2531,
		"isArchived": false,
		"extendedName": "London - Greater London - United Kingdom",
		"id": 71284
	},
	{
		"name": "London",
		"countryId": 93,
		"regionId": 249,
		"stateId": 2124,
		"isArchived": false,
		"extendedName": "London - Ontario - Canada",
		"id": 12226
	},
	{
		"name": "London",
		"countryId": 152,
		"regionId": 128,
		"stateId": 2192,
		"isArchived": false,
		"extendedName": "London - Ohio - United States",
		"id": 5946
	}
]

    Example of search for specified partners

    The following example requests the partner IDs 76 and 75:

    https://demand-api.eqtv.io/partners?ids=76,75

    The following example shows the corresponding response:

    [
	{
		"name": "Google DV360",
		"isMultiBuyerDealForbidden": false,
		"isArchived": false,
		"id": 76
	},
	{
		"name": "The Trade Desk",
		"isMultiBuyerDealForbidden": false,
		"isArchived": false,
		"id": 75
	}
]

    Hyperlocal targeting

    For more information about hyperlocal targeting, see Hyperlocal targeting fields.

    Create deal: POST /deals

    The POST /deals method creates a deal.

    General fields

    You must specify at least one buyerId or dspId to create or edit a deal. partnerIds are deprecated and no longer supported.

     
    Field name Type Necessity Definition Example
    beginDate endDate datetime ISO 8601 mandatory The deal’s start and end dates. A value of null for both fields (see example) indicates that the deal is always on (no start or end date) "beginDate": null, "endDate": null,
    buyerIds  array of int (id) mandatory (if no dspIds) The buyer seat IDs allowed to bid on the deal. Setting both buyerIds and dspIds isn't allowed. Resource: GET /buyers "buyerIds": [3548], "dspIds": []
    dspIds array of int (id) mandatory (if no buyerIds) The DSP IDs allowed to bid on the deal. Setting both dspIds and buyerIds isn't allowed. Resource: GET /dsps "dspIds": [75], "buyerIds": []
    expirationDate datetime ISO 8601 optional The deal's expiration date "2026-06-29T21:59:59+00:00"
    expirationDateUtc datetime ISO 8601 read-only The expiration date in UTC (returned in GET responses) "2026-06-29T21:59:59Z"
    callerDealIds array of string optional The caller-side deal IDs ["261828702428"]
    currency string (currency symbol) mandatory The deal currency "currency": "EUR"
    isActive boolean mandatory A field indicating if the deal is active (true) or paused (false) "isActive": true
    isDisabledByRegulator boolean read-only A field indicating if a regulator has disabled the deal. "isDisabledByRegulator": false
    isParentDeal boolean read-only A field indicating if the deal is a parent deal "isParentDeal": false
    name string mandatory The deal name "name": "This is the deal name"
    spoTargetingIds array of int optional The SPO target IDs "spoTargetingIds": [1, 2]
    identityProviderId integer optional The identity provider ID. Required for frequency capping. "identityProviderId": 42
    thirdPartyProviderCosts array of object optional Third-party provider cost configurations. "thirdPartyProviderCosts": [{"providerId": 5, "costRate": 0.10}]

    The partnerIds field has been deprecated and removed from the API. Using partnerIds in POST /deals or PUT /deals requests will return an error. Pre-existing deals remain fully operational, but partnerIds will no longer appear in any API response.

     

    Some DSPs don't support multiple-buyer deal targeting. If you attempt to create a deal targeting one of these DSPs, the API will return the following error: 
    { "message": "Your deal cannot target DSPs that do not support multiple-buyer targeting: {dspId}" } 
    Contact your Equativ representative to check which DSPs are compatible with multi-buyer targeting.

     

    Pricing fields

    Field name Type Necessity Definition
    CompanyVendorCostRate

    number 

    (2 decimals)

    		 optional The company vendor cost rate, also known as curator margin. This field should be used when creating variable floor deals. The CompanyVendorCostRate must be expressed as a percentage of the sold price, for example, CompanyVendorCostRate = 0.15 expresses a 15% margin.  For more information about curator margin, see Create deals.
    managementVendorCostCpm number (2 decimals) optional A management vendor cost expressed as a CPM value.
    managementVendorCostRate number (2 decimals) optional A management vendor cost rate.
    minCompanyVendorCost

    number 

    (2 decimals)

    		 optional The minimum company vendor cost, also known as curator margin. This field should be used when creating Custom floor and Fixed price deals. The minCompanyVendorCost must be expressed as an absolute value, for example, minCompanyVendorCost = 4 expresses a 4$ margin. For more information about curator margin, see Create deals.
    price

    number 

    (2 decimals)

    		 mandatory

    The buyer side price: 

    • Variable floor: 
      • Using publisher floor: 0
      • Else MediaPrice
    • Fixed price: fixed price of the deal
    • Custom floor: floor price of the deal
    pricingModel integer mandatory

    The pricing model: 

    • 0: Variable floor
    • 1: Fixed price
    • 2: Custom floor
    • 3: Guaranteed price

    Pricing examples

    Example Snippet

    Variable floor with floor price

    • Price:  4
    • CompanyVendorCostRate: 0
    		 "pricingModel": 0, "price": 4, "companyVendorCostRate": 0

    Variable floor with publisher floor

    • Price:  4
    • CompanyVendorCostRate: 15%
    		 "pricingModel": 0, "price": 0, "companyVendorCostRate": 0.15

    Custom floor

    • Price: 8
    • minCompanyVendorCost: 3
    		 "pricingModel": 2, "price": 8, "minCompanyVendorCost": 3

    Fixed price

    • Price: 10
    • minCompanyVendorCost: 3
    		 "pricingModel": 1, "price": 10, "minCompanyVendorCost": 3

    Guaranteed price 

    Guaranteed price deals have the following constraints:

    • Single buyer required: exactly one buyerId must be specified.
    • Buyer eligibility: the buyer must be eligible for guaranteed deals (check with your Equativ contact).
    • Format restrictions: only Display, In-Stream, and Out-Stream impression types are supported.
    • Date immutability rules:
      • Pre-flight (before beginDate): beginDate and endDate can be changed.
      • In-flight (between beginDate and endDate): beginDate cannot be changed; endDate can only be extended.
      • Post-flight (after endDate): dates cannot be changed.

    Targeting fields 

    At least one targeting criterion must be applied to create or edit a deal.

     
    Field name Type Definition Resource/Value Example
    apiCompliance boolean The compliancy with the IAB’s VPAID or OMSDK measurement specifications "isVpaidCompliant": boolean "isOmSdkCompliant": boolean "apiCompliance": {    "isVpaidCompliant": false,    "isOmSdkCompliant": false     }
    audienceSegmentsTargeting string

    Audience segments, provided by the AudienceSegmentProviders

    • comma (“,”) as an OR operator
    • semicolon(“;”) as an AND operator
    • “NOT“ as an exclusion operator
    		 GET /AudienceSegmentProviders GET /AudienceSegments "audienceSegmentsTargeting": "102590"
    cityIds array of int/string The city IDs GET /cities "cityIds": [    "448013",    "14352" ], "cityIds": [    448013,    14352 ]
    countryCodes array of codes The country codes, specified as per ISO 3166 GET /countries "countryCodes": [         "FRA"     ]
    creativeSizes array of strings The sets of creative heights and widths GET /CreativeBannerSizes "creativeSizes": [   "300*250",   "320*50",   "300*600",   "728*90", ]
    ctvOttIds array of int The CTV and OTT targeting IDs GET /ctvOtt "ctvOttIds": [1, 4, 7]
    ctvCategoryIds array of int The CTV category targeting IDs GET /ctvCategories

    "ctvCategoryIds": [12, 45]
    ctvChannelIds array of int The CTV channel targeting IDs GET /ctvChannels

    "ctvChannelIds": [101, 204]
    ctvDistributorIds array of int The CTV distributor targeting IDs GET /ctvDistributors

    "ctvDistributorIds": [3, 8]
    ctvNetworkIds array of int The CTV network targeting IDs GET /ctvNetworks

    "ctvNetworkIds": [56, 89]
    dmaIds array of int The DMA IDs (USA only) GET /DMAs "dmaIds": [   "644",   "821" ]
    impressionTypeIds array of int The different types of the impression: Display, Native, In-Stream, and Out-stream GET /impressiontypes "impressionTypeIds": [         1     ]
    inventoryTypeIds array of int The inventory types, indicating the environments where the ad can be displayed: "Web", "WebMobile", or "MobileApp" GET /inventorytypes "inventoryTypeIds": [         0     ]
    isCTV boolean The targeting of connected TV inventory “isCTV”:boolean "isCTV": false,
    platformIds array of int The platform, such as "Desktop", "Tablet", "Smartphone" GET /platforms "platformIds": [    1 ]
    publishers/networks array of int The list of publishers/networks GET /publishers "networkIds": [         1,         13,         50     ]
    regionIds array of int The region IDs GET /regions "regionIds": [   "239",    "88" ]
    semanticSegmentsTargeting string

    Semantic contextual segments

    • comma ( “,”) as an OR operator
    • semicolon, (“;”) as an AND operator
    • and “NOT “ as an exclusion operator

    The example targets: 

    • Segment 7822 OR
    • Segment 8630 AND
    • Segment 12486 OR
    • Segment 7825 excluded
    		 GET /SemanticSegmentProviders GET /SemanticSegments "semanticSegmentsTargeting": "7822,8630;12486;not 7825"
    stateIds array of int The state IDs GET /states "stateIds": [   "1749",    "2144" ]
    videoAdBreakTypeIds array of int The video ad break type IDs for in-stream video GET /videoadbreaktypes "videoAdBreakTypeIds": [   "3" ]
    videoCompletionTargetingPercentage integer The video completion target rate (formula: completely viewed video ads/started video ads  Value from 0 to 100 (int) "videoCompletionTargetingPercentage": 75
    videoPlacementTypeIds array of int The placement type IDs for video formats GET /videoplacementtypes  "videoPlacementTypeIds": [   "1" ]
    videoPlayerSizeDimension integer The minimum video player size At least one of the two values must be specified (width and/or height) "minHeight": int "minWidth": int "videoPlayerSizeDimension": {     "minWidth": 1152,     "minHeight": 648     }
    viewabilityTargetingPercentage integer The viewability target rate (formula: viewable impression/impressions) Value from 0 to 100 (int) "viewabilityTargetingPercentage": 50

    Delivery capping

    Delivery capping controls the volume of impressions or spend for a deal.

    Field Type Definition
    overallCapUnits integer The maximum number of impressions
    overallCapCents integer The maximum total spend (in cents)
    dailyCapUnits integer The maximum daily impressions
    dailyCapCents integer The maximum daily spend (in cents)
    pacingMode string Delivery pacing mode: Even or Asap

    Frequency capping

    Frequency capping limits how many times a user sees the deal's ads.

    Field Type Definition
    timeFrameId integer The capping time frame (see Reference lookups)
    impressions integer The maximum impressions per user per time frame

    Prerequisite: An identityProviderId must be set on the deal, and the identity provider must support frequency capping. Without this, frequency capping settings are ignored.

    Publisher budget allocations

    When delivery capping is set, you can allocate budgets per publisher:

    Field Type Definition
    publisherId integer The publisher ID
    shareAllocation number The percentage share of the total budget
    adjustedTarget number The adjusted delivery target
    softCapped boolean A field indicating if the cap is soft

    Constraint: beginDate and endDate are required when delivery capping (budgetIds) is configured.

    Example of deal creation with targeting criteria

    {
	"isActive": true,
	"name": "Fake API Deal",
	"pricingModel": 1,
	"price": 5,
	"minCompanyVendorCost": 2,
	"currency": "GBP",
	"buyerIds": [
		3548,
		3541
	],
	"dspIds": [],
	"salesPersonUserId": 277,
	"beginDate": null,
	"endDate": "2023-01-23T23:59:59Z",
	"platformIds": [
		1
	],
	"audienceSegmentsTargeting": "102590",
	"semanticSegmentsTargeting": "7822,8630;12486;not 7825",
	"countryCodes": [
		"FRA"
	],
	"networkIds": [
		1,
		13,
		50
	],
	"impressionTypeIds": [
		0
	],
	"inventoryTypeIds": [
		0
	],
	"cityIds": [],
	"stateIds": [],
	"regionIds": [],
	"dmaIds": [],
	"viewabilityTargetingPercentage": 50,
	"videoCompletionTargetingPercentage": 50,
	"ctrTargetingPercentage": 0,
	"videoPlacementTypeIds": [],
	"videoAdBreakTypeIds": [],
	"countryCodesPostalCodes": [],
	"videoPlayerSizeBucketIds": [],
	"apiCompliance": {
		"isVpaidCompliant": false,
		"isOmSdkCompliant": false
	},
	"isCTV": false,
	"videoPlayerSizeDimension": {
		"minHeight": null,
		"minWidth": null
	},
	"creativeSizes": []
}

    Example deal targeting a DSP

    {
 "isActive": true,
 "name": "Fake API Deal - DSP Targeting",
 "pricingModel": 1,
 "price": 5,
 "minCompanyVendorCost": 2,
 "currency": "GBP",
 "buyerIds": [],
 "dspIds": [75],
 "salesPersonUserId": 277,
 "beginDate": null,
 "endDate": "2026-06-30T23:59:59Z",
 "platformIds": [1],
 "audienceSegmentsTargeting": "",
 "semanticSegmentsTargeting": "",
 "countryCodes": ["FRA"],
 "networkIds": [1, 13, 50],
 "impressionTypeIds": [0],
 "inventoryTypeIds": [0],
 "cityIds": [],
 "stateIds": [],
 "regionIds": [],
 "dmaIds": [],
 "viewabilityTargetingPercentage": 50,
 "videoCompletionTargetingPercentage": 0,
 "ctrTargetingPercentage": 0,
 "videoPlacementTypeIds": [],
 "videoAdBreakTypeIds": [],
 "countryCodesPostalCodes": [],
 "videoPlayerSizeBucketIds": [],
 "apiCompliance": {
 "isVpaidCompliant": false,
 "isOmSdkCompliant": false
 },
 "isCTV": false,
 "videoPlayerSizeDimension": {
 "minHeight": null,
 "minWidth": null
 },
 "creativeSizes": []
}

    Hyperlocal targeting fields 

    Hyperlocal targeting is an advanced form of geotargeting, using precise coordinates and a radius.

    Field name Type Definition Example
    coordinates object   The coordinates, each consisting of a name, latitude, longitude and radius. "coordinates": [
        {
          "name": "Loc 1",
          "latitude": 0.6435,
          "longitude": 45.0,
          "radius": 500
        }
    ]
    hyperLocalTargeting object    The hyperlocal targeting, used to target geolocations with high precision, based on longitude, latitude, and radius. "hyperLocalTargeting": {
        "precision": 1,
        "coordinates": [
         {
           "name": "Loc 1",
           "latitude": 0.6435,
           "longitude": 45.0,
           "radius": 500
         }
      ]
    }
    latitude double The latitude value of the coordinate. Value must be between -90 and 90. Values must be in decimal degrees with a dot (“.”) used as separator, for example, 41.40338 "latitude": 0.6435
    longitude double   The longitude value of the coordinate. Value must be between -180 and 180. Values must be in decimal degrees with a dot (“.”) used as separator, for example, 41.40338 "longitude": 45.0
    name string   The name of the coordinate. This value is optional and will be generated automatically, if not provided. "name": "Eiffel Tower"
    precision int

    Specifies if the hyperlocal targeting is based on GPS coordinates or IP addresses:

    • 1: based on both GPS coordinates and IP addresses
    • 2: based on GPS coordinates only
    		 "precision": 1
    radius int  The distance in meters around the specified longitude and latitude "radius": 500

    Example of deal creation with hyperlocal targeting criteria

    The following example shows a request with hyperlocal parameters, highlighted in green.

    {
	"isActive": true,
	"name": "Test HTL",
	"pricingModel": 0,
	"price": 0.34,
	"companyVendorCostRate": null,
	"currency": "EUR",
	"buyerIds": [
		117556
	],
	"dspIds": [],
	"beginDate": null,
	"endDate": null,
	"isDspSyncEnabled": false,
	"ctvOttIds": [],
	"ctvCategoryIds": [],
	"ctvChannelIds": [],
	"ctvDistributorIds": [],
	"ctvNetworkIds": [],
	"platformIds": [],
	"templateIds": [],
	"audienceSegmentsTargeting": "",
	"semanticSegmentsTargeting": "",
	"domainCategorySegmentsTargeting": "",
	"countryCodes": ["FRA"],
	"networkIds": [],
	"impressionTypeIds": [],
	"inventoryTypeIds": [
		1
	],
	"cityIds": [],
	"stateIds": [],
	"regionIds": [],
	"dmaIds": [],
	"videoPlacementTypeIds": [],
	"videoAdBreakTypeIds": [],
	"countryCodesPostalCodes": [],
	"videoPlayerSizeBucketIds": [],
	"apiCompliance": {
		"isVpaidCompliant": false,
		"isOmSdkCompliant": false
	},
	"isRewardedVideo": null,
	"isCTV": false,
	"videoPlayerSizeDimension": {},
	"skippable": null,
	"creativeSizes": [],
	"childrenDealIds": [],
	"contentGenreNames": null,
	"contentCategoryNames": null,
	"contentContextIds": null,
	"contentIds": null,
	"contentLanguageIso6391Alpha2Codes": null,
	"contentChannelNames": null,
	"contentNetworkNames": null,
	"videoMaxAdDurationIds": [],
	"scoNodeBucketIds": [],
	"domains": null,
	"domainListId": null,
	"hyperLocalTargeting": {
		"precision": 1,
		"coordinates": [
			{
				"name": "Loc 1",
				"latitude": 0.6435,
				"longitude": 45.0,
				"radius": 500
			},
			{
				"name": "Loc 2",
				"latitude": 20.0003,
				"longitude": -40.5,
				"radius": 5000
			},
			{
				"name": "(0, 45) - 1500 m",
				"latitude": 0.0,
				"longitude": 45.0,
				"radius": 1500
			},
			{
				"name": "Loc 3",
				"latitude": 50.32455,
				"longitude": 45.0,
				"radius": 500
			}
		]
	}
}

    Hyperlocal targeting and geotargeting combined

    If you set a hyperlocal radius that spans multiple countries, you might inadvertently target regions beyond your intended area. By integrating additional geotargeting parameters, such as country or city boundaries, you can ensure more precise targeting and avoid cross-border issues.

    Retrieve list of deals GET /deals

    The GET /deals method retrieves the entire list of deals created by the company.

    Item limitation

    The response is limited to 100 items. To get more items, make another request using the offset parameter.

    The following example requests the 100 to 200 items of the deal list:

    GET https://demand-api.eqtv.io/deals?offset=100

    Use the limit parameter to reduce the number of results.

    The following example requests a maximum of two deals:

    GET https://demand-api.eqtv.io/deals?limit=2

    The API returns X-Pagination-Total-Count (total number of items) and RFC 5988 Link headers for pagination. Note that the limit parameter is silently clamped to a maximum of 100.

     

    Filter reference

    Parameter Type Description
    createdOrModifiedSince datetime The timestamp used to filter deals created or modified after this date. The API interprets this value in UTC.
    isArchived boolean The flag used to filter deals by their archived status.
    isSoonExpired boolean The flag used to filter for deals that are expiring soon.
    isParentDeal boolean The flag used to filter for parent deals only.
    sortBy string The field used to sort the results (see Reference lookups).
    sortAsc boolean The sort direction (true = ascending).
    metricsBeginDate datetime The start date for metric calculations.
    metricsEndDate datetime The end date for metric calculations.
    buyerIds comma-separated int The list of buyer IDs used to filter the results.
    dspIds comma-separated int The list of DSP IDs used to filter the results.
    partnerIds comma-separated int The list of partner IDs used to filter the results.
    formatIds comma-separated int The list of format IDs used to filter the results.
    platformIds comma-separated int The list of platform IDs used to filter the results.

    Example of deal list retrieval response

    The following example shows a deal list response containing two deals.

    [
	{
		"semanticSegmentsDataCost": 0.0,
		"audienceSegmentsDataCost": 0.0,
		"updatedAt": "2022-06-22T13:01:00Z",
		"isArchived": false,
		"isEditable": true,
		"name": "AP_US_Mobile_InApp_Smadex",
		"createdAt": "2022-06-15T12:45:00Z",
		"isActive": true,
		"typeId": 1,
		"dealId": "841126260456",
		"pricingModel": 0,
		"customVendorCost": 0.0,
		"currency": "USD",
		"isExclusive": false,
		"isDealPlus": true,
		"dealCriticalityId": 2,
		"throttlingRate": 0.99,
		"platformIds": [
			3
		],
		"countryCodes": [
			"USA"
		],
		"keywordTargeting": "",
		],
		"priorityId": 3,
		"semanticSegmentsTargeting": "",
		"audienceSegmentsTargeting": "",
		"inventoryTypeIds": [
			1,
			2
		],
		"impressionTypeIds": [
			0
		],
		"price": 1.224,
		"domainListId": 9812,
		"apiCompliance": {
			"isOmSdkCompliant": false,
			"isVpaidCompliant": false
		},
		"salesPersonUserId": 146,
		"keywordIdsTargeting": "",
		"id": 4728209
	},
	{
		"semanticSegmentsDataCost": 0.0,
		"audienceSegmentsDataCost": 0.96,
		"viewabilityDataCost": 0.0,
		"updatedAt": "2022-06-21T03:01:00Z",
		"isArchived": false,
		"isEditable": true,
		"name": "InfoPro - Security & Antivirus",
		"createdAt": "2022-05-30T10:31:00Z",
		"isActive": true,
		"typeId": 1,
		"dealId": "761583477993",
		"pricingModel": 0,
		"customVendorCost": 0.0,
		"companyVendorCostRate": 0.2,
		"currency": "EUR",
		"isExclusive": false,
		"isDealPlus": true,
		"dealCriticalityId": 2,
		"throttlingRate": 0.99,
		"countryCodes": [
			"FRA"
		],
		"keywordTargeting": "",
		],
		"priorityId": 3,
		"semanticSegmentsTargeting": "",
		"audienceSegmentsTargeting": "26249",
		"inventoryTypeIds": [
			0,
			1
		],
		"impressionTypeIds": [
			0
		],
		"viewabilityTargetingPercentage": 70.0,
		"price": 0.333,
		"apiCompliance": {
			"isOmSdkCompliant": false,
			"isVpaidCompliant": false
		},
		"salesPersonUserId": 107,
		"keywordIdsTargeting": "",
		"id": 3960526
	}
]

    GET responses return a DemandDeal shape that includes computed cost fields not present in write requests: semanticSegmentsDataCost, audienceSegmentsDataCost, viewabilityDataCost, videoCompletionDataCost. These fields are read-only.

     

    Hyperlocal targeting 

    For more information about hyperlocal targeting, see Hyperlocal targeting fields.

    Retrieve deal information: GET /deals/<Id>

    The GET /deals/<Id> method retrieves the information about a specific deal, where <Id> is a deal identifier set by Equativ, to be taken from the deal list response received using the GET /deals method. This identifier isn't to be confused with the "DealId" identifying the deal across SSPs and DSPs.

    Example of deal information retrieval

    The following example retrieves information about the specified deal ID 1327581:

    GET https://demand-api.eqtv.io/deals/1327581

    The response contains:

    • dealId 129531443390: the ID used to identify the deal across SSPs and DSPs
    • id 1327581: the deal ID set by Equativ, taken from the deal list response received using the GET /deals method
    {
   "semanticSegmentsDataCost": 0.0,
   "audienceSegmentsDataCost": 0.0,
   "updatedAt": "2023-01-23T11:02:00Z",
   "isArchived": false,
   "isEditable": true,
   "name": "AP_Mexico_Display_CTR+2_domains_Dynadmic",
   "createdAt": "2021-06-18T15:34:00Z",
   "isActive": true,
   "typeId": 1,
   "dealId": "129531443390",
   "pricingModel": 0,
   "customVendorCost": 0.0,
   "currency": "USD",
   "isExclusive": false,
   "isDealPlus": true,
   "dealCriticalityId": 2,
   "throttlingRate": 0.8,
   "countryCodes": [
       "MEX"
   ],
   "keywordTargeting": "",
   ],
   "dspIds": [],
   "priorityId": 3,
   "semanticSegmentsTargeting": "",
   "audienceSegmentsTargeting": "",
   "price": 0.0,
   "domainListId": 3404,
   "apiCompliance": {
       "isOmSdkCompliant": false,
       "isVpaidCompliant": false
   },
   "keywordIdsTargeting": "",
   "id": 1327581
}

    Hyperlocal targeting

    For more information about hyperlocal targeting, see Hyperlocal targeting fields.

    Edit deal: PUT /deals

    The PUT /deals updates a specified deal, where <Id> is a deal identifier set by Equativ, to be taken from the deal list response received using the GET /deals method. This identifier isn't to be confused with the DealId identifying the deal across SSPs and DSPs.

    ⚠️ Warning: when updating a deal using the PUT method, you must include all relevant fields in the request body. Any fields that aren't explicitly included in the update request will be reset to their default values. If you omit any field, it won't retain its current value but will instead revert to the system's default state.

    Example of deal editing

    The following example edits the specified deal ID 1327581:

    PUT https://demand-api.eqtv.io/deals/1327581

    The request body contains:

    • dealId 129531443390: the ID used to identify the deal across SSPs and DSPs
    • id 1327581: the deal ID set by Equativ, taken from the deal list response received using the GET /deals method
    {
    "semanticSegmentsDataCost": 0.0,
    "audienceSegmentsDataCost": 0.0,
    "updatedAt": "2023-01-23T11:02:00Z",
    "isArchived": false,
    "isEditable": true,
    "name": "AP_Mexico_Display_CTR+2_domains_Dynadmic",
    "createdAt": "2021-06-18T15:34:00Z",
    "isActive": true,
    "typeId": 1,
    "dealId": "129531443390",
    "pricingModel": 0,
    "customVendorCost": 0.0,
    "currency": "USD",
    "isExclusive": false,
    "isDealPlus": true,
    "dealCriticalityId": 2,
    "throttlingRate": 0.8,
    "countryCodes": [
        "MEX"
    ],
    "keywordTargeting": "",
	"dspIds": [75],
    "priorityId": 3,
    "semanticSegmentsTargeting": "",
    "audienceSegmentsTargeting": "",
    "price": 0.0,
    "domainListId": 3404,
    "apiCompliance": {
        "isOmSdkCompliant": false,
        "isVpaidCompliant": false
    },
    "keywordIdsTargeting": "",
    "id": 1327581
}

    Even for deals originally created with partnerIds, any PUT request must now use dspIds. Using partnerIds in a PUT request will result in an error.

     

    Hyperlocal targeting 

    For more information about hyperlocal targeting, see Hyperlocal targeting fields.

    Delete deal: DELETE /deals/{id}

    The DELETE method removes a specified deal.

    DELETE https://demand-api.eqtv.io/deals/{id}

    Where {id} is the deal identifier set by Equativ, taken from the deal list response received using the GET /deals method. This identifier is not to be confused with the "DealId" identifying the deal across SSPs and DSPs.

    Domain lists: POST and DELETE /deals/{id}/domainlists

    Add a domain list: POST /deals/{id}/domainlists

    Associates a domain list with a deal.

    POST https://demand-api.eqtv.io/deals/{id}/domainlists

    Request body:
```json
{
  "domainListId": 1234
}

    Remove a domain list: DELETE /deals/{id}/domainlists 

    Removes the domain list association from a deal.

    DELETE https://demand-api.eqtv.io/deals/{id}/domainlists

    DSP restriction: Domain list endpoints aren't available for DSP callers.

     

    Count breakdown: GET /deals/countBreakdown 

    Returns a breakdown of deal counts by status.

    GET https://demand-api.eqtv.io/deals/countBreakdown

    Validation rules

    Immutability

    • currency and pricingModel cannot be changed after deal creation.
    • isDspSyncEnabled cannot be reverted to false once set to true.

    Geotargeting exclusivity

    • Only one geo targeting type can be active at a time (countries, regions, cities, states, DMAs, or postal codes).
    • hyperLocalTargeting requires at least one other geo field (e.g., countryCodes) to be set.

    Guaranteed price deal constraints

    • Dates follow phase-based immutability rules (see Guaranteed Price section).
    • Only Display, In-Stream, and Out-Stream formats are allowed.
    • Exactly one eligible buyer is required.

    Budget constraint

    • beginDate and endDate are required when budgetIds are set.

    Frequency capping prerequisite

    • identityProviderId must be set and the provider must support frequency capping.

    Deal reporting 

    For more information about deal reporting, see Manage reports with the API.

    auction package api maestro auction package api manage deals api create deals api update deals api hyperlocal targeting api authentication programmatic deal automation

    RELATED ARTICLES