Skip to main content

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​

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​

POST

To 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.
Request sample
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>'
Response 200
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
"refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIn0...",
"scope": "read write",
"token_type": "bearer",
"expires_in": 86399
}
More responses
Response 401
{
"success": false,
"errorObjects": [
{
"error": "Bad Credentials or invalid grant type"
}
]
}
Response 403
{
"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​

GET

To 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 object properties
data
array of objects
Exchanges, sorted by ID in descending order by default.
data array object properties
id
integer
Exchange ID. Pass it as exchangeId when you create a deal.
name
string
Exchange name.
urlName
string
Exchange URL name.
totalRecords
integer
Total number of exchanges.
filteredRecords
integer
Number of exchanges that match the request filters.
Response 200
{
"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​

POST

Once 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.
data object properties
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.
Request sample
{
"dealId": "YT-Test-1234",
"dealName": "Test deal YT31",
"exchangeId": 11,
"statusId": 1,
"paymentTypeId": 2,
"description": "Test Deal"
}
Response 201
{
"success": true,
"data": {
"id": 2681,
"message": "Deal Test deal YT31 created successfully"
}
}
More responses
Response 422
{
"success": false,
"errorObjects": [
{
"error": "Given payment type is not supported"
}
]
}

Create a PMP deal​

POST

Once an exchange id is selected, pass it in the exchangeId field to create a PMP deal.

tip

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.
data object properties
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.
Request sample
{
"dealId": "DIewkFZALX1taoLjQg6Gge1dD6YvZYO4RChUKmOLk",
"dealName": "Deal test123",
"description": "test deal description",
"cpm": 10,
"creativeTypes": [
11,
13
],
"exchangeId": 39,
"active": true
}
Response 201
{
"success": true,
"data": {
"id": 4161,
"message": "PMP Deal added successfully"
}
}
More responses
Response 400
{
"success": false,
"errorObjects": [
{
"error": "Deal id can not be longer than 500 characters",
"field": "dealId"
}
]
}
Response 422
{
"success": false,
"errorObjects": [
{
"error": "Invalid exchange id/s provided"
}
]
}
Response 500
{
"success": false,
"errorObjects": [
{
"error": "server encountered an error !"
}
]
}

Assign deals to a campaign​

PATCH
PATCH

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.
Request sample
{
"operations": [
{
"action": "assign",
"campaignIds": [
201,
203
],
"pmpDealIds": [
101,
102
]
},
{
"action": "deassign",
"campaignIds": [
202
],
"pmpDealIds": [
102
]
}
]
}
Response 200
{
"success": true,
"data": "PMP deal campaign mappings updated successfully"
}
More responses
Response 403
{
"success": false,
"errorObjects": [
{
"error": "User is not allowed to perform campaign mapping operation"
}
]
}
Response 422
{
"success": false,
"errorObjects": [
{
"error": "PMP deal id/s is/are invalid or not accessible for logged-in user"
}
]
}
Response 200 (PG deals)
{
"success": true,
"data": "PG deal campaign mappings updated successfully"
}
Response 422 (PG deals)
{
"success": false,
"errorObjects": [
{
"error": "Provided PG deals are invalid"
}
]
}

Get list of deals associated with campaigns​

GET

Get 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.
Response 200
{
"success": true,
"data": {
"625975": [
2678,
2679
],
"625976": [
2680
]
}
}
More responses
Response 422
{
"success": false,
"errorObjects": [
{
"error": "Unsupported campaign type ID, PMP deals are not supported currently: [1]"
}
]
}
Have a question?
Was this page helpful?