Reports API

Overview

The Reports API allows you to create and schedule custom Reports to generate insights and inform current and future Campaign optimization.

Metrics and dimensions can be selected to customize Reports. Metrics are quantitative values (number, percentage, dollar amount) measuring some Campaign's attribute. Dimensions are those attributes: the chosen element (e.g. demographics, Creatives, technologies) to be subjected to a metric.

Reports can be scheduled to a specified delivery frequency, and further fine-tuned to aggregate data or daily Reports.

info

There must be at least one active Campaign before a Report can be created/executed.

See the quickstart guides on Creating a Campaign, then Creating a Report and Scheduling a Report.

Learn more about Reports with our Help Center articles.

Authentication

Use the following header parameters for all requests:

Headers
`Authentication` string required	Authentication bearer token See Authentication Guide
`X-IAA-OW-ID` integer required	Organization Worskpace ID Header

Get Reports Details

This section covers the various methods and endpoints for getting lists and details of Reports.

Get a List of Reports

GET /api/v3/ra/reports/list
POST /api/v3/ra/reports/list

Get a list of Reports.

GET Query Parameters

`customerIds` string	Filters by comma separated customer IDs Passing `all` gets all eligible customer's Report, default: `all`
`sortBy` string	Sorts by ascending (`+`) or descending (`-`) Supported values: `id`, `name`, `startDate`, `modifyDate` Default: `-modifyDate`
`searchField` string	Filters by searched keyword
`limit` integer	Maximum number of entries returned, default: `20`
`pageNo` integer	Page number for the data, default: `1`

POST Request Schema

`customerIds` string	Filters by comma separated customer IDs Passing `all` gets all eligible customer's Report, default: `all`
`sortBy` string	Sorts by ascending (`+`) or descending (`-`) Supported values: `id`, `>name`, `startDate`, `modifyDate` Default: `-modifyDate`
`searchField` string	Filters by searched keyword
`noOfEntries` integer	Maximum number of entries returned, default: `20`
`pageNo` integer	Page number for the data, default: `1`

JSON
TypeScript

Request Sample
{
  "customerIds": "123,234,345",
  "pageNo": 1,
  "noOfEntries": 30,
  "sortBy": "+id",
  "searchField": "search field"
}

{
  "success": true,
  "data": {
    "data": [
      {
        "id": 1,
        "reportName": "Campaign by Gender by Device type",
        "startDate": 1650177200,
        "endDate": 1666938296,
        "dimensions": "[{\"filter\":\"campaign\",\"value\":[123,234,345,456]},{\"filter\":\"gender\",\"value\":[10200002]},{\"filter\":\"device_type\",\"value\":[20300001,20300003]}]",
        "customerIds": null,
        "customerDetails": null,
        "timezoneId": 11,
        "reportSchedulingEventDetails": {
          "eventId": 29,
          "deliveryFrequency": 3,
          "fileType": 2,
          "subscriberEmails": [
            "demoUser1@gmail.com",
            "demoUser2@iqm.com"
          ],
          "eventEndDate": 1671148799999,
          "deliveryDay": "Friday"
        }
      },
      {
        "id": 2,
        "reportName": "Campaigns by Zip Codes with filters",
        "startDate": 1660521600,
        "endDate": 1668470399,
        "dimensions": "[{\"filter\": \"campaign\"}, {\"value\": [123, 234, 345, 456], \"filter\": \"zip5\"}]",
        "customerIds": null,
        "customerDetails": null,
        "timezoneId": 12,
        "reportSchedulingEventDetails": {}
      },
      {
        "id": 3,
        "reportName": "Creatives by Income Ranges and Operating System with filters",
        "startDate": 1660521600,
        "endDate": 1668470399,
        "timezoneId": 11,
        "dimensions": "[{\"filter\": \"creative\"}, {\"value\": [10300002, 10300003], \"filter\": \"income_group\"}, {\"value\": [20200001, 20200002, 20200003], \"filter\": \"os\"}]",
        "customerIds": [
            200,
            201
        ],
        "customerDetails": [
            {
                "owId": 200,
                "organizationName": "Test Organization",
                "organizationLogo": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/organization-profile/200/1637314301025.png",
                "statusId": 1,
                "status": "Active",
                "supportEmail": "demoSupport@gmail.com",
                "timezone": 29
            }
        ],
        "reportSchedulingEventDetails": {}
      }
    ],
    "totalRecords": 3,
    "filteredRecords": 3
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          data: {
            id: number;
            reportName: string;
            startDate: number;
            endDate: number;
            dimensions: string;
            customerIds: number[];
            customerDetails: {
              owId: number;
              organizationName: string;
              organizationLogo: string;
              statusId: number;
              status: string;
              supportEmail: string;
              timezone: number
            }[];
            timezoneId: number;
            reportSchedulingEventDetails: {
              eventId: number;
              deliveryFrequency: number;
              fileType: number;
              subscriberEmails: string[];
              eventEndDate: number;
              deliveryDay: string;
            }
          }[];
          totalRecords: number;
          filteredRecords: number;
        }
      }
    };
  };
};

