Create a deal
Create a deal with this in-depth tutorial using IQM's Inventory API.
About IQM deals
The Inventory API allows you to create and manage advertising deals. IQM offers two kinds of private deals:
- Private Marketplace (PMP) deals are a type of programmatic advertising arrangement that allows Advertisers to purchase ad inventory through a private, invitation-only auction.
- Programmatic Guaranteed (PG) deals are a direct negotiation between one publisher and one Advertiser that offer budget predictability and avoid auction volatility by ensuring a fixed amount of ad inventory at a pre-negotiated price.
More resources
- Inventory API guidelines
- Optimize your inventory tutorial
- Ad inventory and placements Help Center article
Before you begin
To create a deal, the following are required:
- An account on the IQM platform
- See Getting started section to create an account and request a Client ID and Client Secret
- A campaign, only for assigning a deal to an existing campaign
- For a PMP deal, see the Create a campaign quickstart guide
- A PG campaign can't be created without an active PG deal, so create the PG deal first and then use it in Create a PG campaign. You can assign more PG deals to the campaign afterwards.
Log in
POSTTo log in, send the Authorization: Basic header with your Base64-encoded Client ID and Client Secret, and send the request body as form data (application/x-www-form-urlencoded). The response contains an OAuth access token.
To find the Organization Workspace IDs that you have access to, use Get list of accessible Organizations.
For further information see OAuth token.
| Headers | |
|---|---|
Authorization string required | Basic followed by your Base64-encoded client_id:client_secret. See Sign up and authenticate. |
Content-Type string required | application/x-www-form-urlencoded. Send the request body as form data. |
| Request schema | |
|---|---|
grant_type string required | password for login. See OAuth Grant Types. |
username string required | User account email. |
password string required | User account password. |
- JSON
curl -i --location 'https://api.iqm.com/api/v3/ua/oauth/token' \
--header 'accept: application/json, text/plain, */*' \
--header 'Authorization: Basic <base64 of client_id:client_secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=user@iqm.com' \
--data-urlencode 'password=<your password>'
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
"refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIn0...",
"scope": "read write",
"token_type": "bearer",
"expires_in": 86399
}
More responses
{
"success": false,
"errorObjects": [
{
"error": "Bad Credentials or invalid grant type"
}
]
}
{
"error": "Client details are not provided."
}
Authentication
Use the following header parameters for all requests after logging in:
| Headers | |
|---|---|
Authorization string required | Bearer followed by the access_token from the login response. See Sign up and authenticate. |
X-IAA-OW-ID integer required | Organization Workspace ID header. |
Request exchange list
GETTo create a PG or PMP deal, an exchange must be provided. Use the master exchange endpoint to get a list of available exchanges.
| Query parameters | |
|---|---|
pageNo integer | Page number of retrieved data, default: 1. |
noOfEntries integer | Number of entries returned per page, default: 300. |
sortBy string | Sort the result set by specific field. For ascending use plus(+) sign and for descending use minus(-) sign, default: -id. |
searchField string | Search exchanges by name. |
ids string | Comma-separated exchange IDs to return first, ahead of the other exchanges. |
exchangeIds string | Comma-separated exchange IDs to return. Other exchanges are left out. |
exchangeIds array of integers | Filters for exchange IDs. |
Response properties
success boolean | Indicates the request was successful: true. | ||||||||||||||||
data object | Exchange list and record counts. | ||||||||||||||||
| |||||||||||||||||
data array of objects | Exchanges, sorted by ID in descending order by default. | |||||||
| ||||||||
id integer | Exchange ID. Pass it as exchangeId when you create a deal. |
name string | Exchange name. |
urlName string | Exchange URL name. |
totalRecords integer
filteredRecords integer
- JSON
{
"success": true,
"data": {
"data": [
{
"id": 96,
"name": "Pine Lake",
"urlName": "pinelake"
},
{
"id": 39,
"name": "Google DoubleClick",
"urlName": "adx"
},
{
"id": 11,
"name": "Smaato",
"urlName": "smaato"
}
],
"totalRecords": 30,
"filteredRecords": 30
}
}
Create a PG deal
POSTOnce an exchange id is selected, pass it in the exchangeId field to create a PG deal.
| Request schema | |
|---|---|
dealId string required | PG deal ID, up to 500 characters. |
dealName string required | PG deal name, up to 500 characters. |
exchangeId integer required | Exchange ID associated with PG deal. |
statusId integer required | Status ID of PG deal Active: 1 Inactive: 2 Only active deals can be assigned to a campaign. |
description string | Description or notes about the deal, up to 1,000 characters. |
paymentTypeId integer | Payment type ID Only Platform (2) is supported, and it is the default. |
Response properties
success boolean | Indicates the deal was created: true. | |||||
data object | Created deal details. | |||||
| ||||||
id integer | PG deal ID assigned by IQM. Use this ID, not dealId, when you assign the deal to a campaign. |
message string | Success message. |
- JSON
{
"dealId": "YT-Test-1234",
"dealName": "Test deal YT31",
"exchangeId": 11,
"statusId": 1,
"paymentTypeId": 2,
"description": "Test Deal"
}
{
"success": true,
"data": {
"id": 2681,
"message": "Deal Test deal YT31 created successfully"
}
}
More responses
{
"success": false,
"errorObjects": [
{
"error": "Given payment type is not supported"
}
]
}
Create a PMP deal
POSTOnce an exchange id is selected, pass it in the exchangeId field to create a PMP deal.
Consider creating a PMP inventory group if you plan to target or block the same group of PMP deals across multiple campaigns. See the Optimize your inventory tutorial for step-by-step instructions.
| Properties | |
|---|---|
dealId string required | PMP deal ID. |
dealName string required | PMP deal name. |
description string | PMP deal description. |
cpm number | PMP deal Cost Per Mille (CPM) value. |
dealCurationTypeId integer | Curation type ID. |
creativeTypes array of integers | Creative type IDs. |
exchangeId integer required | Exchange associated with PMP deal. |
assignToCustomers array of integers | Customer Organization Workspace IDs. Workspace organizations only; Advertiser organizations get a 422. |
active boolean required | Deal status, active (true) or inactive (false). |
Response properties
success boolean | Indicates the deal was created: true. | |||||
data object | Created deal details. | |||||
| ||||||
id integer | PMP deal ID assigned by IQM. Use this ID, not dealId, when you assign the deal to a campaign. |
message string | Success message. |
- JSON
{
"dealId": "DIewkFZALX1taoLjQg6Gge1dD6YvZYO4RChUKmOLk",
"dealName": "Deal test123",
"description": "test deal description",
"cpm": 10,
"creativeTypes": [
11,
13
],
"exchangeId": 39,
"active": true
}
{
"success": true,
"data": {
"id": 4161,
"message": "PMP Deal added successfully"
}
}
More responses
{
"success": false,
"errorObjects": [
{
"error": "Deal id can not be longer than 500 characters",
"field": "dealId"
}
]
}
{
"success": false,
"errorObjects": [
{
"error": "Invalid exchange id/s provided"
}
]
}
{
"success": false,
"errorObjects": [
{
"error": "server encountered an error !"
}
]
}
Assign deals to a campaign
PATCHPATCH
Deals can be assigned or removed to/from campaigns. PG deals may only be assigned to PG campaigns; and PMP deals may only be assigned to Advanced campaigns.
Both endpoints require an Advertiser organization. A request can't list the same campaign and deal pair in both an assign and a deassign operation.
| Request schema | |
|---|---|
operations array | Operations specifying the action, campaign IDs and PMP deal IDs. |
action string | Action to perform: assign or deassign. |
campaignIds array of integers | Campaign IDs to assign deals or remove deals from. |
pmpDealIds array of integers | PMP deal IDs to assign/remove to/from campaigns. |
pgDealIds array of integers | PG deal IDs to assign/remove to/from campaigns. |
Response properties
success boolean | Indicates deals were assigned successfully: true. |
data string | Success message. |
- JSON
{
"operations": [
{
"action": "assign",
"campaignIds": [
201,
203
],
"pmpDealIds": [
101,
102
]
},
{
"action": "deassign",
"campaignIds": [
202
],
"pmpDealIds": [
102
]
}
]
}
{
"success": true,
"data": "PMP deal campaign mappings updated successfully"
}
More responses
{
"success": false,
"errorObjects": [
{
"error": "User is not allowed to perform campaign mapping operation"
}
]
}
{
"success": false,
"errorObjects": [
{
"error": "PMP deal id/s is/are invalid or not accessible for logged-in user"
}
]
}
{
"success": true,
"data": "PG deal campaign mappings updated successfully"
}
{
"success": false,
"errorObjects": [
{
"error": "Provided PG deals are invalid"
}
]
}
Get list of deals associated with campaigns
GETGet a list of campaigns and their associated deal IDs by campaign type ID.
| Path parameter | |
|---|---|
campaignTypeId integer | Campaign type ID. Only 2 (PG) is supported. |
Response properties
success boolean | Indicates the request was successful: true. |
data object | Map of campaign ID (key, as a string) to an array of the PG deal IDs assigned to that campaign. Only PG campaigns (campaignTypeId 2) are supported. |
- JSON
{
"success": true,
"data": {
"625975": [
2678,
2679
],
"625976": [
2680
]
}
}
More responses
{
"success": false,
"errorObjects": [
{
"error": "Unsupported campaign type ID, PMP deals are not supported currently: [1]"
}
]
}