Skip to main content

Create a Conversion

IQM’s REST API enables you to interact with most of our platform's applications.

The following endpoints will be used to create a Conversion and assign it to a Campaign:

POST /api/v3/ua/login
POST /api/v3/conversion/pixel/add
PATCH /api/v3/conversion/assign-to/campaign

About IQM Conversions​

IQM uses Conversions as a tool to track user traffic for your Campaigns.

The IQM platform supports two types of Conversions:

  • Pixel Conversions are client-side tracking and they feature advanced settings for fine-tuned optimization.
  • Postback Conversions are server-side.

Learn more about Conversions with our Help Center articles.

Before You Begin​

To upload Matched Audience, the following are required:

  1. An Account On the IQM platform
    • See Getting Started section to create an account and request a Client ID and Client Secret
  2. A Draft Campaign

Create a Conversion Using the IQM API​

This Quickstart Guide will cover how to create a Conversion and assign it to a Campaign.

The minimum requirements to perform this task are: logging in with authentication credentials, creating a Conversion, and assigning it to a Campaign. Once these steps are accomplished, more can be learned about IQM's API through the Guidelines pages.

  1. Log In
    • Optional if you have already logged in and have a token
  2. Create a Conversion
  3. Assign Conversion to a Campaign

Step 1: Log In​

POST /api/v3/ua/login

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), which is a unique identifier for each Organization. This ID will be used for any further API communications.

For further information see the complete Login API Documentation.

Headers
Authentication
string required		Authentication bearer token. See Authentication Guide
X-IAA-HOST
string required		Workspace URL
Request Schema
grantType
string required		OAuth Grant Types
email
string required		User account email
password
string required		User account password
Request Sample
{
   "grantType": "password",
   "email": "pratik.t+ihp@iqm.com",
   "password": "123456"
}
Response 200
{
   "success": true,
   "data":
   {
      "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
      "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
      "scope": "read write",
      "token_type": "bearer",
      "expires_in": 35999,
      "owId": 200001
   }
}
More Responses
Response 400
{
   "success": false,
   "data":
   {
      "status": "On Hold",
      "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
      "supportEmail": "support@iqm.com"
   },
   "errorObjects":
   [
      {
         "error": "User is not allowed to access provided customer",
         "reason": "User is not associated with any active organization."
      }
   ]
}
Response 403
{
   "success": false,
   "errorObjects":
   [
      {
         "error": "User doesn't exist or user is not allowed to provided workspace."
      }
   ]
}

Step 2: Create a Pixel Conversion​

POST /api/v3/conversion/pixel/add

Create a pixel type Conversion. Refer to the Request Schema table below for supported and required properties.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
statusId
integer		Status ID
name
string required		Name for Pixel Conversion
attributionId
string		Attribution Type ID
customFields
string		Allows user to pass additional data along with Conversion details, which can be used for more detailed Insights
financialMetrics
string		Allows user to pass additional financial data along with Conversion details, which can then be used to calculate ROAs
piggybackData
object		Piggyback data details
piggybackData object properties
url
string		Additional URL that can be added to a pixel Conversion to send Conversion information to a third-party platform
type
integer		Piggyback Type ID
pixelConversionScript
string		Pixel Conversion script
conversionSetting
object required		Advanced Conversion settings
conversionSetting object properties
conversionDuration
object optional		Determines the length of time after a user clicks or views (or both: hybrid) an ad that a Conversion can be attributed to that ad
conversionDuration object properties
view
integer		View-based attribution gives credit to an ad that a user saw, but did not necessarily interact with, before making a Conversion
Post view interval, days: [1...30]
click
integer		Click-based attribution assigns credit for a Conversion to the last ad that a user clicked on before making a purchase or taking an action
Post click interval, days: [7...60]
repeatConversion
object required		Allows for multiple Conversions from the same user to be tracked and attributed to the same ad or Campaign
repeatConversion object properties
count
integer required		Counts all Conversions per user [0] or just 1 Conversion per user [1]
frequency
integer required		Counts 1 Conversion per user for specified number based on selected unit
unit
string required		Selected unit of Conversion frequency
crossModelling
boolean optional		Machine learning technique used to attribute Conversion to ads that may not have received direct clicks or views from the same device

