Skip to main content

Schedule a report

Create your first report schedule using IQM's API in this step-by-step quickstart guide.

Get started scheduling a report with the following endpoints:

POST
POST

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 includes the date as a dimension and provides 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.

More resources​

Schedule a report​

This quickstart guide covers 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

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.

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: Schedule a report​

POST

Decide the delivery frequency, day, and end date of scheduled reports. This API saves the delivery information and returns a success message.

For further information see Scheduling management.

Request schema
reportId
integer		The unique report ID, event is created on this report ID
subscriberEmails
array of strings		List of emails to which the report is sent
fileType
integer		Report file type ID. The report is sent in the selected file format.
Supported values
1CSV
2XLS
deliveryFrequency
integer		Delivery frequency type ID for the emails to be sent.
Supported values
1One time now
2Daily until
3Weekly until
4Monthly until
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, the scheduled report is 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 is 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."
  }
}
Have a question?
Ask the community
Was this page helpful?