function getReportList(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ra/reports/list',
    params: {
      query?: {
        customerIds?: `string`,
        sortBy?: `string`,
        searchField?: `string`,
        limit?: `number`,
        pageNo?: `number`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

/* or */

function fetchReportList(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ra/reports/list',
    requestBody: {
      content: {
        "application/json": {
          searchBy?: `array of strings`,
          owId?: `number`,
          customerIds?: `string`,
          uowId?: `number`,
          pagination?: `string`,
          pageNo?: `number`,
          noOfEntries?: `number`,
          sortBy?: `string`,
          searchField?: `string`,
          order?: [ "asc" | "desc" ],
          offset?: `number`
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get Report by ID

GET /api/v3/ra/report/{reportId}

Get Report data by Report ID.

Path Parameters
`reportId` integer	Report ID

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "id": 123,
    "reportName": "Campaign by Gender by Device type",
    "startDate": 1650177000,
    "endDate": 1666938000,
    "dimensions": "[{\"filter\":\"campaign\"},{\"filter\":\"gender\",\"value\":[10200002]},{\"filter\":\"device_type\",\"value\":[20300001,20300003]}]",
    "columns": [
      "gender",
      "deviceType",
      "campaignId",
      "campaignName",
      "startTime",
      "endTime",
      "maxBid",
      "budgetDay",
      "budgetTotal",
      "impressions",
      "clicks"
    ],
    "timezoneId": 29,
    "requestType": 1,
    "reportSchedulingEventDetails": {
      "eventId": 18,
      "deliveryFrequency": 3,
      "fileType": 2,
      "subscriberEmails": [
        "demoUser1@gmail.com",
        "demoUser2@iqm.com"
      ],
      "eventEndDate": 1671148799,
      "deliveryDay": "Friday",
      "runningTotalEnabled": 0,
      "earliestCampaignStartDate": 0
    }
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          reportName: string;
          startDate: number;
          endDate: number;
          dimensions: string;
          columns: string[];
          timezoneId: number;
          requestType: number;
          reportSchedulingEventDetails: {
            eventId: number;
            deliveryFrequency: number;
            fileType: number;
            subscriberEmails: string[];
            eventEndDate: number;
            deliveryDay: string;
            runningTotalEnabled: number;
            earliestCampaignStartDate: number;
          }
        }
      }
    };
  };
};

function getReport(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ra/reports/{reportId}',
    params: {
      path?: {
        reportId: `number`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Reports Management

This section covers the various methods and endpoints for managing Reports.

See the quickstart guide on Creating a Report.

Resource Properties

`id` integer	Gets data for this Report ID
`dimensions` serialized JSON string	Represents dimension details serialized as a string
`columns` array of strings	Metrics for showing serving result
`customerIds` array of integers	Gets data for these customer IDs
`filters` serialized JSON string	Serialized string. Supports: `campaignId`, `creativeTypeId`, and `campaignStatus`
`searchField` string	Filters data by keyword
`requestType` integer	Denotes Daily (`1`) or Aggregate (`2`) Report request
`reportAggregated` string	Identifies whether Report is Aggregated (`1`) or not (`0`)
`startDate` integer	Unix epoch timestamp, milliseconds
`endDate` integer	Unix epoch timestamp, milliseconds
`timezoneId` integer	Timezone ID
`timezoneName` string	Timezone name
`sortBy` string	Sorts by ascending (`+`) or descending (`-`), default: `-impressions`
`pageNo` integer	Page number for the data, default: `1`
`noOfEntries` integer	Maximum number of entries returned, default: `50`

Create Report

POST api/v3/ra/report/add

Create a new Report based on given fields (see Resource Properties).

JSON
TypeScript

Request Sample
{
    "reportName": "Campaign by Gender by Device type with customer and filtering",
    "customerIds": [
        200,
        201
    ],
    "startDate": 1650177200000,
    "endDate": 1666938296000,
    "dimensions": "[{\"filter\":\"campaign\",\"value\":[123,234,345,456]},{\"filter\":\"gender\",\"value\":[10200002]},{\"filter\":\"device_type\",\"value\":[20300001,20300003]}]",
    "columns": [
        "gender",
        "deviceType",
        "campaignId",
        "campaignName",
        "startTime",
        "endTime",
        "maxBid",
        "budgetDay",
        "budgetTotal",
        "impressions",
        "clicks"
    ],
    "requestType": 1,
    "reportAggregated": "0",
    "timezoneId": 29,
    "timezoneName": "US/Eastern",
    "reportSchedulingEventDetails": {
        "runningTotalEnabled": 0,
        "deliveryFrequency": 3,
        "deliveryDay": "Friday",
        "fileType": 2,
        "subscriberEmails": [
            "demoUser1@gmail.com",
            "demoUser1@gmail.com"
        ],
        "eventEndDate": 1671148799999
    }
}

Response 200

{
    "success": true,
    "data": 1001
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: number;
      }
    };
  };
};

function saveReport(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ra/reports/add',
    requestBody: {
      content: {
        "application/json": {
          id?: `number`,
          reportName?: `string`,
          startDate?: `number`,
          endDate?: `number`,
          dimensions?: `string`,
          customerIds?: `array of numbers`,
          columns?: `array of strings`,
          timezoneId?: `number`,
          requestType?: `number`,
          reportAggregated?: `string`,
          owId?: `number`,
          createdByUOWId?: `number`,
          modifiedByUOWId?: `number`,
          timezoneName?: `string`,
          organizationName?: `string`,
          customerDetails?: [
            {
            owId?: `number`,
            organizationName?: `string`,
            organizationLogo?: `string`,
            statusId?: `number`,
            status?: `string`,
            supportEmail?: `string`,
            timezone?: `number`,
            organizationType?: `string`,
            }
          ],
          reportSchedulingEventDetails?: {
            earliestCampaignStartDate?: `number`,
            reportId?: `number`,
            deliveryFrequency?: `number`,
            fileType?: `number`,
            subscriberEmails?: `array of strings`,
            eventEndDate?: `number`,
            deliveryDay?: `string`,
            runningTotalEnabled?: `boolean`,
          }
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Execute a Report

POST api/v3/ra/report/execute

Once a Report is created, execute it with this endpoint.

Request Schema
`id` integer	Executes Report by Report ID
`dimensions` JSON string	Dimensions to filter by in serialized JSON format
`columns` array of strings	List of metrics for the Report obtained from dimensions and metrics details API
`customerIds` array of integers	Customer IDs to add to Report
`filters` JSON string	Supports `campaignId`, `campaignStatus`, and `creativeTypeId` filtering
`searchField` string	Filters by searched keyword
`requestType` integer	ID for whether Report is daily (`1`) or aggregated (`2`)
`reportAggregated` string	ID for whether first Report dimension is aggregated (`1`) or not (`0`)
`startDate` integer	Unix epoch timestamp of start date for Report
`endDate` integer	Unix epoch timestamp of end date for Report
`timezoneId` integer	Timezone ID
`timezoneName` string	Timezone name
`sortBy` string	Sorts by ascending (`+`) or descending (`-`), default: `+impressions`
`pageNo` integer	Page number for the data, default: `1`
`noOfEntries` integer	Maximum number of entries returned, default: `50`

JSON
TypeScript

Request Sample
{
  "id": 1001
}

Response 200
{
  "success": true,
  "data": {
    "total": {
      "CTR": 0.26809,
      "date": null,
      "deviceTypeId": null,
      "VCR": 51.452171,
      "budgetDay": null,
      "gender": null,
      "budgetPacing": null,
      "dataCost": 0,
      "totalRecords": 135,
      "campaignTimezone": null,
      "eCPM": 4.503114298538752,
      "bidImpressions": 4678583,
      "startTime": null,
      "mediaSpent": 8485.86672119556,
      "eCPC": 1.6797044182889074,
      "deviceType": null,
      "startCount": 351095,
      "campaignType": null,
      "campaignId": null,
      "spent": 8485.86672119556,
      "impressions": 1884444,
      "eCPCV": 0.021560143713093907,
      "completeCount": 180646,
      "budgetTotal": null,
      "maxBid": null,
      "clicks": 5052,
      "endTime": null,
      "campaignName": null,
      "status": null
    },
    "data": [
      {
        "CTR": 0.2796,
        "date": "2022-01-30",
        "deviceTypeId": 20300001,
        "VCR": 0,
        "budgetDay": 0.07,
        "gender": "Unknown",
        "budgetPacing": true,
        "dataCost": 0,
        "totalRecords": null,
        "campaignTimezone": "America/Costa_Rica",
        "eCPM": 2.9999999999999996,
        "bidImpressions": 628344,
        "startTime": 1643428296,
        "mediaSpent": 457.09799999999996,
        "eCPC": 1.073,
        "deviceType": "Mobile",
        "startCount": 0,
        "campaignType": "cpm",
        "campaignId": 15474,
        "spent": 457.09799999999996,
        "impressions": 152366,
        "eCPCV": 0,
        "completeCount": 0,
        "budgetTotal": 1549,
        "maxBid": 3,
        "clicks": 426,
        "endTime": 1644192000,
        "campaignName": "Costa Rica MEMES COMPILADOS Profile: All Gender: All Ages: 18 to 45 Geo: Heredia, Alajuela, Cartago and San Jose",
        "status": "expired"
      },
      {
        "CTR": 0.2122,
        "date": "2022-01-30",
        "deviceTypeId": 20300001,
        "VCR": 0,
        "budgetDay": 0.21,
        "gender": "Unknown",
        "budgetPacing": true,
        "dataCost": 0,
        "totalRecords": null,
        "campaignTimezone": "America/Costa_Rica",
        "eCPM": 2.9999999999999996,
        "bidImpressions": 271620,
        "startTime": 1643423160,
        "mediaSpent": 418.48799999999994,
        "eCPC": 1.4138108108108107,
        "deviceType": "Mobile",
        "startCount": 0,
        "campaignType": "cpm",
        "campaignId": 15472,
        "spent": 418.48799999999994,
        "impressions": 139496,
        "eCPCV": 0,
        "completeCount": 0,
        "budgetTotal": 1548,
        "maxBid": 3,
        "clicks": 296,
        "endTime": 1644192000,
        "campaignName": "Costa Rica Universidad Latina Profile: All Gender: All Ages: 18 to 75 Geo: All Costa Rica",
        "status": "expired"
      },
      {
        "CTR": 0.1065,
        "date": "2022-01-30",
        "deviceTypeId": 20300001,
        "VCR": 0,
        "budgetDay": 0.43,
        "gender": "Unknown",
        "budgetPacing": true,
        "dataCost": 0,
        "totalRecords": null,
        "campaignTimezone": "America/Costa_Rica",
        "eCPM": 3.000024952590078,
        "bidImpressions": 239865,
        "startTime": 1643431623,
        "mediaSpent": 360.68699999999995,
        "eCPC": 2.8178671874999996,
        "deviceType": "Mobile",
        "startCount": 0,
        "campaignType": "cpm",
        "campaignId": 15477,
        "spent": 360.68699999999995,
        "impressions": 120228,
        "eCPCV": 0,
        "completeCount": 0,
        "budgetTotal": 1551,
        "maxBid": 3,
        "clicks": 128,
        "endTime": 1644192000,
        "campaignName": "Costa Rica TICOS AL DIA 24-25 ENE Profile: All Gender: All Ages: 18 to 25 and 60+ and over Geo: Heredia, Alajuela, Cartago and San Jose",
        "status": "expired"
      },
      {
        "CTR": 0.3118,
        "date": "2022-01-31",
        "deviceTypeId": 20300001,
        "VCR": 0,
        "budgetDay": 0.07,
        "gender": "Unknown",
        "budgetPacing": true,
        "dataCost": 0,
        "totalRecords": null,
        "campaignTimezone": "America/Costa_Rica",
        "eCPM": 2.9999999999999996,
        "bidImpressions": 280562,
        "startTime": 1643428296,
        "mediaSpent": 219.36299999999997,
        "eCPC": 0.9621184210526315,
        "deviceType": "Mobile",
        "startCount": 0,
        "campaignType": "cpm",
        "campaignId": 15474,
        "spent": 219.36299999999997,
        "impressions": 73121,
        "eCPCV": 0,
        "completeCount": 0,
        "budgetTotal": 1549,
        "maxBid": 3,
        "clicks": 228,
        "endTime": 1644192000,
        "campaignName": "Costa Rica MEMES COMPILADOS Profile: All Gender: All Ages: 18 to 45 Geo: Heredia, Alajuela, Cartago and San Jose",
        "status": "expired"
      },
      {
        "CTR": 0.3154,
        "date": "2022-01-30",
        "deviceTypeId": 20300001,
        "VCR": 0,
        "budgetDay": 1,
        "gender": "Unknown",
        "budgetPacing": true,
        "dataCost": 0,
        "totalRecords": null,
        "campaignTimezone": "America/Costa_Rica",
        "eCPM": 3,
        "bidImpressions": 233754,
        "startTime": 1643131598,
        "mediaSpent": 211.161,
        "eCPC": 0.9511756756756757,
        "deviceType": "Mobile",
        "startCount": 0,
        "campaignType": "cpm",
        "campaignId": 15455,
        "spent": 211.161,
        "impressions": 70387,
        "eCPCV": 0,
        "completeCount": 0,
        "budgetTotal": 1749,
        "maxBid": 3,
        "clicks": 222,
        "endTime": 1644192000,
        "campaignName": "Costa Rica MEMES COMPILADOS Profile: Undecided Gender: All Ages: 18 to 35 Geo: Heredia, Alajuela, Cartago, San Jose",
        "status": "expired"
      }
    ],
    "totalRecords": 135
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          total: {
            CTR: number;
            date: number;
            deviceTypeId: number;
            VCR: number;
            budgetDay: string;
            gender: string;
            budgetPacing: boolean;
            dataCost: number;
            totalRecords: number;
            campaignTimezone: string;
            eCPM: number;
            bidImpressions: number;
            startTime: number;
            mediaSpent: number;
            eCPC: number;
            deviceType: string;
            startCount: number;
            campaignType: string;
            spent: number;
            impressions: number;
            eCPCV: number;
            completeCount: number;
            budgetTotal: number;
            maxBid: number;
            clicks: number;
            endTime: number;
            campaignName: string;
            status: string;
          };
          data: {
            CTR: number;
            date: number;
            deviceTypeId: number;
            VCR: number;
            budgetDay: string;
            gender: string;
            budgetPacing: boolean;
            dataCost: number;
            totalRecords: number;
            campaignTimezone: string;
            eCPM: number;
            bidImpressions: number;
            startTime: number;
            mediaSpent: number;
            eCPC: number;
            deviceType: string;
            startCount: number;
            campaignType: string;
            spent: number;
            impressions: number;
            eCPCV: number;
            completeCount: number;
            budgetTotal: number;
            maxBid: number;
            clicks: number;
            endTime: number;
            campaignName: string;
            status: string;
          }[];
          totalRecords: number
        }
      }
    };
  };
};

function executeReportData(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ra/reports/execute',
    requestBody: {
      content: {
        "application/json": {
          id?: `number`;
          reportName?: `string`,
          startDate?: `number`,
          endDate?: `number`,
          dimensions?: `string`,
          customerIds?: `array of numbers`,
          columns?: `array of strings`,
          timezoneId?: `number`,
          requestType?: `number`,
          reportAggregated?: `string`,
          owId?: `number`,
          createdByUOWId?: `number`,
          modifiedByUOWId?: `number`,
          timezoneName?: `string`,
          organizationName?: `string`,
          resultType?: `string`,
          fileType?: `number`,
          filters?: {
            [key: `string`]: Record<`string`, never>[],
          },
          pageNo?: `number`,
          noOfEntries?: `number`,
          sortBy?: `string`,
          searchField?: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Delete a Report

DELETE /api/v3/ra/report/{reportId}

Delete a Report and its scheduling data by ID.

Path Parameters
`reportId` integer	Report ID

JSON
TypeScript

Response 200
{
    "success": true,
    "data": "Report with id 123 deleted successfully"
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string
      }
    }
  };
};

function DeleteReport(): Promise < Responses > {
  const options = {
    method: 'DELETE',
    url: 'https://app.iqm.com/api/v3/ra/report/{reportId}',
    params: {
     path: {
      reportId: `number`
     }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Edit a Report

PATCH /api/v3/ra/report/{reportId}

Edit a Report's data based on given field.

Path Parameter
`reportId` integer	Report ID

Request Schema

customerIds
array of integers Customer IDs to add to Report. Parameter only available to update by workspace users or users with customers

startDate
integer Unix epoch timestamp of start date for Report

endDate
integer Unix epoch timestamp of end date for Report

reportName
string Updated Report name

timezoneId
integer Timezone ID

timezoneName
string Timezone name

dimensions
serialized JSON string Dimensions to filter by in serialized JSON format

columns
array of strings List of metrics for the Report obtained from dimensions and metrics details API

requestType
integer ID for whether Report is daily (1) or aggregated (2)

reportAggregated
integer ID for whether first Report dimension is aggregated (1) or not (0)

reportSchedulingEventDetails
object Contains parameters for updating scheduling details

reportSchedulingEventDetails object properties

`eventId` integer	ID for schedule event
`deliveryFrequency` integer	Delivery frequency type ID Once: `1` Daily: `2` Weekly: `3` Monthly: `4`
`fileType` integer	Report file type ID CSV: `1` XLS: `2`
`subscriberEmails` array of strings	List of emails to which the Report will be sent
`eventEndDate` integer	Unix epoch timestamp of Report schedule event end date, in milliseconds
`deliveryDay` string	[Required, if `deliveryFrequency` is not "once"] Delivery day to specify the day-time when the Report should be sent. Weekly delivery day: [`sunday`, `monday`, ...] Monthly delivery day: [`first`, `last`, `2`,`3`, ... `29`]

JSON
TypeScript

Request Sample
{
   "startDate":1727798981000,
   "endDate":1730304581000,
   "reportName": "new Report",
   "dimensions":"[{\"filter\":\"ioName\"},{\"filter\":\"campaign\"}]",
   "columns":[
      "impressions",
      "clicks",
      "CTR",
      "VCR",
      "spent",
      "dataCost",
      "mediaSpent",
      "eCPM"
   ],
   "requestType":2,
   "reportAggregated":"0",
   "timezoneName":"US/Eastern",
   "timezoneId":29
}

Response 200
{
    "success": true,
    "data": "Report with id 123 updated successfully"
}

Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "User does not have access for Report's customers"
        }
    ]
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string
      }
    }
  };
};

function UpdateReport(): Promise < Responses > {
  const options = {
    method: 'PATCH',
    url: 'https://app.iqm.com/api/v3/ra/report/{reportId}',
    params: {
     path: {
      reportId: `number`
     }
    },
    requestBody: {
      content: {
        "application/json": {
          customerIds?: `array of numbers`,
          startDate?: `number`,
          endDate?: `number`,
          reportName?: `string`,
          timezoneId?: `number`,
          timezoneName?: `string`,
          dimensions?: `string`,
          columns?: `array of strings`,
          requestType?: `number`,
          reportAggregated?: `number`,
          reportSchedulingEventDetails?: {
            eventId?: `number`,
            deliveryFrequency?: `number`,
            fileType?: `number`,
            subscriberEmails?: `array of strings`,
            eventEndDate?: `number`,
            deliveryDay?: `string`,
          }
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Duplicate a Report

POST /api/v3/report/duplicate

Create a copy of a Report with its ID.

Request Schema
`reportId` integer	Report ID to duplicate
`reportName` string	Name for duplicated Report

JSON
TypeScript

Request Sample
{
    "id": 123,
    "reportName": "Report name"
}

Response 200
{
    "success": true,
    "data": "Report duplicated successfully with id 124"
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string
      }
    }
  };
};

function duplicateReport(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/report/duplicate',
    params: {
     path: {
      reportId: `number`
     }
    },
    requestBody: {
      content: {
        "application/json": {
          id?: `number`,
          reportName?: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Scheduling Management

This section covers the various methods and endpoints for managing scheduled Reports.

See the quickstart guide on Scheduling a Report.

Schedule a Report

POST /api/v3/ra/report/email/schedule

Create and save a Report schedule.

Request Schema
`reportId` integer	Report ID
`subscriberEmails` array of strings	List of emails to which the Report will be sent
`fileType` integer	Report file type ID CSV: `1` XLS: `2`
`deliveryFrequency` integer	Delivery frequency type ID Once: `1` Daily: `2` Weekly: `3` Monthly: `4`
`deliveryDay` string	[Required, if `deliveryFrequency` is not "once"] Delivery day to specify the day-time when the Report should be sent. Weekly delivery day: [`sunday`, `monday`, ...] Monthly delivery day: [`first`, `last`, `2`,`3`, ... `29`]
`eventEndDate` integer	[Required if `deliveryFrequency` is not "once"] Unix epoch timestamp, time when scheduled Report will stop
`runningTotalEnabled` boolean	Flag to indicate if the 'Total' Running is enabled for the Report. Only supported with 'Campaign' dimension. If `true`, start date for Report will be earliest Campaign start date, ending with Report end date
`earliestCampaignStartDate` integer	[Required with `runningTotalEnabled` as `true`] Unix epoch timestamp, milliseconds. This is the Campaign's earliest start date from the selected Campaigns, which will be set as the start date of the Report-time-period

JSON
TypeScript

Request Sample
{
  "reportId": 1234,
  "subscriberEmails": [
    "sample_email1@example.com",
    "sample_email2@example.com"
  ],
  "fileType": 2,
  "deliveryFrequency": 4,
  "eventEndDate": 1670674106000,
  "deliveryDay": "4",
  "runningTotalEnabled": true,
  "earliestCampaignStartDate": 1670674108900
}

Response 200
{
  "success": true,
  "data": {
    "scheduledData": {
      "earliestCampaignStartDate": 0,
      "reportId": 1234,
      "deliveryFrequency": 4,
      "fileType": 1,
      "subscriberEmails": [
        "sample_email@sample.com",
        "sample_email2@sample.com"
      ],
      "eventEndDate": 1696270980000,
      "deliveryDay": "5",
      "runningTotalEnabled": false
    },
    "message": "Report schedule has been successfully updated."
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          scheduledData: {
            earliestCampaignStartDate: string;
            reportId: number;
            deliveryFrequency: number;
            fileType: number;
            subscriberEmails: string[];
            eventEndDate: number;
            deliveryDay: number;
            runningTotalEnabled: boolean;
          };
          message: string;
        }
      }
    };
  };
};

function saveReportScheduleEvent(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ra/report/email/schedule',
    requestBody: {
      content: {
        "application/json": {
          earliestCampaignStartDate?: `number`,
          reportId?: `number`,
          deliveryFrequency?: `number`,
          fileType?: `number`,
          subscriberEmails?: `array of strings`,
          eventEndDate?: `number`,
          deliveryDay?: `string`,
          runningTotalEnabled?: `boolean`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Update a Report Schedule

PATCH /api/v3/ra/report/email/schedule/{reportId}

Update a Report schedule.

Path Parameters
`reportId` integer	Report ID

Include whichever fields to be updated in the request body:

Request Schema
`subscriberEmails` array of strings	List of emails to which the Report will be sent
`fileType` integer	Report file type ID CSV: `1` XLS: `2`
`deliveryFrequency` integer	Delivery frequency type ID Once: `1` Daily: `2` Weekly: `3` Monthly: `4`
`deliveryDay` string	[Required, if `deliveryFrequency` is not "once"] Delivery day to specify the day-time when the Report should be sent. Weekly delivery day: [`sunday`, `monday`, ...] Monthely delivery day: [`first`, `last`, `2`,`3`, ... `29`]
`eventEndDate` integer	[Required if `deliveryFrequency` is not "once"] Unix epoch timestamp, time when scheduled Report will stop
`runningTotalEnabled` boolean	Flag to indicate if the 'Total' Running is enabled for the Report. Only supported with 'Campaign' dimension. If `true`, start date for Report will be earliest Campaign start date, ending with Report end date
`earliestCampaignStartDate` integer	[Required with `runningTotalEnabled` as `true`] Unix epoch timestamp, milliseconds. This is the Campaign's earliest start date from the selected Campaigns, which will be set as the start date of the Report-time-period

JSON
TypeScript

Request Sample
{
  "subscriberEmails": [
    "sample_email1@example.com",
    "sample_email2@example.com",
    "sample_email3@example.com"
  ]
}

Response 200
{
  "success": true,
  "data": {
    "scheduledData": {
      "earliestCampaignStartDate": 0,
      "reportId": 1234,
      "deliveryFrequency": 4,
      "fileType": 1,
      "subscriberEmails": [
        "sample_email1@example.com",
        "sample_email2@example.com",
        "sample_email3@example.com"
      ],
      "eventEndDate": 1696270980000,
      "deliveryDay": "4",
      "runningTotalEnabled": false
    },
    "message": "Report schedule has been successfully updated."
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          scheduledData: {
            earliestCampaignStartDate: number;
            reportId: number;
            deliveryFrequency: number;
            fileType: number;
            subscriberEmails: string[];
            eventEndDate: number;
            deliveryDay: string;
            runningTotalEnabled: boolean;
          }
          message: string;
        }
      }
    };
  };
};

function updateReportScheduleEvent(): Promise < Responses > {
  const options = {
    method: 'PATCH',
    url: 'https://app.iqm.com/api/v3/ra/report/email/schedule/{reportId}',
    params: {
      path: {
        reportId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          earliestCampaignStartDate?: `number`,
          reportId?: `number`,
          deliveryFrequency?: `number`,
          fileType?: `number`,
          subscriberEmails?: `array of strings`,
          eventEndDate?: `number`,
          deliveryDay?: `string`,
          runningTotalEnabled?: `boolean`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Delete Report Schedule

DELETE /api/v3/ra/report/email/schedule/{reportId}

Remove a Report schedule.

Path Parameters
`reportId` integer	Report ID

JSON
TypeScript

Response 200
{
    "success": true,
    "data": {
        "message": "Report event is removed."
    }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          message: string
        }
      }
    };
  };
};

function deleteReportScheduleEvent(): Promise < Responses > {
  const options = {
    method: 'DELETE',
    url: 'https://app.iqm.com/api/v3/ra/report/email/schedule/{reportId}',
    params: {
      path: {
        reportId: `number`
      }
    },
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Unsubscribe an Email from All Scheduled Reports

GET /api/v3/ra/report/email/schedule/unsubscribe-all

Unsubscribe an email from all scheduled Reports or an organization.

Query Parameters
`token` string	Generated on the server when populating the email template dispatched to the end user. End user is able to unsubscribe the email address by opening the link in browser

Unsubscribe an Email from a Report Schedule

GET /api/v3/ra/report/email/schedule/unsubscribe

Unsubscribe an email from a Report schedule.

Query Parameters
`token` string	Generated on the server when populating the email template dispatched to the end user. End user is able to unsubscribe the email address by opening the link in browser

Get More Report Details

This section covers more endpoints for getting various details about Reports.

Get URL for Report Download

POST /api/v3/ra/report/download

Run a Report and get a S3 file URL for download.

Refer to the Resource Properties table for request schema supported parameters.

JSON
TypeScript

Request Sample
{
    "id": 123
}

{
    "success": true,
    "data": {
        "url": "https://bucketname.s3.amazonaws.com/csv/123/reportname__1677643612992.csv"
    }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          url: string
        }
      }
    };
  };
};

function DownloadReport(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ra/report/download',
    requestBody: {
      content: {
        "application/json": {
          url: `string`,
          fileName: `string`,
          method: `string`,
          headers: {
            "Base-Url": `string`,
          },
          data: {
            id: `string`,
            page_number: `number`,
            total_count: `number`,
            request_type: `string`,
            sort_by: `string`,
            dataPath: `string`,
            dateRange: {
              start: `number`,
              end: `number`,
            };
            sort_type: `string`,
          },
          columns: [
            {
              label: `string`,
              value: `string`,
            }
          ],
          token: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get a List of Conversion's Custom Fields

POST /api/v3/ra/conversion/custom-field/list

Get a list of Conversion's custom fields by filter parameters.

Request Schema
`owIds` array of integers	Filters list by customer IDs, default is all assigned customers
`searchField` string	Filters by keyword or ID
`sortBy` string	Sorts by ascending (`+`) or descending (`-`), default: `-id`
`pageNo` integer	Page number for the data, default: `1`
`noOfEntries` integer	Maximum number of entries returned, default: `20`

Custom Fields IDs
`3114`	Pixel Conversion 1
`3221`	Pixel Conversion 2

JSON
TypeScript

Request Sample
{
  "customerIds": [
    123,
    234,
    345
  ],
  "pageNo": 1,
  "noOfEntries": 30,
  "sortBy": "+id",
  "searchField": "Pixel"
}

Response 200
{
  "success": true,
  "data": {
    "totalRecords": 10,
    "filterRecords": 3,
    "customFieldData": [
      {
        "id": 3114,
        "pixelName": "Pixel Conversion 1",
        "customFieldName": "sample_one"
      },
      {
        "id": 3114,
        "pixelName": "Pixel Conversion 1",
        "customFieldName": "sample_two"
      },
      {
        "id": 3221,
        "pixelName": "Pixel Conversion 2",
        "customFieldName": "product_sales"
      }
    ]
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          filterRecords: number;
          customFieldData: {
            id: number;
            pixelName: string;
            customFieldName: string;
          }[]
        }
      }
    };
  };
};

function getConversionCustomFieldsDetailsList(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ra/conversion/custom-field/list',
    requestBody: {
      content: {
        "application/json": {
          searchBy?: `array of strings`,
          owIds?: `array of numbers`,
          pagination?: `string`,
          pageNo?: `number`,
          noOfEntries?: `number`,
          sortBy?: `string`,
          searchField?: `string`,
          order?: [ "asc" | "desc" ],
          offset?: `number`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get Report Request Types

GET /api/v3/rb/static/report-request-type

Get a static list of Report request type.

Request Type IDs
`1`	Daily
`2`	Aggregated

JSON
TypeScript

Response 200
{
    "success": true,
    "data": [
        {
        "name": "daily",
        "id": 1,
        "label": "Daily"
        },
        {
        "name": "total",
        "id": 2,
        "label": "Aggregated"
        }
    ]
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          name: string;
          id: number;
          label: string;
        }[]
      }
    };
  };
};

function getRequestType(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/rb/static/report-request-type',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get Report File Types

GET /api/v3/rb/static/report-file-type

Get a static list of Report file types.

Report File Type IDs
`1`	CSV
`2`	XLS

JSON
TypeScript

Response 200
{
  "success": true,
  "data": [
    {
      "name": "csv",
      "id": 1,
      "label": "CSV"
    },
    {
      "name": "xlsx",
      "id": 2,
      "label": "XLS"
    }
  ]
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          name: string;
          id: number;
          label: string;
        }[]
      }
    };
  };
};

function getFileType(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/rb/static/report-file-type',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get Report Delivery Frequency Types

GET /api/v3/rb/static/report-delivery-frequency

Get a static list of Report delivery frequency types.

Delivery Frequency Type IDs
`1`	One time now
`2`	Daily until
`3`	Weekly until
`4`	Monthly until

JSON
TypeScript

Response 200
{
  "success": true,
  "data": [
    {
      "name": "One Time Now",
      "id": 1,
      "label": "One time now"
    },
    {
      "name": "DAY",
      "id": 2,
      "label": "Daily until"
    },
    {
      "name": "WEEK",
      "id": 3,
      "label": "Weekly until"
    },
    {
      "name": "MONTH",
      "id": 4,
      "label": "Monthly until"
    }
  ]
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          name: string;
          id: number;
          label: string;
        }[]
      }
    };
  };
};