Response Properties
id
integer		Conversion ID
name
string		Conversion name
postbackPartnerName
string		Postback partner name
status
string		Conversion status
type
string		Conversion type
created
integer		Unix epoch creation date, in milliseconds
totalConversions
integer		Total Conversions count
owID
integer		Organization Workspace ID
createdByUowId
integer		Created by User Organization Workspace ID
modifiedByUowId
integer		Modified by User Organization Workspace ID
uuid
integer		Universally Unique Identifier
pixelConversionScript
string		Pixel Conversion script
attributedConversion
integer		The number of Conversions that are attributed to a specific Campaign based on the Attribution model
attributedViewThroughConversion
integer		The number of Conversions that occurred after a user viewed an ad but did not click on it
attributedClickThroughConversion
integer		The number of Conversions that occurred after a user clicked on an ad
pixelFinancialMetric
string		Pixel financial metric
postbackPartnerLogoUrl
string		Postback partner logo URL
Request Sample
{
    "name": "PixelConversion",
    "attributionId": "1",
    "customFields": [
        "field_1",
        "field_2",
        "field_3"
    ],
    "financialMetrics": "field_4",
    "piggybackData": {
        "url": "http://piggybackdata.com/url",
        "type": 1
    },
    "conversionSetting": {
        "conversionDuration": {
            "view": 10,
            "click": 10
        },
        "repeatConversion": {
            "count": 1,
            "frequency": 1,
            "unit": "Day"
        },
        "crossModelling": true
    }
}
Response 200
{
    "success": true,
    "data": {
        "id": 3213,
        "name": "PixelConversion",
        "postbackPartnerName": null,
        "status": "Pending",
        "type": "Pixel",
        "created": 1687459918,
        "totalConversions": 0,
        "owId": 202017,
        "createdByUowId": 108658,
        "modifiedByUowId": 108658,
        "uuid": "a574ca49cc244c3bb3089491a11aae43",
        "attributedConversions": 0,
        "attributedViewThroughConversions": 0,
        "attributedClickThroughConversions": 0,
        "pixelFinancialMetric": "name",
        "postbackPartnerLogoURL": null,
        "pixelConversionScript": "<script src='https://pxl.stage.iqm.com/i/pixel/8f3165d0-b714-440e-bc1d-621127fa5fad?cv={CONVERSION_VALUE}' async></script>",
        "partnerUrl": null
    }
}

Step 3: Assign a Conversion to a Campaign​

PATCH /api/v3/conversion/assign-to/campaign

Assign a Conversion to a Campaign while validating Conversion IDs and Campaign IDs.

Pass the Conversion id created in Step 2 in the conversionIdList array along with the Campaign ID in the addCampaignsList array to assign the created Conversion to the desired Campaign.

info

The Campaign must be in "draft" status to assign a Conversion to it. Once a Campaign has been run, new Conversions cannot be assigned to it.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Query Parameters
assignConversionToCampaign
string optional		Map containing details list of Campaign IDs which need to be added/removed
Request Schema
conversionIdList
array of integers		Conversion IDs to assign
addCampaignsList
array of integers		Campaign IDs to assign Conversions to
removeCampaignsList
array of integers		Campaign IDs to remove assigned Conversions from
Response Properties
conversionIdsList
integer		Conversion IDs assigned to Campaigns
validAddCampaignIdsList
array of integers		Validated Campaign IDs to assign a Conversion to
invalidAddCampaignIdsList
array of integers		Invalid Campaign IDs to assign a Conversion to
validRemoveCampaignIdsList
array of integers		Validated Campaign IDs to remove a Conversion from
invalidRemoveCampaignIdsList
array of integers		Invalid Campaign IDs to remove a Conversion from
Request Sample
{
  "conversionIdList": [
    3925
  ],
  "addCampaignsList": [
    25396,
    256374,
    234567
  ],
  "removeCampaignsList": [
    256321,
    256432,
    256433
  ]
}
Response 200
{
  "success": true,
  "data": {
    "conversionIdsList": 3925,
    "validAddCampaignIdsList": [
      253396,
      256374
    ],
    "invalidAddCampaignIdsList": [
      234567
    ],
    "validRemoveCampaignIdsList": [
      256321,
      256432
    ],
    "invalidRemoveCampaignIdsList": [
      256433
    ]
  }
}