Skip to main content

Schedule a Report

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

Get started scheduling a Report with the following endpoints:

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

About IQM Reports​

The IQM APIs provide access to all dimensions and KPIs of ad-serving Reporting data in JSON format.

Reports can be either daily or aggregated. The daily Report will include the date as a dimension and provide the data breakdown by date. Reports provide five top-level dimensions of filtering support, and can be filtered for multiple values in each dimension.

A Report can be run containing up to three months of data for any dimension combination or up to one year for the campaign dimension. Multiple Reports must be run if more than that amount of data are needed.

Schedule a Report​

This quick start guide will cover how to schedule a Report.

The minimum requirements to perform this task are: logging in with authentication credentials, and having a campaign started in order to execute Reports. 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. Schedule a Report
    • Execute scheduling event with frequency, day, and end date parameters

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.

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 Response Samples
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: Schedule a Report​

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

Decide the delivery frequency, day, and end date of scheduled Reports. This API will save the delivery information and return a success message.

For further information see the complete Scheduling Management Documentation for the Report API.

Request Schema
reportId
integer		The unique Report ID, event will be created on this Report ID
subscriberEmails
array of strings		List of emails to which the Report will be sent
fileType
integer		Report file type ID. The Report will be sent in the selected file format.
CSV: 1
XLS: 2
deliveryFrequency
integer		Delivery frequency type ID for the emails to be sent.
Once: 1
Daily: 2
Weekly: 3
Monthly: 4
deliveryDay
string		If delivery is not 'Once', specify the day/date when the Report should be sent.
Day: Sunday, Monday, ...
Monthly: First, Last, 1, 2, ..., 29
eventEndDate
integer		If delivery is not "Once", this should be a long, TIME EPOCH in UNIX format, in milliseconds. This is event's end date, Scheduled Report will be stopped after the eventEndDate is exceeded.
runningTotalEnabled
boolean optional		Flag to indicate if the 'Total' Running is enabled for the Report. This flag is supported only with 'Campaign' dimension. If this is true the start-date for the Report duration should be the EARLIEST campaign start date, so the Report-time-period will be from the Earliest-campaign-start-date to the Report-end-date.
earliestCampaignDate
integer		With runningTotalEnabled as true, this should be a unix epoch timestamp, in milliseconds. This is campaign's EARLIEST start date from the selected campaigns, which will be set as the start date of the Report-time-period.
Request Sample
{
  "reportId": 1235,
  "subscriberEmails": [
    "sample_email1@example.com",
    "sample_email2@example.com"
  ],
  "fileType": 2,
  "deliveryFrequency": 3,
  "eventEndDate": 1670674106000,
  "deliveryDay": "MONDAY",
  "runningTotalEnabled": true,
  "earliestCampaignStartDate": 1670674108900
}
Response 200
{
  "success": true,
  "data": {
    "scheduledData": {
      "earliestCampaignStartDate": 0,
      "reportId": 12345,
      "deliveryFrequency": 3,
      "fileType": 1,
      "subscriberEmails": [
        "sample_email@sample.com",
        "sample_email2@sample.com"
      ],
      "eventEndDate": 1696270980000,
      "deliveryDay": "MONDAY",
      "runningTotalEnabled": false
    },
    "message": "Report schedule has been successfully updated."
  }
}