function getDeliveryFrequency(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/rb/static/report-delivery-frequency',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get Dimensions and Metrics Details

GET /api/v3/ra/report/dimension-metrics/detail

Get dimensions and metrics information grouped by category (see Complete Table).

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "metrics": [
      {
        "Budget": [
          {
            "id": 1,
            "label": "Daily Budget",
            "order": 1,
            "fieldDataType": "currencyUSD",
            "aggregationType": "sum",
            "description": "Amount up to which you allow platform to spend on average each day",
            "defaultEnabled": false,
            "key": "dailyBudget",
            "dependentDimensions": [
              1,
              2,
              43,
              44
            ]
          },
          {
            "id": 2,
            "label": "Total Budget",
            "order": 2,
            "defaultEnabled": false,
            "key": "totalBudget",
            "dependentDimensions": [
              1,
              2,
              43,
              44
            ]
          }
        ]
      },
      {
        "Counts": [
          {
            "id": 5,
            "label": "Impressions",
            "order": 1,
            "defaultEnabled": true,
            "key": "impressions",
            "dependentDimensions": null
          }
        ]
      }
    ],
    "dimensions": [
      {
        "Campaign Specifics": [
          {
            "id": 1,
            "label": "Campaign",
            "order": 1,
            "isFilterSupported": true,
            "isRowToColumn": false,
            "isCustomerDependent": true,
            "fieldDataType": "text",
            "description": "Campaign Name",
            "groupId": 1,
            "key": "campaign"
          },
          {
            "id": 2,
            "label": "Campaign ID",
            "order": 2,
            "isFilterSupported": true,
            "isRowToColumn": false,
            "isCustomerDependent": true,
            "fieldDataType": "text",
            "description": "Unique system-generated number assigned to each Campaign",
            "groupId": 1,
            "key": "campaignId"
          }
        ]
      },
      {
        "Locations": [
          {
            "id": 34,
            "label": "Country",
            "order": 1,
            "isFilterSupported": true,
            "isRowToColumn": false,
            "isCustomerDependent": false,
            "fieldDataType": "country",
            "description": "Country the ad ran in",
            "groupId": 29,
            "key": "country"
          },
          {
            "id": 35,
            "label": "State",
            "order": 2,
            "isFilterSupported": true,
            "isRowToColumn": false,
            "isCustomerDependent": false,
            "fieldDataType": "regionCode",
            "description": "State the ad ran in",
            "groupId": 30,
            "key": "state"
          }
        ]
      }
    ]
  }
}

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          metrics: {
            budget: {
              id: number;
              label: string;
              order: number;
              fieldDataType: string;
              aggregationType: string;
              description: string;
              defaultEnabled: boolean;
              key: string;
              dependentDimensions: number[];
            }[];
            counts: {
              id: number;
              label: string;
              order: number;
              defaultEnabled: boolean;
              key: string;
              dependentDimensions: number[];
            }[];
          }[];
          dimensions: {
              Campaign Specifics: {
              id: number;
              label: string;
              order: number;
              isFilterSupported: boolean;
              isRowToColumn: boolean;
              isCustomerDependent: boolean;
              fieldDataType: string;
              description: string;
              groupId: number;
              key: string;
            }[];
            Locations: {
              id: number;
              label: string;
              order: number;
              isFilterSupported: boolean;
              isRowToColumn: boolean;
              isCustomerDependent: boolean;
              fieldDataType: string;
              description: string;
              groupId: number;
              key: string;
            }[]
          }
        }
      }
    };
  };
};

