Skip to main content

Create a Contextual audience

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

The following endpoints are used to create a Contextual audience:

POST
POST
GET

About IQM Contextual audiences​

IQM's Contextual audience allows you to make groupings of users based on their online activity. By specifying keywords and/or URLs, IQM builds a Contextual audience as users visit sites relevant to those parameters within a target timeframe.

Contextual audiences have two kinds of data collection periods:

  • static - a timeframe set between two dates in the last 180 days with a maximum 90 day period
  • dynamic - a rolling timeframe of up to the last 90 days from today with data refreshing every 24 hours

More resources​

Before you begin​

To create a Contextual audience, the following is required:

  1. An account on the IQM platform
    • See Before you begin section to create an account and request a Client ID and Client Secret

Create a Contextual audience using the IQM API​

This quickstart guide covers how to create a Contextual audience using both keywords and URLs and each type of data collection period.

The minimum requirements to perform this task are: logging in with authentication credentials, creating a Contextual audience, and checking the audience status. 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 Contextual audience
  3. Check the audience status

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		Client ID and Client Secret
Content-Type
string required		application/x-www-form-urlencoded
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 Contextual audience​

POST

You can determine how a Contextual audience forms groupings by indicating a list of relevant keywords and/or URLs. IQM adds users to the Contextual audience when they visit a site relevant to those keywords or URLs.

The request schema table below details the supported fields for creating a Contextual audience. Steps 2a and 2b detail two different ways to perform this action, however keywords and URLs can also be used together to create a Contextual audience.

Request schema
audienceName
string		Audience name
keywords
string		Keywords to generate a Contextual audience
startDate
integer		Unix epoch start date, in milliseconds (required if data collection method is static)
endDate
integer		Unix epoch start date, in milliseconds (required if data collection method is static)
frequency
integer		The number of times a user visits the publisher(s) relevant to one or more keywords or URLs added to the Contextual audience. Integer between 1-10
urls
string		The publisher sites visited by a user
timezoneId
integer		Timezone ID specifies data collection start time
dataCollectionMethodId
integer		static (1) collection period in a fixed set of dates
dynamic (2) data collection period over a rolling timeframe, with data refreshes every 24 hours
dataCollectionDays
integer		Number of days for data collection timeframe when data collection method is dynamic (maximum value: 90)

Step 2a: Contextual audience with keywords​

You can create a Contextual audience with keywords and just a few other parameters. You need to pass an audienceName and select one or more keywords. In the provided request sample (seen in the code block in the right-side column) the chosen keywords are "politics", "voters", and "california".

Next you need to decide a frequency from 1-10. This determines how many times a user must visit a site relevant to the chosen keywords to be added to the Contextual audience.

A Contextual audience also requires specifying a timeframe for data collection. In this example you can choose a static data collection method by passing 1 as the dataCollectionMethodId. This method requires Unix Epoch values for the startDate and endDate fields.

info

The start date of a Contextual audience must be within the last 180 days.

Contextual audiences support a static or dynamic data collection period of up to 90 days.

Lastly, a timezone ID is required to determine the data collection timeframe. An ID of 29 designates EST timezone.

Request sample
{
  "audienceName": "California Politics",
  "frequency": 5,
  "keywords": "politics, voters, california",
  "dataCollectionMethodId": 1,
  "startDate": 1750737600000,
  "endDate": 1753329599000,
  "timezoneId": 29,
}
Response 200
{
  "success": true,
  "data": {
    "id": 1078146,
    "message": "Contextual Audience created successfully"
  }
}

Step 2b: Contextual audience with URLs​

You can also create a Contextual audience with URLs. You need to pass the desired websites as a string in the urls field.

As in Step 2a, you need to pass integers for frequency and timezoneId.

In this example you can choose a dynamic data collection method by passing 2 as the dataCollectionMethodId. This method requires passing a period of days (1-90) in the dataCollectionDays field.

Request sample
{
  "audienceName": "California Politics",
  "frequency": 5,
  "urls": "www.iqm.com",
  "dataCollectionMethodId": 2,
  "dataCollectionDays": 20,
  "timezoneId": 29,
}
Response 200
{
  "success": true,
  "data": {
    "id": 1078146,
    "message": "Contextual Audience created successfully"
  }
}

Step 3: Check audience status​

GET

You can check on the audience status after creation to see if it's "Ready" or still "Processing". This endpoint also returns various details about the audience as described in the Response properties table below.

Use the id from Steps 2a or 2b and pass it as the audienceId in the endpoint path to get the audience's details.

Path parameter
audienceId
string		Audience ID
Response properties
id
integer		Audience ID
name
string		Audience name
status
string		Audience status
type
integer		Audience type ID.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
includedCount
integer		Count of campaigns including this audience
excludedCount
integer		Count of campaigns excluding this audience
createdOn
integer		Unix epoch creation date, in milliseconds
organizationName
string		Organization name
owId
integer		Organization Workspace ID
createdByUowId
integer		Created by user Organization Workspace ID
createdByUser
string		Created by user name
uniques
integer		Count of unique audiences reached
dataCost
integer		Fees charged by the platform if the audience is used in any campaign
keywords
string		Keywords
urls
integer		URLs
startDate
integer		Unix epoch start date, in milliseconds
endDate
integer		Unix epoch end date, in milliseconds
frequency
integer		Frequency
editAccess
boolean		Indicates if user has edit access for the requested resource
Response 200
{
  "success": true,
  "data": {
    "id": 1078361,
    "name": "USA",
    "status": "Processing",
    "type": 5,
    "includedCount": 0,
    "excludedCount": 0,
    "createdOn": 1719382932,
    "organizationName": "IQM Corporation",
    "owId": 202314,
    "createdByUowId": 117790,
    "createdByUser": "Neeraj Khatri",
    "createdByUserEmail": null,
    "uniques": 0,
    "dataCost": 1.5,
    "keywords": "law,act,actions",
    "urls": "",
    "startDate": 1718873084000,
    "endDate": 1719229978000,
    "frequency": 2,
    "editAccess": true
  }
}
Have a question?
Ask the community
Was this page helpful?