Skip to main content

Create a conversion

Create a conversion with this in-depth tutorial using IQM's API.

The following endpoints are used to create a conversion and assign it to a campaign:

POST
POST
POST

About IQM conversions​

IQM uses conversions as a tool to track user traffic for your campaigns.

The IQM platform supports three types of conversions:

  • Pixel conversions are client-side tracking and they feature advanced settings for fine-tuned optimization.
  • Postback conversions use server-to-server tracking, sending conversion data directly from your server to IQM without relying on browser-based JavaScript or cookies.
  • Universal Pixel conversions are client-side and use a single JavaScript snippet that can track multiple conversion events across your site without deploying separate per-page pixels.

More resources​

Before you begin​

To create a conversion, 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 tutorial covers 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

Authentication​

Use the following header parameters for all requests after logging in:

Headers
Authentication
string required		Authentication bearer token
See Sign up and authenticate
X-IAA-OW-ID
integer required		Organization Workspace ID Header

Step 1: Log in​

POST

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

For further information see OAuth token.

Headers
Authentication
string required		Authentication bearer token. See Sign up and authenticate
Request schema
grant_type
string required		password for login
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 <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
{
   "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

Create a Pixel type conversion. Refer to the Request schema table below for supported and required properties.

Request schema
statusId
integer		Status ID.
Supported values
1Active
2Pending
name
string required		Name for Pixel conversion
attributionId
string required		Attribution type ID
Supported values
1Hybrid
2Click based
3View based
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
Supported values
1Image Pixel
2Javascript Pixel
pixelConversionScript
string		Pixel conversion script
conversionSetting
object required		Advanced conversion settings
conversionSetting object properties
conversionDuration
object required		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 		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​

POST

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

Conversions can be assigned, updated, or removed from a campaign only before the campaign is running.

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
    ]
  }
}
Have a question?
Ask the community
Was this page helpful?