function getDimensionAndMetricDetails(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ra/report/dimension-metrics/detail',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Overview​

Authentication​

Get Reports Details​

Get a List of Reports​

Get Report by ID​

Reports Management​

Resource Properties​

Create Report​

Execute a Report​

Delete a Report​

Edit a Report​

Duplicate a Report​

Scheduling Management​

Schedule a Report​

Update a Report Schedule​

Delete Report Schedule​

Unsubscribe an Email from All Scheduled Reports​

Unsubscribe an Email from a Report Schedule​

Get More Report Details​

Get URL for Report Download​

Get a List of Conversion's Custom Fields​

Get Report Request Types​

Get Report File Types​

Get Report Delivery Frequency Types​

Get Dimensions and Metrics Details​

Overview

Authentication

Get Reports Details

Get a List of Reports

Get Report by ID

Reports Management

Resource Properties

Create Report

Execute a Report

Delete a Report

Edit a Report

Duplicate a Report

Scheduling Management

Schedule a Report

Update a Report Schedule

Delete Report Schedule

Unsubscribe an Email from All Scheduled Reports

Unsubscribe an Email from a Report Schedule

Get More Report Details

Get URL for Report Download

Get a List of Conversion's Custom Fields

Get Report Request Types

Get Report File Types

Get Report Delivery Frequency Types

Get Dimensions and Metrics Details